samagotchi 0.149.0 → 0.151.0

data/docs/internals/bridge.md

@@ -15,7 +15,8 @@ rescues its own errors: an observer must never break the running turn.
 |-------|------------------|-------|
 | `RingBuffer` | `ring_buffer.rb` | The last `ring_capacity` (256) raw events by `event_seq`, in memory, for a reconnect's replay. The capture observer feeds it. |
 | `TurnAccumulator` | `turn_accumulator.rb` | The turn in progress, folded from events. |
-| `CardStore` | `card_store.rb` | The last cards and notices, saved in `cards.json`. |
+| `CardStore` | `card_store.rb` | The last cards and notices, saved in `cards.json`, each anchored to its turn. |
+| `CardPlaces` | `card_places.rb` | Pure: where `CardStore`'s entries sit in the messages the page draws (`turns_since`). |
 | `PendingCard` | `pending_card.rb` | `pending_card.json` `{id:, bundle:}`: the running turn's open card with actions (check-in's Nudge), written and removed with that card, so chi web's hub, which watches files and not workers, can notify. |
 
 Per connection there is an `SSEWriter` (with a `BoundedQueue`); `ClientEvent` and `EventId` are pure helpers. The
@@ -49,17 +50,60 @@ The cards a plugin or the Engine shows (`Engine#show_card`), hook notices, load
 the "asking again" and steer-cut rows, ✂ rows and questions (with how they were answered), for a UI that joins later:
 `snapshot[:cards]` and `GET /tail`'s `cards`.
 
-- **Placement is relative.** An entry carries `turns` and lists with `turns_since` (turns completed after it) and
-  `current` (a card of the running turn). A card that comes mid-turn but isn't the turn's (an anytime command's, such as
-  `/btw`) goes after that turn (`during`). A card with an earlier card's id replaces it in place.
+- **Anchored to its turn.** The store keeps a **turn log**, every id it saw at `:turn_started`, oldest first. An entry
+  holds `turn_id`: the running turn's, else the log's last (nil before any); a load warning, which the Engine announces
+  inside the first turn, takes the one before it. `list(messages:)` computes `turns_since` from the messages the page draws
+  (`CardPlaces`, the snapshot's own list; a stopped session's file for `.saved`): the turn openings (`Steer.turn_opening?`, as
+  the page's `TURN_PROMPT` and the recap count) after the last one whose id is in the log at or before the entry's, else from
+  the first one whose id is later in the log, else 0. The log only orders; the messages count. So a turn with no opening (a
+  reminder, a Continue, a failed or rolled-back one, a prompt stopped before the model) moves nothing, a wake's note does, and
+  an opening with no id (`/continue no`'s reason, Qwen's recovery line) counts as on the page. Nothing orders such an opening
+  against an entry, so the store reads the session's messages (its `messages:` lambda) when an entry is shown between turns, and
+  at the turn's end for what a running turn showed that isn't its own: `past_idless` is how many of them, right after the opening
+  it counts from, the entry already came after, and they don't count for it. A `!rollback` usually only shortens that run, and the count
+  is capped at the run still there, so a stale number doesn't eat a later turn. It can also move an entry's counting point back to a
+  run the entry never recorded (T1, `/continue no, too slow`, a card, a held T2 stopped, a second card, `!rollback`: the second card,
+  anchored to T2, now counts from T1 and reads above the reason and the first card). That rare inversion is accepted. A turn's own rows don't read it: they count such a line, which sits below them. `current` is a card of the running turn. A card that
+  comes mid-turn but isn't the turn's (an anytime command's, such as `/btw`) goes after that turn (`during`), and so does a
+  between-turns notice. A card with an earlier card's id replaces it in place and keeps its anchor. A `list` with no messages
+  (`?cards=1`'s bodies, `chi bundle try`'s trace) has no `turns_since`.
+- **A turn that leaves nothing** is read, not told: an in-turn entry not `current` whose turn has no opening in the messages
+  (a `!rollback`, a failed turn with nothing kept, a prompt stopped before the model) lists as a between-turns entry at its
+  place, a card without its actions and a hook's notice without its step; its other rows, having no step to sit in, aren't
+  listed. Nothing in the entry changes. A kept Continue or reminder turn never has an opening, so its entries are `continued`
+  and stay rows of the turn before; a failed one loses the mark at its end. The page draws a failed prompt at the history's
+  end, so an entry pushed idle after it lists `after_failed` (the store's saved `failed_turn`) and goes below it, until the
+  next turn starts.
+- **A command's card.** `SessionCommands#run` wraps its dispatch in `Engine#running_command`, so a card shown on that thread
+  carries `command:` (the event's field, `show_card` adds it). The store keeps the first show's (a replacement keeps it, even
+  none) and lists `label: "from /short"`, never `command`. The page draws it after a reload, where the command's line is gone.
 - **Caps.** `CAPACITY` (20) each for notices, ✂ rows (`LLM_CONTEXT_TYPES`) and cards, so one burst cannot push out
   another kind. An open question (an approval too) is never pushed out.
 - **Saved.** With a `path` (`cards.json` in the session's folder) the store rewrites the file after each event in
-  `SAVED_ON`, and a later worker's store starts from it, so a turn's cards outlive the worker; `CardStore.saved(dir)` is
-  what chi web reads for a session no worker runs. Load warnings are the worker's own (each start announces them)
-  and an unanswered question waits for no one: neither is saved or seeded. An entry from an earlier worker lists with
-  `earlier: true`; one shown during a turn comes back **without its actions** (their turn no longer runs), while a
-  between-turns card keeps its buttons.
+  `SAVED_ON`, and a later worker's store starts from it, so a turn's cards outlive the worker; `CardStore.saved(dir, messages:)`
+  is what chi web reads for a session no worker runs. The file is `{version: 2, turn_log:, entries:}`. The log is pruned at
+  a turn's start and end and at an idle show (a running turn's rows reuse the start's, as finding it walks the messages) to start at the opening the earliest anchor counts from (all of it while an entry has none, or for a store with no
+  `messages:`), so a restart reads an entry as the live store did; an old card therefore keeps it whole. `seed` drops an entry
+  whose `turn_id`, `base_since` or `past_idless` isn't an id or a non-negative integer. Load warnings
+  are the worker's own (each start announces them) and an unanswered question waits for no one: neither is saved or seeded. An
+  entry from an earlier worker lists with `earlier: true`; one shown during a turn comes back **without its actions** (their
+  turn no longer runs), while a between-turns card keeps its buttons.
+- **Version 1.** A file from before the log (top-level `turns`, each entry its own, maybe `running`) keeps its places, drift
+  included: `seed` turns each count into `base_since`, new openings add to it, and such an entry never reads as having left
+  nothing (no id to check). The next save writes version 2 with `base_since` kept. `SessionManager.cards_empty?` reads both.
+- **An older chi on a version 2 file.** Its `seed` wants an integer `turns`, finds none, and starts with no entries. A chi web not
+  yet restarted only reads: it lists no cards for that session until restarted, and the file stays whole. An older **writer** does
+  damage: at its first saved event, `:turn_started`, it writes `{"version":1,"turns":0,"running":true,"entries":[]}` over the file
+  (`{"version":1,"turns":1,"entries":[]}` after that first turn), so that session's cards go, and with them the answered approvals
+  `chi guardrails replay` reads. A plain upgrade doesn't reach this: a worker already running seeded before and keeps its own version 1
+  file, and a spawn runs the newest chi installed (`SessionManager.worker_command`), unless that activation raises LoadError: the boot
+  line then falls back to the spawner's or the home's pinned version, which can be older. Otherwise it takes an older process starting
+  on a session a newer one wrote: a downgrade, a chi home whose newest chi is older (`home_older_than_spawner`), or a REPL or `bin/chi`
+  from an older gem or checkout on the same state dir. Nothing on this side stops
+  it: an older chi can't be changed, and having it read the file would mean writing fake `turns` counters into every file.
+- **A killed turn needs nothing special.** `TurnCheckpoint` keeps a running turn's prompt in the session file, with its id from
+  the start (`Worker#run_engine_turn` settles it first), so it counts as any opening. A REPL keeps no running turn in the
+  session, so a kill takes the prompt along and there's nothing to count.
 
 ## SSEWriter
 

data/docs/internals/bundles.md

@@ -13,9 +13,14 @@ user-facing side (what a bundle owns, profiles, needs) is in [memory.md](../memo
   *.md, index.md                 the bundle's memories, one managed index line each ("· from <bundle>")
 <system memories>/.bundles/      MemoryPaths.bundles_dir
   <name>/manifest.json           the install record (Provenance#write, read as InstalledBundle)
-  <name>/bases/                  each file as installed: the base of the next upgrade's 3-way merge
+  <name>/bases/                  each file's base for the next upgrade's 3-way merge: as installed, or the
+                                 bundle's own text after a merge
+  <name>/incoming/               the bundle's text for each file marked conflict, until the file settles (Provenance:
+                                 #write, #refresh_marks, gone with #resolve_conflicts); nothing globs it for memories
+                                 (Builder takes the scope dir's top level), and an uninstall's rm_rf sweeps it
   <name>/hooks/ guardrails/ plugin/ scripts/
-  .trash/<name>-<stamp>/         files an uninstall or upgrade took away (Trash), never deleted
+  .trash/<name>-<stamp>/         files an uninstall or upgrade took away, and copies of what an install
+                                 overwrote (Trash), never deleted
 ```
 
 ## Components
@@ -35,15 +40,20 @@ user-facing side (what a bundle owns, profiles, needs) is in [memory.md](../memo
 | `MemoryFiles` | which top-level `*.md` files of a bundle are its memories (`.select`: the `files:` list, else all but README/LICENSE and the like), `.unshipped` (listed, not shipped) and `.symlinks` (skipped: a symlink is never a memory) |
 | `Manifest` | parses/validates `manifest.yml` (`name:` is the bundle's name and a directory under `.bundles/`, so a path such as `../x`, `a/b`, `.` or `..` is refused: `name: … is not a bundle name`; YAML that doesn't parse or isn't a mapping is a `ValidationError` too; files, hooks as `BundleHook`, plugin, scripts, needs, requires_chi, includes, context_providers, session_settings: the keys a session's `chi --set` may give, a list or a mapping of them to types (`SESSION_SETTING_TYPES`), recorded at install in `manifest.json` (`session_settings`, `session_setting_types`) for `SessionConfig` to check; settings: the keys config.yml's `bundles: <name>:` may have, the same shape, recorded as `settings` (nil when the manifest has none) and `setting_types` for `BundleSettingsCheck`, whose warnings the Engine holds for the first turn and `SessionConfig`'s refusals share the words of) and writes it (`Manifest.write`, for Builder). It ignores `requires_chi_next`, a shipped bundle's release-time marker (`script/release/release_tools.rb`, docs/releasing.md) |
 | `Installer` | one install/upgrade/dry run of one bundle (below) |
-| `AssetInstaller` | the parts that live in `.bundles/<name>/`: hooks, guardrail rules, plugin, scripts; returns `AssetInstaller::Installed` (the paths the record keeps) |
-| `Merger` | 3-way classification per file: `install`, `fast_forward`, `keep`, `noop`, `conflict` |
-| `Provenance` | the `.bundles/<name>/` dir: `#write` the record + bases, `#record` → `InstalledBundle`, `.each_installed`, `.claimants` (which bundles own a file) |
+| `AssetInstaller` | the parts that live in `.bundles/<name>/`: hooks, guardrail rules, plugin, scripts; returns `AssetInstaller::Installed` (the paths the record keeps). A file it replaces or removes whose bytes are neither the recorded sha nor the incoming file's is copied to the Installer's `Trash` first (`Trash#copy_edit`, `#copy_edits` for a folder at any depth, as `hooks/x`, `guardrails/x`, `plugin/x`, `scripts/sub/x`; no sha recorded counts as edited; a dev link never is) |
+| `Merger` | 3-way classification per file: `.classify` → an `Outcome` (`status`: `install`, `fast_forward`, `keep`, `noop`, `conflict`, `merged`; `base`: where the file's next base comes from, `:on_disk`, `:recorded` or `:incoming`; a new outcome and its base go in its constants, and it needs a branch in `Installer#merge_memory`, a kind in `#next_base` if its base is new, and its status word in `#preview_memory`, `#verify_memory_checksums` and `#summary`). `.classify` never merges and answers `conflict` for two changed sides; `Merger::Upgrade` (provenance, target dir, source dir) is the one way to ask what an upgrade does to a file, nothing written: `#outcome` (`.classify`, then `TextMerge` where both sides changed, git once per call: `merged`, with its `TextMerge::Result` and the digest it read as the Outcome's `merge` and `current_sha`; `ALREADY_MERGED`, a `keep` with base `:incoming`, when the merge adds nothing; or `conflict` with that `merge`, whose `why` says why none was possible), `#classified`, `#forecast` (a `Forecast` of `merged` and `behind` in one pass), `#behind` (a `conflict` outcome as a `FileStanding::Behind`: why, and from `TextMerge.changed_sections` what it missed, nothing for an older mark, whose base may be the user's text), `#paths`, used by the Installer's merge and dry run, `ShippedUpdate.plan` and `SystemBundle.sync(dry_run:)`. `.write_merged` puts a merge in place: the digest checked just before the rename (`AtomicFile.write`'s block), through a symlink, the mode kept, the old file in the `Trash`; false when a live `memory_write` got in. A mark from an older chi (`InstalledBundle.legacy_mark?`: no `incoming_sha`, or `legacy_base`, which keeps that known once the digest is recorded, until the mark goes) may have the user's own text as its base, 0.149's doing, and a merge against it would undo that text with nothing to show, or a fast-forward replace all of it: `#outcome` makes a fast-forward that takes a line out of the file, and `.merge_outcome` a merge that does, a `conflict` (`FileStanding::LEGACY_BASE`), on the Installer's and `Remerge`'s path alike, unless `ShippedHistory` proves the base is a version chi shipped. The price, with no such gem left or for a bundle chi doesn't ship: a real base looks the same, so such a file whose bundle rewords or removes a line it still holds stays behind until it is resolved by hand, with `--agent` or with `--force`; no retry fixes it. `Installer#save_marked_file` serves a fast-forward that goes ahead over a mark: a file put back to its base under this chi's mark, or an older mark with a proved base or an update that only adds. `.markers?` (a file holding a merge's `<<<<<<<`/`>>>>>>>` lines; `=======` alone is a Markdown underline) |
+| `ShippedHistory` | `.shipped?(bundle, file, path)`: whether those bytes are that file of that bundle (by manifest name, since a shipped dir can be renamed) in an installed `samagotchi-<version>` gem. Reads `<gem dir>/gems/` by hand, for `Gem.path` (set by a chi home's boot string) and the home's `gem_dirs` from home.json (a checkout or another Ruby runs on other gems), never `Gem::Specification`. Size, then bytes, then the manifest. Anything it can't read is no match, which keeps the guard. Asked only when `Merger`'s guard would otherwise fire: with 54 gems on the Studio a miss costs about 4 ms, a hit less |
+| `TextMerge` | the text merge: `.merge(base:, ours:, theirs:)` → a `Result` (`status` `:clean` with `text`, `:conflict` with `hunks`, `:failed` with `why`). `git merge-file -p --diff3 --marker-size=20` on temp copies in a temp cwd, with every `GIT_*` that points at a repository or a config unset or at `/dev/null` (it can run inside another tool's hook). git isn't a runtime dependency: none on PATH, or macOS's `/usr/bin/git` with no developer tools behind it (`.apple_stub?`, by `xcode-select -p`; running it pops a dialog), is `:failed`. So is a git past `TIMEOUT` (10 s; its process group is killed: this runs under `SystemBundle`'s lock), and any doubt about the answer: `min(hunks, 127)` against the exit status, a status over 127, a NUL in a side, marker lines that don't pair up (a user's line equal to one), a line no input holds, or an empty answer to non-empty inputs. `Scan` reads the output: a hunk unions (ours, then the entries of theirs that ours lacks) only when the last heading before it, at level 1 or 2 and outside code fences, HTML comments and any hunk, is titled exactly `Changelog` or `Change log`, with nothing but list entries (an item and its indented lines) since that heading and no fence or comment open, and base, ours and theirs each hold only list entries, with every base entry still on both sides: both only added. Any other hunk is a real conflict, and markers never leave the module. An entry is an item and the lines indented deeper under it, nested items too, and the union compares whole entries. `.changed_sections(base, theirs, ours)`: the headings of the sections the bundle changed and the file hasn't got, and whether text under no heading did, which is what names a miss: a conflict's hunks can't, since the whole file stays and the one hunk may be a Changelog line beside a whole new section. `Hunk#heading` counts the places under no heading |
+| `FileStanding` | the one owner of what chi says of an edited bundle file, used by every surface: `Behind` (`#state`, `#line`: `x.md stays behind 0.8.0: no merge possible (why); missed ## A, ## B, ## C and 2 more`, `would stay` in a dry run), `MergeNote`, `.merged_line`, `.no_merge` (for `LEGACY_BASE` it says chi can't tell whether the file holds edits), `.clauses` (a report's clauses for one bundle), `.behind_count`, `.stay_behind`, `.counts_sentence` (the push), `.still_behind`, `.text` (UTF-8, whatever a name or heading was tagged), `FORCE_TAKES`, `FORCE_MOVES`, `IN_THE_TRASH`. Behind means marked and bytes other than the mark's `incoming_sha` (`.behind?`, read by `InstalledBundle#behind_files` and `Remerge` alike): a file brought level by hand isn't, a missing one is a missing file, and one that can't be read is. An older mark no retry has looked at reads `may be behind` (`Behind#unsure`, and the counts say so), and isn't behind at all when level with its recorded source on disk (`InstalledBundle#behind_file?`). A new surface reads these and adds no wording |
+| `Remerge` | the retry at the same version, memory files only, for a file marked `conflict`: `#run(dry_run:)` → a `Result` (`merged`, `settled`, `stamped`, `behind`, `warnings`, `trash_copy`, `trash_dir`). It merges what merges and settles those entries (`Provenance#resolve_conflicts`, the index line refreshed), leaving `version`, `installed_at` and the assets alone: the Installer would `rm_rf` guardrails, plugin and scripts under live sessions. Every file it leaves is in `behind`, with why: one not shipped now (`MemoryFiles.select`) keeps its mark, base and text; one whose `incoming_sha` isn't the shipped text (a checkout at one VERSION) is left alone, no git runs, and it reads as its mark says; a mark with no digest (older chi) is tried as well, and a real conflict then records it (`Provenance#refresh_marks`, which writes only when the mark would read differently, so a conflict at each start writes nothing). A mark whose digest matches is tried on every run, since the file or git may have changed. `noop` and `keep` settle quietly; `fast_forward` waits for the next upgrade, reading as behind until then; `install` is a missing file, which isn't behind, and a warning says so. A file it can't read or replace stays as it is, saying why. Called from `ShippedUpdate.plan_row`/`apply` (`chi update`) and `SystemBundle.sync`'s equal-version branch, under its lock (each chi start and `chi update`); a bundle chi doesn't ship retries through `chi bundle upgrade`. No marks: nothing is read beyond the record. One marked file costs one git run per Engine start, about 12 ms on the Studio (0.1 ms with none) |
+| `Provenance` | the `.bundles/<name>/` dir: `#write` the record + bases (its `files:` is the full list: a key left out is dropped, a nil value keeps the entry with no base; `marks:` are the files left behind, each a `FileStanding::Behind`, and `incoming_dir:` the bundle text each speaks of, recorded as `incoming_sha` and saved at `#incoming_path`; an older mark that stays keeps `legacy_base`), `#resolve_conflicts` (base to the incoming file, mark and its fields (`MARK_FIELDS`) and saved text gone; a file whose incoming copy is gone keeps both), `#refresh_marks` (what a retry found: why, missed, the digest and `legacy_base`, the saved text), `#note_merged` and `#clear_merge_notes(notes)` (`MERGE_NOTE_FIELDS`, kept through `#write`; the saved text is best effort, after the manifest, so it can't leave a plugin under the old record's sha; any other failure writing the record still can, until a retry), `#record` → `InstalledBundle`, `.each_installed`, `.claimants` (which bundles own a file) |
 | `InstalledBundle`, `BundleHook`, `PluginRef` | value objects for the record; tolerant of older records (missing keys read as empty). `BundleHook#events` is the manifest's `event:` or its `events:` list (written back as `event:` for one, as an older chi reads it); `Hooks::BundleLoader#load_hook_file` builds the hook once and registers it under each |
+| `BlockRenderers` (`lib/samagotchi/block_renderers.rb`) | a manifest's `block_renderers:`: `.parse_list`, and what chi web asks without loading plugins: `.for_installed` (first bundle by name wins a language; a record with an error, an unmet `requires_chi` or a list that doesn't parse is skipped) and `.script_path` (`load` membership first, then `Provenance.sha_matches?`). `Manifest` checks each `load` is a `scripts:` key; the files are ordinary scripts everywhere else ([block-renderers.md](block-renderers.md)) |
 | `Builder` | `chi bundle build`: memories (+ the installed bundle's hooks, rules, plugin, scripts) → zip/tar/dir |
 | `Profile` | meta bundles (`includes:`): install the members, record which; `InstallResult#kept_own` names a new member's memory files the user already had, with other bytes (`kept_own_line`, printed by `chi bundle`, `chi update` and `chi bootstrap`); a dry run runs each member's Installer as a dry run too, so it names them as well |
-| `SystemBundle`, `ShippedUpdate` | the built-in system bundle (`ensure!` at Engine start, `sync` in `chi update`) and `chi update`'s upgrade of shipped bundles; both drive the Installer with `upgrade: true`. `ShippedUpdate.external` is the rest: what `chi update` only checks |
+| `SystemBundle`, `ShippedUpdate` | the built-in system bundle (`ensure!` at Engine start, `sync` in `chi update`) and `chi update`'s upgrade of shipped bundles; both drive the Installer with `upgrade: true` and `Remerge` at an equal version (`ShippedUpdate::Row`'s `:would_merge`, `:merged`; `SystemBundle::Result`'s `:merged`). `SystemBundle` also puts back a memory missing at an equal version, that file alone, with no Installer (`verify_files_present`, `Provenance#record_restored`). `ensure!` echoes a merge in one line, in the row's words. That reaches a terminal launch; a worker has only its log (`Log.configure(stderr: false)`), so every merge leaves a note on the file's record (`Installer#note_merges`, a failed run's too, and `Remerge#note_merges`; `Provenance#note_merged`: version, time, trash dir). `chi bundle status` shows it, and `chi update` reads the notes before the run (`SystemBundle.merge_notes`, `ShippedUpdate::Row#earlier`), names them in the row and clears after it those exact ones and the notes of the files that run merged (a worker's meanwhile, on another file, stays), unless it was a dry run, the row failed or has no place for them (a skipped system row), or the run is unattended (`ChildEnv::UNATTENDED_UPDATE`, which `Web::UpdateOps` sets for `update.auto`, an env marker so a hand-over's exec keeps it and an older chi ignores it; `--json` alone says nothing, as a person or script may use it). `chi bundle upgrade` clears the notes of what it printed, and `--force` those of the files it replaced. `--json`'s `merged` is this run's, `earlier` the notes'. `ensure!` says what an upgrade left behind and nothing of a file already behind, which `Result#behind` still has for the row. A plan or sync that can't read a file is that bundle's failed row, in `Trash.failure_message`'s words (`ShippedUpdate.plan_row`, `SystemBundle.sync`). `ShippedUpdate.external` is the rest: what `chi update` only checks |
 | `InstalledCopy`, `BundleCommand::InstalledCheck` | `chi update`'s re-check of the bundles chi didn't ship ([docs/cli.md](../cli.md#updating)). `InstalledCopy` lays a record and its installed files out as a source folder (manifest.yml from `Manifest.write`, the files' own shas, memories from `bases/`); `InstalledCheck` forks per bundle (a plugin's `exit` or hang is that bundle's row; stdio to /dev/null, so `--json` stays parseable; `TIMEOUT`, then KILL of its group) and runs `Check.new(dir, installed: true)` there, which leaves out what only suits a source tree. Its `boundary` finding is narrower there than in a source tree: `Testing::Boundary.gone?` calls a reference gone only when its constant doesn't resolve or the object has no method the name names, so a bundle reaching `Samagotchi::Log` gets no row. lib loads lazily, so when a name doesn't resolve `gone?` requires every file of this chi's library in that same child and asks again (about 0.2 s, only for a bundle that reaches into chi at all); anything it can't read — a `const_get`, a require of a file that is there — is taken as still there. The fork is the point: `Sandbox` swaps ENV and the plugin's code is arbitrary. `UpdateCommand#external_rows` makes the rows (`level`, never `failed`) and holds the check back while a newer gem is yet to take over (`@not_checked`), since a fork is this chi's code |
-| `Uninstaller`, `Trash`, `Status`, `Listing` | remove, keep removed files, `chi bundle status`, `chi bundle list` |
+| `Uninstaller`, `Trash`, `Status`, `Listing` | remove (the bundle's own folder too: an edited file there is copied to the trash first, `Uninstaller#trash_copy_line`); keep removed files (`Trash#move`) and a copy of overwritten ones (`Trash#copy`, its `as:` keeping a subfolder); `chi bundle status` (per file, `behind`, `merge_note`, `unreadable`; `issues=` counts behind, missing and unreadable, not edited); `chi bundle list` (`Installed#behind`) |
 | `IndexUpdater`, `IndexSync` | the managed `index.md` lines (Installer; and the write/edit tools for memories) |
 | `EntrySize` | one memory's size in tokens: `memory.entry_warn_tokens`' crossing note after a memory write, `chi self`'s `big memories` row |
 | `IndexSize` | one scope's memory index as the prompt carries it (tokens, lines, bytes): `memory.index_warn_tokens`' crossing note after a memory write, `chi self`'s summary, the prompt's figures (`SystemPrompt`) |
@@ -86,25 +96,44 @@ The order matters: warnings print in it, and a plugin/script the manifest names
    `#source_change` (the summary's first line, `Source changes: old → new`). A source `SourceIdentity` can't place
    (an older record's relative path) never refuses.
 3. `install_memories`, per memory (`MemoryFiles.select`: a non-empty `files:` list, else every top-level `*.md` but
-   README, CHANGELOG, LICENSE and the like; a listed name not shipped warns; a symlink is skipped with a warning): an upgrade 3-way merges the files the bundle owns (`merge_memory`), a dry run only
-   classifies (`preview_memory`), a plain install writes new files and skips existing ones (`skip_existing`). A
+   README, CHANGELOG, LICENSE and the like; a listed name not shipped warns; a symlink is skipped with a warning): an upgrade 3-way merges the files the bundle owns (`merge_memory`: a clean text merge replaces the file through `Merger.write_merged`, and a real conflict, no git or no base leaves it untouched, `note_conflict`, in `#behind`; a fast-forward over an entry this chi marked `conflict`, a file put back by hand, copies it to the trash first: `save_marked_file`), a dry run only
+   classifies (`preview_memory`, `would_merge` for a merge, git running on temp copies; both through `Merger::Upgrade`), a plain install writes new files and skips existing ones (`skip_existing`), and `--force` overwrites, a file that
+   differs copied to the trash first (`Trash#copy`, said by `#trash_copy_line`; a profile's in `InstallResult#trash_copies`). A
    same-name file the bundle didn't write is the user's: skipped and never recorded (`@owned`). Model overlays
    (`<name>.<key>.md`) get no index line (`note_overlay`).
 4. `AssetInstaller#run`: hooks (manifest-listed, else every `hooks/*.rb`), prune dropped hooks, hook checksums,
-   guardrails, plugin, scripts; each set replaces the previous version's. requires_chi warnings for hooks/rules. A
+   guardrails, plugin, scripts; each set replaces the previous version's, an edited file copied to the trash first. requires_chi warnings for hooks/rules. A
    file that is a symlink or resolves outside the bundle dir (`AssetInstaller#linked?`, a linked `hooks/` too) is
    skipped with a warning (a hook or rule) or raises `InstallError` (the plugin, a script).
 5. An upgrade's `prune_dropped_files`: unchanged → trash; edited → kept (`kept_pruned`); owned by another bundle → kept.
 6. `verify_memory_checksums` (strict), `warn_missing_needs`.
-7. `write_provenance` (manifest, not a dry run): bases come from the incoming file, except where the user's edit was
-   kept (kept/noop/conflict/kept_pruned, or a re-install's skipped edit): those keep the old base, so the next
-   upgrade still sees the edit. A plain install also keeps the record (the old base) of a file an earlier install
+7. `write_provenance` (manifest, not a dry run): an upgrade's bases come from each file's `Merger::Outcome`
+   (`Installer#next_base`): the file on disk, which has the bundle's bytes; the incoming file for a merge, since the merged
+   file holds the user's edit and taking it would make current == base, so the next upgrade would fast-forward over the
+   edit (the edited signal stays current != base, which `chi bundle status` and uninstall's refusal read); and where the user's edit was
+   kept (keep, conflict, whose `FileStanding::Behind` goes in `marks:`; a file the bundle dropped, kept_pruned, and a re-install's skipped edit take the same path by their
+   status and reason): those keep the old base, so the next upgrade still sees the edit. One with no base stays without one (a nil in `Provenance#write`'s `files:`, which keeps the
+   entry and its recorded checksum): taking the user's file would let the next upgrade fast-forward over it. A plain
+   install carries the `conflict` mark of a file it skipped (`held_conflict_marks`), a newer source moving `version`
+   included; it goes once the file has the incoming bytes. A plain install also keeps the record (the old base) of a file an earlier install
    owned and this version doesn't ship, while it is on disk (`dropped_owned_files`), so the next upgrade prunes it.
 8. `detect_placeholders`.
 
+A file system error in steps 3 to 5 (`Installer#replace_files`; a `.trash` it can't write, an edited file it can't read) is an
+`InstallError` in `Trash.failure_message`'s words, as it is an `UninstallError` in `Uninstaller#run`. Each save comes before
+its removal, so no edit is lost, and the record isn't written, so a retry is the same upgrade. Not atomic: files the
+failed run already placed stay.
+
+Which files a plan asks `Merger::Upgrade` about is the caller's, and the lists differ, each less the files the bundle
+doesn't own: the Installer's `MemoryFiles.select`; `ShippedUpdate.forecast`' every shipped `*.md`, so `chi update`'s plan
+can name a file dropped from `files:` or now a symlink, which the upgrade doesn't merge: edited, it stays (`kept_pruned`, or `kept_shared` when another bundle has it too); `SystemBundle`'s dry
+run the manifest's `files:`, so a manifest with none plans nothing (the shipped one lists its files).
+
 Results are `@results` (file → `{status:, reason:}`), summarised by `#summary`. An upgrade with conflicts keeps an
 owned source dir alive (`#source_dir`) until `#cleanup_source!`, because the conflict agent reads the incoming
-files; `Provenance#resolve_conflicts` then moves the resolved files' bases forward.
+files; `BundleCommand#settle_conflicts` then runs `Provenance#resolve_conflicts`, which moves a base forward and keeps
+the entry's description, only for a file the agent step changed that holds no markers (`Merger.markers?`), and whose incoming
+copy is still there. Any other keeps its old base and mark, and the command exits `CONFLICTS_KEPT`.
 
 ## Builder#run, in order
 

data/docs/internals/objectives.md

@@ -220,8 +220,13 @@ the record settles is `unclear`, and a file changed since isn't seen. If that tu
 next step, and the file and view below can stay.
 
 **Independence.** The request (`ObjectivesCheck.request`) has its own system text and no tools. Its record is what people and
-notes said and what tools returned (`.record`, each entry cut at 1,500 characters, the newest 24,000 kept). It never holds the
-agent's prose, the system prompt, the list's notes, a continue's carry note, which holds the agent's last answer
+notes said, what tools returned, and the agent's visible answers labelled `[agent's own words]` (`.record`, each entry cut at 1,500 characters, the
+newest 24,000 kept). Without those answers a claim about what the agent said or asked could only come back `unclear`. So the request says they settle
+what was said or asked and are never proof of work, which needs a tool's output or a person's word. That rule is words to a model, not a mechanism: a
+probe on Qwen3.8 Flash Next held it 3 of 3 (only the agent's "all pass": `unclear`), and a verdict is information only either way.
+The record never holds the agent's thinking (`own_words`: a chat entry's `thinking` and `anthropic_content` aren't read; a native
+entry's content is the raw response, so its inline thoughts, a thought cut off unclosed, and its call markup come out), the system prompt, the list's
+notes, a continue's carry note, an earlier session's answer that would read as outside news
 (`Objectives.outside_note?`, the rule the audit shares), or the objectives tool's calls, since a move isn't evidence for itself.
 Note and evidence are capped at 1,000 characters each. Mid-turn it reads the loop's conversation (`Engine#live_conversation`), the running turn's runs too.
 

data/docs/internals/web-frontend.md

@@ -23,7 +23,7 @@ page. A factory dep a new version stops passing is the same hazard the other way
 out of `send_turn.js`, `session_actions.js` and `lists_view.js`); a page loaded before keeps all its old modules
 until a reload, so the risk is a mixed cache, not an open tab. `answer_fold.js`, `details_motion.js`,
 `turn_range.js`, `history_reveal.js`, `latest.js`, `session_payload.js`, `method_api.js`, `session_store.js`,
-`session_fields.js`, `feature_gates.js`, `revise_stack.js`, `revise_switch.js`, `shell_command.js`, `stale_params.js`, `popover_modal.js`, `more_sheet.js`, `hash_intent.js` (what the hash asks for: session, all, start or keep), `worker_features.js` and the `objectives_*.js` modules are new modules for that reason.
+`session_fields.js`, `feature_gates.js`, `revise_stack.js`, `revise_switch.js`, `shell_command.js`, `stale_params.js`, `popover_modal.js`, `more_sheet.js`, `hash_intent.js` (what the hash asks for: session, all, start or keep), `worker_features.js`, `block_open.js`, `text_roots.js`, `block_source.js`, `block_frame.js`, `block_host.js` and the `objectives_*.js` modules are new modules for that reason. The last three `block_*` draw a bundle's fenced blocks: [block-renderers.md](block-renderers.md).
 
 ## Two pages, two models
 
@@ -50,7 +50,7 @@ change.
 | **`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 and long prompts (`.folded`), Revise stamps (`data-revises` on a prompt; a Verify turn's `data-verify`) and the stacks' folded versions (`.stack-hidden`, `.stack-stub.open`); the switcher's version on view is `revise_stack.js`'s own (a copy `.stack-view` before the top answer, the top `.stack-swapped`; never stored) | `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` and `verify` 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) |
+| **The history DOM** | the conversation as drawn: which turn a bubble belongs to (`data-turn-id`, `data-answer-turn`), what opens a turn (`TURN_PROMPT`, `bubbles.js`: a prompt or a wake's note, the same turns `Steer.turn_opening?` counts for a card's or the recap's `turns_since`), kept command bubbles, which texts were shown, unnamed badges, folded answers and long prompts (`.folded`), Revise stamps (`data-revises` on a prompt; a Verify turn's `data-verify`) and the stacks' folded versions (`.stack-hidden`, `.stack-stub.open`); the switcher's version on view is `revise_stack.js`'s own (a copy `.stack-view` before the top answer, the top `.stack-swapped`; never stored) | `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` and `verify` 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 |
 

data/docs/internals/web-push.md

@@ -181,9 +181,9 @@ from saying it twice across restarts). The key's `chi:` prefix keeps sw.js from
 
 | `kind` | key | title / body |
 |---|---|---|
-| `installed` (`update.restart: never`) | `chi:installed:<X>` | "chi X is installed" / "chi web and its sessions switch over when you restart them." + kept edits |
+| `installed` (`update.restart: never`) | `chi:installed:<X>` | "chi X is installed" / "chi web and its sessions switch over when you restart them." + the edited files (`FileStanding.counts_sentence`) |
 | `failed` | `chi:update_failed:<X>` | "chi X didn't install" (or "installed with a problem" when the gem row was fine) / the first failed row's status, "Open chi web for details." |
-| `updated` | `chi:updated:<X>` | "chi updated to X" / "chi web and 3 sessions restarted; 1 restarts when idle." + kept edits |
+| `updated` | `chi:updated:<X>` | "chi updated to X" / "chi web and 3 sessions restarted; 1 restarts when idle." + the edited files |
 | `restart_failed` | `chi:restart_failed:<X>` | "chi X is installed; chi web didn't restart" / why (a failed `--version` preflight, no wrapper), "Restart chi web in its terminal." |
 
 `updated` is sent by the **restarted** chi web (its AutoUpdate finds the run at `phase: web`): the exec ends the

data/docs/internals/working-set.md

@@ -242,7 +242,10 @@ session's set (load, resync) and when the list opens (a file changed while the s
 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);
+  unchanged one). A footprint is a `<span>` in its block's summary line, `.turn-work > summary > .tw-sum`, before the
+  steps' `.turn-steps`: drawn in the reload's template (`turnHistoryNodes`), prepended at the hand-off
+  (`stage_view.js handOff`, while the stage still hides the summary). A click there must not toggle the block:
+  `details_motion.js` skips `.ws-foot`, and `footClick` cancels the click;
 - 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
@@ -287,7 +290,7 @@ leaves nothing behind. The rail adds a dashed `+ name · next turn` line per pen
 (`working_set_rail.js addLabels`, inside the rail's budget), and `read again next turn` on a held line's title.
 
 **Looks** (design spec §3, §5): a stale line is faded (`--ws-stale-opacity`: `.55` on the light palette, `.4` on the
-dark one, where a lighter grey reads as plain secondary text; a footprint label `.55` on both, its text already faint); a forgotten one is struck in `--text-faint`
+dark one, where a lighter grey reads as plain secondary text; a footprint label `.55` on both); 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 stale` (plain; a file the turn's

data/docs/memory.md

@@ -187,7 +187,7 @@ Working habits for this model:
     `model_notes_<name>.md` you already have and never owns it, so your note
     is what loads, the two never stack, and upgrades leave it alone.
     `chi bundle install model-notes` says `Skipped model_notes_deepseek.md
-    (already exists; use --force to overwrite)`; through the `dev` profile
+    (already exists; --force takes the bundle's version, your file copied to the trash first)`; through the `dev` profile
     (`chi bundle install dev`, `chi bundle upgrade dev`, `chi update`) it is
     `model-notes: kept your own model_notes_deepseek.md (not the bundle's; to
     take the bundle's, remove yours with chi memory rm model_notes_deepseek
@@ -197,14 +197,14 @@ Working habits for this model:
     (`chi memory rm model_notes_deepseek --scope system`, or `memory_write`
     with `remove: true`, moves it to the trash) and run
     `chi bundle install model-notes` again: the install writes the missing
-    file and owns it from then on. Don't use `--force`: it overwrites every
-    file of the bundle with no trash copy.
+    file and owns it from then on. `--force` overwrites every file of the
+    bundle instead, each one that differs copied to the bundle trash first.
   - **Other notes stack.** A note of another name for the same models
     (`model_notes_my_deepseek`), or a project-scope `model_notes_deepseek`,
     loads beside the bundle's (notes are told apart by their file, not their
     name), and the total may pass the 3,000-character warning.
-  - **Your edits to an installed note** are kept by an upgrade (a 3-way
-    merge), or come back as a conflict.
+  - **Your edits to an installed note** survive an upgrade: it merges them
+    with the new version, or leaves your file as it is on a real conflict.
 - Without a model note the system prompt is what it was.
 
 
@@ -487,7 +487,9 @@ for a file another bundle installed.
   and the output names them and the dir:
   `Moved to the trash: notes.md (…/.trash/team-notes-20261003-120000)`. So
   does an upgrade's removal of a file the new version no longer ships. A
-  file you edited still needs `--force`. `chi bundle trash` lists the trash
+  file you edited still needs `--force`. A hook, rule, plugin or script you
+  edited isn't asked about: it is copied to the same dir (`Copied to the trash
+  first: scripts/x (…)`) and the bundle's own copy goes. `chi bundle trash` lists the trash
   (oldest first, with file count, size, and age); `--empty` deletes all
   folders, `--older-than DAYS` keeps only recent ones, and `--dry-run`
   previews. Hooks, rules and the plugin live in the bundle's own dir and
@@ -509,17 +511,53 @@ for a file another bundle installed.
   `.tgz` or `.tar` gives that archive, any other path a directory; default
   `<name>.zip`).
 - **An upgrade that meets your edits.** `chi bundle upgrade` updates a file
-  you didn't edit and keeps one you did (a conflict), then asks on a
+  you didn't edit. One you edited that the bundle also changed takes a text
+  merge (with `git`, which chi doesn't otherwise need): when it comes out clean
+  the file holds both, the old one is in the bundle trash, and the output says
+  `merged 0.8.0 into your X` (a dry run, `would merge 0.8.0 into your X`). Entries both sides added under a
+  `Changelog` heading are kept, yours first. A clean merge is text, not
+  meaning: two sentences can still disagree, so read what you care about (`chi
+  bundle trash` lists the old copy).
+- **A real conflict** leaves your file untouched, never with markers in it, and
+  marks it. So does no `git`, a file with no recorded base, or a file marked by
+  an older chi (below). The output says `X stays behind 0.8.0:` with why and what
+  it missed, as `chi update`, `chi bundle status` and `chi bundle list` (`1 file
+  behind`) do from then on, until the file has the bundle's bytes; the bundle's text
+  waits in `.bundles/<name>/incoming/` until it settles. The upgrade then asks on a
   terminal whether to launch a chi session that merges the two (`/exit`
   when done). `--agent` launches it without asking, `--no-agent` never does;
-  with neither and no terminal it keeps your edits and says so. Kept edits
+  with neither and no terminal the file just stays behind. Only a file
+  the session changed, with no conflict markers left, counts as resolved: any
+  other stays a conflict (`Nothing changed in X: still behind.`). A file marked
+  this way is retried at the same version: the system bundle's at each chi start
+  and on `chi update`, another shipped bundle's on `chi update`, and any other
+  bundle's on `chi bundle upgrade`.
+- **A file marked by an older chi** merges normally when its recorded base is a
+  version chi shipped, which chi checks against the samagotchi gems still
+  installed. Otherwise that base may be your own text, so the file merges only if
+  the bundle takes out or rewords no line it still holds. If it does, chi can't
+  tell whether the file holds edits of yours and says that; the file
+  stays behind until you resolve it by hand, with `--agent` or with `--force`, and
+  the retry can't fix that. A file left behind makes the upgrade
   exit 2; `chi bundle diff NAME FILE` shows the base, and `--force` takes
-  the bundle's version.
+  the bundle's version, copying a file that differs to the bundle trash first
+  (the output says `Copied to the trash first: …`).
+- **Every merge is noted on the file's record.** The system bundle's upgrade and
+  retry run at each start, a worker's only output is its log, and no one may read
+  an automatic update. So `chi bundle status` shows the merge with the old copy's
+  folder while the note exists. A `chi update` row or `chi bundle upgrade` output
+  printed to you ends it for what it printed (an automatic update leaves it), and
+  `--force` replacing the file ends it too. No session is told at start.
+- **`chi bundle status`** says per file what is `modified`, `missing` or
+  `unreadable`, and that a file stays behind and why. Its `issues=` counts files
+  behind, missing or unreadable (and a plugin or hooks that won't load), not edits. A
+  file an older chi marked, which no retry has looked at, says `may be behind`, and so
+  do the counts in `chi bundle list`, `chi self` and `chi update`'s last line.
 - **A dev install** (`chi bundle install --dev PATH`) links the hooks, rules,
   plugin and scripts to `PATH` but still copies the memories at install, so
   an edit to one of them in `PATH` isn't seen until the next install.
 - **The rest of the manifest** (`plugin:`, `requires_chi`, `session_settings:`,
-  `context_providers:`, `requires_chi_next`) is in
+  `context_providers:`, `block_renderers:`, `requires_chi_next`) is in
   [Plugins](plugins.md) and [internals/bundles.md](internals/bundles.md).
 
 ## Bundle profiles: core and dev

data/docs/plugins.md

@@ -942,6 +942,12 @@ worker gone), then moves out of the block, after the turn's end line, so it
 stays in sight; a reload puts it in the same place. An `:info` card of a
 completed turn stays in its step.
 
+Between turns, a card goes above the first turn prompt after it, live and
+after a reload. A failed turn whose prompt went back to its sender isn't a
+turn: its prompt line comes after the cards shown before it, and before those
+shown after. After a reload a card a command showed names it (`from /short`),
+its line being gone.
+
 An [anytime command](#anytime-true)'s cards show as it shows them, after its
 line, in every UI, whether a turn runs or not.
 
@@ -957,8 +963,8 @@ then a new turn) starts from them. Load warnings and a question still
 waiting when the worker went are not saved.
 
 The event is `{type: :card, id:, source:, title:, body:, level:, actions:,
-in_turn:}` (`source` is the bundle), logged as `card` with its source, id and
-title.
+in_turn:}` (`source` is the bundle), plus `command:` when a session command
+showed it (`"/short"`), logged as `card` with its source, id and title.
 
 ## Side answers: `ctx.ask_model`
 
@@ -1347,6 +1353,41 @@ context_providers:
   the PATH may be another one, such as macOS's 2.6).
 - The command follows [the contract](context.md#the-command-contract).
 
+## Block renderers
+
+A bundle can draw a fenced code block as a picture in chi web's answers: the model writes ```` ```mermaid ````, the
+page shows the drawing. No tool, no plugin code in the web server: chi web runs no plugins, and a reloaded page must
+draw after the worker has gone, so JS draws and Ruby only routes and serves.
+
+```yaml
+# manifest.yml
+scripts:
+  draw.js: sha256:…               # scripts/draw.js in the bundle
+block_renderers:
+  - lang: mermaid                 # a fence's first word, downcased: [a-z0-9_+-], at most 32
+    load: [draw.js]               # scripts: keys, loaded into the frame in this order
+```
+
+- `load:` names files under `scripts:`, so they install and check as any script does (`chi bundle check`,
+  `rake bundles:sha`), and one changed after the install isn't served until the bundle is reinstalled; a `--dev`
+  install's links aren't checked. A bundle with no memories installs fine, but `chi bundle build` still needs one:
+  it refuses with "No memories to build".
+- The first installed bundle (by name) with a language draws it. A bundle whose `requires_chi` this chi doesn't meet
+  draws nothing.
+- **What it needs of the page:** `web.markdown` on (a default-off setting, and the commonmarker gem). With it off a
+  fence has no language in the page and nothing draws, though a hint in the bundle's prompt section still reaches
+  the model: say so in the bundle's README.
+- **Where it draws:** the owner's page only, in answers and closed steps. Participants' pages, cards, question
+  replies, the asking slot, delegate reports and the doc viewer show the source, and so does the terminal.
+- **The script's side:** the last file calls `chi.defineRenderer({ init, render })`. `init()` (optional, may be async)
+  runs once; `render(source, theme)` returns the SVG as a string, or a promise of one. Throw to keep the block as
+  source. `theme` is `{name, bg, panel, text, muted, border, accent, font}`, from the page's tokens. The script runs in
+  a sandboxed frame with no cookie and no access to the page, and the CSP closes its network, but for WebRTC (what the
+  frame holds, the diagrams it rendered, could leave that way). The SVG is shown as an `<img>`, so its scripts, links
+  and remote images don't run: it has to stand alone (no `foreignObject`, every namespace prefix bound) and stay under 50,000 px a
+  side and 100M px. Over that, or if the image doesn't decode, the block stays source. The
+  layers and the residual risk are in [internals/block-renderers.md](internals/block-renderers.md).
+
 ## Stable for bundles
 
 Bundles normally use only `chi.*` and `ctx`; the constants and helpers below
@@ -1380,7 +1421,9 @@ that calls it, or for a real external bundle that does. No method on the chance
 5. `Samagotchi::Tools::TaskRuntime::TASKS_DIR` and `EXIT_CODE_FILENAME`.
 6. `Samagotchi::AtomicFile.write`, `Samagotchi::Log.warn` /
    `Samagotchi::Log.debug`, `Samagotchi::Config.get`,
-   `Samagotchi::VERSION` and `Samagotchi::CancellationController` (`new`, `cancel!`: what `cancel:` takes).
+   `Samagotchi::VERSION`, `Samagotchi::CancellationController` (`new`, `cancel!`: what `cancel:` takes) and
+   `Samagotchi::GitEnv::UNSET` (a spawn env: a bundle's own git, or gh, asks about the folder it names, not the repo
+   a hook's or `rebase --exec`'s environment names).
 
 `Samagotchi::Testing::Boundary::ALLOWED` is the checked copy of this list,
 and `Boundary::EXCEPTIONS` the per-bundle list of what each shipped bundle
@@ -1390,6 +1433,9 @@ fails on a reference in neither (docs/testing.md). In `chi update`'s re-check of
 an installed bundle the same scan warns only for a name this chi no longer has
 (`Boundary.gone?`): a reference that still resolves gets no row.
 
+A bundle's `block_renderers:` and the frame's `chi.defineRenderer` ([Block renderers](#block-renderers)) are stable
+too. They aren't Ruby, so the scan above doesn't see them.
+
 **Used by shipped bundles today, but internal** (may change without notice; a
 bundle that needs one should ask for an API instead):
 

data/docs/sessions.md

@@ -219,8 +219,9 @@ reword is refused when you changed that objective since. The model never changes
 
 **Check this** (`/objectives check O2`, or the button in the web's list, for an objective with a move) asks for an independent read of
 the latest move: one side request, on your request only, on the session's model or `objectives.check_model`. It sees the
-claim, what people and notes said and what tools returned, not the agent's prose, and no file: what the record doesn't
-settle comes back `unclear`. **That is up to 24,000 characters of raw tool output, which with a hosted `check_model` leaves the machine on one tap, even from a local session.** chi's redaction takes out known key shapes and `token=`-style values first, by pattern only, so another secret in a tool's output still goes. The verdict (confirmed, refuted, unclear) and its reasons come as a card and under the
+claim, what people and notes said, what tools returned and the agent's visible answers (never its thinking), and no file. The agent's
+words settle what it said or asked, never that its work was done: "I ran the tests" with no run behind it isn't `confirmed`. What the record doesn't
+settle comes back `unclear`. **That is up to 24,000 characters of raw tool output, messages and the agent's visible answers, which with a hosted `check_model` leaves the machine on one tap, even from a local session.** chi's redaction takes out known key shapes and `token=`-style values first, by pattern only, so another secret in them still goes. The verdict (confirmed, refuted, unclear) and its reasons come as a card and under the
 objective. It is information only: it changes no status, approves nothing, and isn't in the conversation or the model's next request.
 A second tap while one runs asks nothing. Its cost is in the session's side line. Mid-turn it runs beside the turn; on a one-slot
 local server it answers after the running request. A participant can't reach it. See
@@ -471,8 +472,8 @@ mise.toml pins Ruby 3.4 gets that `ruby`, `gem` and `bundle` in its tools while
   included, asks you first; a read-only mention (`find . -name mise.toml`) doesn't. `.envrc` and mise's local files
   (`mise.local.toml`, `mise.<env>.local.toml`, dotted or not, and `config.local.toml` / `config.<env>.local.toml` in
   `.config/mise/`, `mise/`, `.mise/`) are secrets to them, as `.env` is.
-- **What tools still drop**: every `execute`, task, `!cmd`, context source and MCP server takes no `RUBYOPT`, `RUBYLIB`, `BUNDLE_GEMFILE`,
-  `BUNDLE_BIN_PATH` or `BUNDLER_VERSION` from the project's mise env: it runs without `RUBYLIB` and Bundler's
+- **What tools still drop**: every `execute`, task, `!cmd`, context source and MCP server takes no `RUBYOPT`, `RUBYLIB`, or what `bundle exec` sets
+  (`BUNDLE_GEMFILE`, `BUNDLE_LOCKFILE`, `BUNDLE_BIN_PATH`, `BUNDLER_VERSION`, `BUNDLER_SETUP`: `BundlerEnv`) from the project's mise env: it runs without `RUBYLIB` and Bundler's
   variables, and with the worker's own `RUBYOPT`, Bundler's part removed (`TaskRuntime`).
 - **`chi` in a tool** stays the home's: with a chi home the tools' PATH starts with `$XDG_STATE_HOME/samagotchi/bin`,
   a dir holding only a `chi` script that boots the home (rewritten at each worker start when the home changed; it

data/docs/testing.md

@@ -40,6 +40,11 @@ that way locally: `npx playwright run-server --port 3333`, then `PW_TEST_CONNECT
 
 No spec reads your own setup. The suite points `XDG_CONFIG_HOME` and `XDG_STATE_HOME` at temp folders,
 clears your `SAMAGOTCHI_*` environment, and keeps every spec off the network (WebMock).
+It also clears what tells git which repo to act on (`GIT_DIR`, `GIT_WORK_TREE`, the rest of
+`git rev-parse --local-env-vars`: `GitEnv`), first thing in `spec_helper.rb` and as the bundle test kit's
+adapters load, so a run from `git rebase --exec`, `bisect run` or a hook can't reach the real repo through a spec's git.
+`npm run e2e` clears the same list as `spec/e2e/support/env.js` loads, asked of git. chi's own git calls on a folder chi
+chose spawn with `GitEnv::UNSET`, in any run.
 `SAMAGOTCHI_TAILSCALE_CLI` points at a file that does not exist (`spec_helper.rb`), so no spec reaches a real `tailscale`; a
 `chi web --tunnel tailscale` spec writes a fake one and sets the variable.
 

data/lib/samagotchi/atomic_file.rb

@@ -18,6 +18,8 @@ module Samagotchi
     # @param content [String] written as-is, byte for byte
     # @param perm [Integer, nil] the new file's mode; nil = a fresh file's
     #   (0666 less the umask), like File.write
+    # @yield just before the rename, when given: a last check of what is being
+    #   replaced; raising leaves +path+ as it was
     # @return [String] +path+
     def write(path, content, perm: nil)
       tmp = "#{path}.#{Process.pid}.#{SecureRandom.hex(4)}.tmp"
@@ -25,6 +27,7 @@ module Samagotchi
         io.write(content)
       end
       File.chmod(perm, tmp) if perm
+      yield if block_given?
       File.rename(tmp, path)
       path
     ensure