samagotchi 0.133.0 → 0.135.0

data/docs/sessions.md

@@ -6,6 +6,8 @@ Sessions are plain files — no DB. Each session is `~/.local/state/samagotchi/s
 
 **Verify verdicts:** a web Verify turn stamps its opening user message with `verify: {turn_id, quote}` (the selected source turn and quote; metadata only, never added to the prompt). When that turn completes and the final assistant reply's last non-empty line is a valid `Verdict: confirmed|refuted|unclear — <reason>`, the session file appends `{anchor: {turn_id, quote}, verdict, reason, by, check_turn_id, at}` to its optional `verdicts` array. `by` is the turn's author (nil for the owner), `check_turn_id` names the Verify turn, and `at` is its timestamp. The array is append-only; older files without it have no saved verdicts. An `unclear` verdict can be checked again by **Verify fresh** (a delegate child that gets only the claim; see *Delegating*): its verdict is appended to the parent's `verdicts` with `fresh: true`, `of` (the verdict it checked again) and `child_id`, from the parent's `fresh_verdicts/` dir, which its worker takes between turns. Verdicts are display state: none enters a prompt.
 
+**Revise stacks:** a web Revise turn (POST /turn `revises: {turn_id}`, the answer it rewrites) stamps its opening message (its prompt) with `revises: {turn_id}` at the turn's end, only when the turn completed with an answer (`AnswerTail`): a failed, canceled or empty turn revised nothing (`Engine#stamp_opening`). A draft no prompt carries (a stale page, a rolled-back turn) is no target: no stamp. A draft a stamped turn already revised is re-targeted to its stack's top, the newest version, so a stack is a chain `v1 ← v2 ← v3`. Like `verify`, it is metadata only, never added to the prompt (no change to a request's bytes); chi web's history passes it on the opening message (and on a wake turn's note), and `:turn_completed` carries the stamped `revises` (the participant view's too). The history also marks a Verify turn's opening `verify: true`: the page offers no Revise on its answer. The web page draws the stacks from these stamps (docs/cli.md, Revise). Like a Verify turn's, a Revise message waits for the running turn's end (`SessionInbox.turn_end_data?`), is sent only to a worker whose `bridge.json` names the `revise` feature (else 409 `revise_unavailable`), and a failed turn gives it back (`:prompt_restored`'s `revises`). Participants can't Revise: chi web and the Bridge drop it from their turns. Both anchors travel as one `TurnAnchors` inside chi; on the wire and in an input file each keeps its own key (`verify`, `revises`).
+
 **Input files:** a message for a session's worker waits in `input/<timestamp>.json` (`SessionInbox.write_input`: `prompt`, `client_id`, `enqueued_id`, and `images`, `no_interrupt` and `delivery` when they apply; `delivery` is written only for `"queue"`). While a turn runs, the worker merges them at each step boundary in name order, except a queued one or one with images: those wait for the turn's end and run one turn each, in name order, and a file after them still merges (`Worker#pending_input_drain`). Such a file, with a prompt, from the user, `chi send` or a delegating parent, also ends a running `task_wait` (`SessionInbox.steer_waiting?`, a peek the worker's turn polls through `Engine#input_waiting?`; never in a participant's turn): the file stays for the drain. A queue is sent only to a worker whose `bridge.json` names the `delivery` feature; an older one would steer it, so `SessionManager.deliver_turn` refuses it (409 `delivery_unavailable`), and any other 4xx the Bridge answers is a refusal too, never a fallback file (except a 413, a body over its size limit: that one still goes in as a file, its `delivery` kept). A session command recognized in a file runs without a turn; its outcome is kept at `input/settled/<enqueued_id>` (`completed`, `failed` for a command error, `canceled` with `cancel_reason` `busy` or `dropped` for one refused mid-turn or dropped as the worker left; `origin: command`) so `chi send --wait` ends instead of waiting for a turn that will not run, its detail saying `the command failed` or `the command was refused (busy)` rather than a turn's words. **Reply files:** a turn that ends with visible text leaves its reply in `output/<timestamp>.txt`, or `output/<timestamp>-<enqueued_id>.txt` when the turn ran an input file with an id (`SessionInbox.write_output`), and the session's `last_turn` keeps that `enqueued_id`; so a wait for one queued message (`chi send --queue --wait`, `ReplyWait`'s `turn:`) finds its own turn's reply or end, never another turn's. The names still sort by time, and every reader takes `*.txt`.
 
 **Removing a queued message:** a message queued for after the running turn (`chi send --queue`, the web's Alt+Enter, `/queue TEXT` in a terminal), or one with images (it waits for the turn's end too), can be taken back while it still waits: the worker's Bridge (`POST /session/:id/turn/dequeue {enqueued_id}`, the `unqueue` feature) deletes its input file and every UI drops it (`:turn_dequeued`). It is a race with the turn's end, decided by the same rename the worker uses to take the file: once a turn took it the answer is `409 already_started` (it runs), and an id the worker no longer knows is `404 unknown_enqueued_id`. A plain message sent without `--queue` is not removable (`409 not_queued`): a running turn's next step may take it at any moment. A wait for its turn (`chi send --queue --wait`, a delegate follow-up's wait) ends at once with `removed` (the tombstone `input/removed/<enqueued_id>` says so), and a `chi -p` run whose queued prompt went ends with exit 1. The `200` carries the removed `prompt`: the web and the attached terminal put it back into the composer to edit (not its images). The images a removed message named stay in the session's `images/`. Not removable: a queued session command (`/queue /model x`: it waits in the worker, not in `input/`), a message in a stopped worker's inbox (the next worker runs it), and the plain REPL's (`--no-shared`) own queue.
@@ -396,8 +398,9 @@ mise.toml pins Ruby 3.4 gets that `ruby`, `gem` and `bundle` in its tools while
 - **Pair turns** (a participant's, see [Participants](internals/participants.md)) run their `execute` without the
   project env. MCP servers are the session's, started once in the project env, so a pair turn's MCP calls do use
   it. A participant's command that runs `mise` or `direnv`, and any write to mise's config (`mise.toml`,
-  `.mise.toml`, `mise.<env>.toml`, `.config/mise.toml`, `.config/mise/…`, `mise/` or `.mise/config*.toml`: your
-  next worker start runs it, and its `[env]` can run commands), asks you first. `.envrc` and mise's local files
+  `.mise.toml`, `mise.<env>.toml`, `.config/mise.toml`, `.config/mise/…`, `mise/` or `.mise/config*.toml`, and
+  `.tool-versions`: your next worker start runs it, and its `[env]` can run commands), a delete or move of one
+  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 and `!cmd` takes no `RUBYOPT`, `RUBYLIB`, `BUNDLE_GEMFILE`,

data/docs/testing.md

@@ -24,7 +24,9 @@ style pass: add a rule only for a bug class it would have caught. It runs in abo
 global (`name`, `status`, `open`…) passes even when its import is gone: give an export such a name only with care.
 It also checks `spec/e2e/` for one thing, the Playwright twin of `Samagotchi/SpecSleep`: no `page.waitForTimeout`.
 Wait for the state (a locator's `expect`, `data-phase`, an animation's end through `waitForFunction`); a pause that
-is the behaviour (a pointer's dwell) carries `// eslint-disable-line no-restricted-syntax -- why`.
+is the behaviour (a pointer's dwell) carries `// eslint-disable-line no-restricted-syntax -- why`. And in the six
+modules that hold the owner page's session state, one more: no write into `current`, `store.current` or `state()`
+in place (`samagotchi/session-writes`; the store is the write path, see internals/web-frontend.md, The session store).
 
 CI's e2e job keeps the tests, chi and the fake model on the runner but runs Chromium in Playwright's image
 (`mcr.microsoft.com/playwright:v<version>-noble`, `playwright run-server` on the host network); the tests connect
@@ -41,7 +43,7 @@ paths (replace them with placeholders), no PATH tools (the suite pins `rg` as fo
 that sets PATH to test the lookup is tagged `:real_rg`), no Ruby-version-dependent `inspect` (a Hash's or an
 exception's text changes between Ruby versions: write the string yourself).
 
-The web specs run in plain node. One that loads lit-html, itself or through a module it imports (`turn_view.js`,
+The web specs run in plain node. One that loads lit-html, itself or through a module it imports (`turn_block.js`,
 `turn_html.js`, `card.js`, `copy.js`, `images.js`, `scope.js`, `command_view.js`, `diff_view.js`, `read_view.js`,
 `question_cards.js`, `stream_handlers.js`, `stage_view.js`, `bubbles.js`, `cards_place.js`, the chips, `info_bar.js`, `info_bar_model.js`, `lists_view.js`, `context_chips.js`, `families_view.js`,
 `chains.js`, `working_set_view.js`, `working_set_rail.js`, `unqueue.js`, `toasts.js`, `notice_links.js`, `start_page.js`, `start_settings.js`, `start_toolkit.js`, `session_actions.js`, `send_turn.js`, `composer_mount.js`, `dock_reserve.js`,
@@ -69,6 +71,28 @@ either router adds its row there; a row where a UI differs on purpose (or a foun
 `repl` override and a `note`. The Ruby side runs each row with every core command (a new one fails its
 `CORE_ROUTES` check until listed there); a row's names that core lacks stand for plugin commands.
 
+## Levels
+
+Each level owns its own share; a detail is asserted once, at the lowest level that has it.
+
+| Level | Ruby | Web | Owns |
+|---|---|---|---|
+| Unit | a class, its collaborators stubbed or passed in | `npm test` (node; happy-dom for lit) | the details and the variants: a message's text, each refusal, the edge cases |
+| Functional | a component through its real seams in one process (an Engine on `test_kernel`, a real Bridge, `Web::App` on Rack) | chi web's routes (`spec/web/`, Rack) | the component's happy path and its main negative paths, and the payload it hands the next layer |
+| Process / e2e | a real `bin/chi`, worker or script (`run_chi`, a spawned process) | Playwright (`npm run e2e`) | one run per mechanism (the wiring a lower level can't see: a require, a spawn, a real browser), and a few whole journeys |
+
+- **The variants are the units'.** A higher-level spec says which mechanism it is the one test of and where its
+  variants live (`remote_attach_stream_spec.rb`, `steer_delivery_e2e_spec.rb`, `terminal_ui/attached_loop_bridge_spec.rb`).
+- **One real chi per mechanism** (spec/support/chi_cli.rb): a file keeps one `run_chi` per mechanism and forks the
+  rest (`fork_chi`). A script that runs chi (a bundle's `scripts/pair`) likewise: its mechanism on real chi, its
+  variants on a fake one (`FakeChiContext`).
+- **A spec that spawns per assertion gets a seam.** A unit spec that starts a process for every check (a `git`, a
+  Ruby boot) passes the collaborator in or fakes it: a guardrails `Context` takes `git:`, so give it one `GitInfo`
+  per example, as the wiring keeps one per turn.
+- **e2e** is for real-browser behaviour (layout, focus, reload, two tabs), one happy path per Ruby↔web mechanism and
+  a few journeys. Before adding a test, extend an existing journey's step; a variant goes to node, a Ruby↔web shape
+  variant to a shared fixture (`spec/fixtures/composer_routes.json`).
+
 ## Waiting and time
 
 A spec waits *for* something and never sleeps to wait: a fixed pause is too short on a loaded runner (a parallel
@@ -95,6 +119,9 @@ run, CI) and too long on a fast one. The contract a new spec follows:
 4. **"Nothing happens" is shown by counting passes** (the worker's loop rounds, spec/support/worker_loop_rounds.rb;
    a class's ticks), not by a pause.
 5. **A wall-clock bound** only as "not the full N s", with at least 5× headroom measured on the slow (x86) laptop.
+   Write it `be < time_bound(3, below: 5)`: the bound scaled like a helper's deadline, and kept under the unscaled
+   deadline it tells apart from (here a 5 s read timeout), so the check still fails on the full wait at any scale. A
+   cost bound with nothing to tell apart from ("no quadratic blow-up") takes no `below:`.
 
 The helpers are the bundle test kit's (`Samagotchi::Testing::Waiting`, [plugins.md](plugins.md#testing-a-bundle-experimental)),
 so core and bundle specs share one copy; `SpecWaiting` (spec/support/waiting.rb) includes them in every example
@@ -107,6 +134,7 @@ group and also answers them as module calls (`SpecWaiting.pop!`, for a stubbed l
   same deadline and message. A gate a stubbed lib thread waits on takes `timeout: 30`: it only ends a hang.
 - `wait_until(timeout:) { … }` returns the block's last value (falsy at the deadline): for a value the example
   checks after, or a `wait-ok` wait.
+- `time_bound(seconds, below: nil)`: a wall-clock upper bound, scaled and kept under `below:` (rule 5).
 - `eventually(timeout: 5) { expect(…) }` (spec only) retries until the expectations hold, then re-raises the last
   failure prefixed `still failing after 5 s:`, so the matcher's own expected/got is in the message.
 
@@ -129,8 +157,8 @@ Every example also runs under a 120 s limit (`spec_helper`'s `around`; `integrat
 limit, `0` turns it off (a debugger session). The limit is not scaled.
 
 **The cops.** `Samagotchi/SpecSleep` (an untagged `sleep` in a spec) and `Samagotchi/SilentWait` (a `wait_until`
-whose value is dropped, an example's last line included, `expect(wait_until { … }).to be(true)`, or an untagged
-`Timeout.timeout`) live in `rubocop/` and run in `rake lint`, so CI fails on them. RSpec counts `wait_for`,
+whose value is dropped, an example's last line included, `expect(wait_until { … }).to be(true)`, an untagged
+`Timeout.timeout`, or a statement `thread.join(N)`, whose N is unscaled and whose nil is dropped: use `join!`) live in `rubocop/` and run in `rake lint`, so CI fails on them. RSpec counts `wait_for`,
 `eventually`, `join!` and `pop!` as an example's expectation (`RSpec/NoExpectationExample`), so a wait can be an
 example's last line. What the cops can't see, `script/affected-specs` hints at (`timing:`, below).
 
@@ -180,10 +208,12 @@ any other file requires it, so a spec file run alone still finds its requires. E
 | `env.rb` | *helper*: `with_env` sets ENV for a block and puts it back (nil unsets) |
 | `failing_saves.rb` | shared context "failing session saves": `Session#save` raising ENOSPC while `saves_fail`, and the worker's `save_failed` records |
 | `fake_chat_adapter.rb` | `FakeChatAdapter`: an `LLM::OpenAIChat` stand-in answering `#chat` with queued steps, recording each request |
+| `fake_chi_context.rb` | `FakeChiContext`: a fake `chi context add/show/push/rm/ls` for the peer bundles' `scripts/pair` variants, logging each call |
 | `fake_executables.rb` | `FakeExecutables`: fake commands (`gh`, `git`) for a spec's PATH, symlinks to one launcher (macOS's first-exec check is paid once) |
 | `fake_provider_server.rb` | `FakeProviderServer`: an in-process HTTP provider replaying spec/fixtures/providers, recording requests |
 | `fake_tailscale.rb` | A fake `tailscale` for `Web::Tunnel::Tailscale` (status, serve, lock from JSON files; argv.log) |
 | `git_repo.rb` | *helper*: `git_repo`, a temp folder with `git init`, removed after the example |
+| `lock_holder.rb` | *helper*: `spawn_lock_holder(session_dir)`, a stand-in worker process holding a session's owner lock, which says so on a pipe |
 | `integration_server.rb` | *helper*: the live model server `:integration` examples use, from `SAMAGOTCHI_INTEGRATION_*` ([Integration specs](#integration-specs)) |
 | `mcp_bundle.rb` | The shipped mcp bundle's path and the fake MCP server its specs start (`MCP_FAKE_COMMAND`, no RubyGems) |
 | `no_console.rb` | Loaded first (`ruby -r`) by spawned bin/chi children: `IO.console` is nil, so output never wraps at a terminal's width |

data/lib/samagotchi/bridge.rb

@@ -11,7 +11,7 @@ require_relative "atomic_file"
 require_relative "bridge_secret"
 require_relative "delivery"
 require_relative "session_inbox"
-require_relative "verify_anchor"
+require_relative "turn_anchors"
 
 require_relative "bridge/bounded_queue"
 require_relative "bridge/card_store"
@@ -634,7 +634,7 @@ module Samagotchi
     # turn (Guardrails::PairBoundary); a worker without it runs it as a
     # review turn, and chi web says so (Delivery::PAIR_FEATURE).
     FEATURES = ["restart", "task_stop", "reparent", Delivery::QUEUE_FEATURE, ReplyWait::TURN_IDS_FEATURE,
-                VerifyAnchor::FEATURE,
+                VerifyAnchor::FEATURE, ReviseAnchor::FEATURE,
                 SessionInbox::UNQUEUE_FEATURE, Delivery::REVIEW_FEATURE, Delivery::PAIR_FEATURE].freeze
 
     # The routes, by method and what follows /session/:id/: a handler takes
@@ -1073,7 +1073,10 @@ module Samagotchi
       # request's principal; the Bridge is loopback and trusts its caller).
       author = fetched(parsed, "author")
       author = nil unless author.is_a?(String) && !author.empty?
-      verify = VerifyAnchor.from(fetched(parsed, "verify"))
+      # A Verify turn's claim, a Revise turn's draft; a participant can't
+      # Revise (chi web drops it first, this is the worker's own layer).
+      anchors = TurnAnchors.from(parsed)
+      anchors = anchors.without_revises if Steer.participant_author?(author)
       if sid.to_s.strip.empty? || prompt.to_s.strip.empty?
         return [{ "Allow" => "POST" }, 400,
                 { error: "missing_fields", detail: "session_id and prompt are required" }]
@@ -1135,7 +1138,7 @@ module Samagotchi
         delivery = Delivery::QUEUE if @accumulator.participant_turn?
         queued_behind_turn = Delivery.queue?(delivery) && !@accumulator.current_turn.nil?
         enqueue_turn(prompt: prompt, client_id: client_id, enqueued_id: enqueued_id,
-                     no_interrupt: no_interrupt, images: images, delivery: delivery, author: author, verify: verify).tap do |ok|
+                     no_interrupt: no_interrupt, images: images, delivery: delivery, author: author, anchors: anchors).tap do |ok|
           next unless ok
 
           enqueued_event = { type: :turn_enqueued, enqueued_id: enqueued_id, client_id: client_id, prompt: prompt.to_s }
@@ -1299,9 +1302,11 @@ module Samagotchi
 
     # Write a turn into this session's input dir, reusing the file IPC the
     # worker polls. Never calls run_turn across the boundary.
-    def enqueue_turn(prompt:, client_id: nil, enqueued_id: nil, no_interrupt: false, images: [], delivery: nil, author: nil, verify: nil)
+    def enqueue_turn(prompt:, client_id: nil, enqueued_id: nil, no_interrupt: false, images: [], delivery: nil, author: nil,
+                     anchors: nil)
       SessionInbox.write_input(session_dir, prompt: prompt, client_id: client_id, enqueued_id: enqueued_id,
-                                            no_interrupt: no_interrupt, images: images, delivery: delivery, author: author, verify: verify)
+                                            no_interrupt: no_interrupt, images: images, delivery: delivery, author: author,
+                                            anchors: anchors)
     end
 
     # ── HTTP plumbing ────────────────────────────────────────────────────────

data/lib/samagotchi/bridge_client.rb

@@ -14,8 +14,10 @@ require_relative "bridge_client/event_stream"
 require_relative "bridge_client/stream_request"
 
 module Samagotchi
-  # Loaded on first use (a Verify turn): keeps the bundle test kit's load
-  # budget (spec/samagotchi/testing/sandbox_spec.rb).
+  # Loaded on first use (any turn's input, a Verify or a Revise turn's
+  # anchor): keeps the bundle test kit's load budget
+  # (spec/samagotchi/testing/sandbox_spec.rb).
+  autoload :TurnAnchors, File.expand_path("turn_anchors", __dir__)
   autoload :VerifyAnchor, File.expand_path("verify_anchor", __dir__)
 
   # Client side of a session worker's Bridge: the 127.0.0.1 HTTP + SSE server
@@ -192,16 +194,17 @@ module Samagotchi
     #   owner; sent only when given (SessionManager.deliver_turn)
     # @param pending_limit [Integer, nil] with a participant's +author+: how
     #   many of their turns may be running or waiting (429 too_many_turns past it)
+    # @param anchors [TurnAnchors, Hash, nil] a Verify turn's claim, a Revise
+    #   turn's draft: their own body keys ("verify", "revises")
     def post_turn(prompt:, client_id: nil, no_interrupt: false, images: nil, delivery: nil, author: nil, pending_limit: nil,
-                  verify: nil)
+                  anchors: nil)
       body = { session_id: @session_id, prompt: prompt, client_id: client_id }
       body[:no_interrupt] = true if no_interrupt
       body[:author] = author if author
       body[:pending_limit] = pending_limit if author && pending_limit
       body[:images] = images if images && !images.empty?
       body[:delivery] = delivery unless delivery.nil? || Delivery.next_step?(delivery)
-      anchor = VerifyAnchor.from(verify)
-      body[:verify] = anchor.to_file if anchor
+      body.merge!(TurnAnchors.from(anchors).to_file) if anchors
       body[:deadline] = deadline
       post("turn", body, read_body: true)
     end

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

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

data/lib/samagotchi/chi_home.rb

@@ -42,6 +42,15 @@ module Samagotchi
     class Invalid < StandardError
     end
 
+    # A record of this process under Bundler (`bundle exec chi home set`)
+    # would name the bundle's Ruby and gems as the home every launch boots.
+    class UnderBundler < StandardError
+      def initialize(msg = "under Bundler (bundle exec) this chi's gem path is the bundle's, not a chi home: " \
+                           "run chi itself, or name another Ruby with --ruby")
+        super
+      end
+    end
+
     # home.json's fields. +gem_path+ is what `Gem.paths=` takes (dirs joined
     # by File::PATH_SEPARATOR); +mise+ an absolute path or nil.
     Record = Data.define(:ruby, :gem_home, :gem_path, :mise, :set_at, :set_by_version) do
@@ -274,8 +283,9 @@ module Samagotchi
       nil
     end
 
-    # The test UpdateCommand's @bundler makes: a first record from a
-    # `bundle exec` would name the bundle's gems.
+    # Whether this process runs under Bundler (`bundle exec`), where a
+    # record of it would name the bundle's gems: record_first!, chi home
+    # set (UnderBundler) and chi update's @bundler.
     def under_bundler?(env = ENV) = !!(defined?(::Bundler) || !env["BUNDLE_GEMFILE"].to_s.empty?)
 
     # mise's absolute path: on +env+'s PATH, else in MISE_DIRS; nil without.

data/lib/samagotchi/config.rb

@@ -330,8 +330,6 @@ module Samagotchi
       Entry.new(key: "web.port",                 yaml_path: %w[web port],                 type: :integer, default: 4567,            expose: %i[env config cli], lifecycle: :web_start),
       Entry.new(key: "web.host",                 yaml_path: %w[web host],                 type: :string, default: "127.0.0.1",     expose: %i[env config cli], lifecycle: :web_start),
       Entry.new(key: "web.markdown",             yaml_path: %w[web markdown],             type: :bool,    default: false,           expose: %i[env config cli], lifecycle: :web_start),
-      # The page's view of a turn: stage (the running turn pinned above the composer) or turn (one block of generations, the live one at the bottom); ?view= overrides it per page load.
-      Entry.new(key: "web.view",                 yaml_path: %w[web view],                 type: :enum,    default: "stage",        expose: %i[env config cli], enum_values: %w[stage turn], lifecycle: :web_start),
       # The stage view's working set (files, memories and URLs the turn brought into context): a rail in the stage, a
       # footprint under each finished turn and a "set N" chip in place of the mem chip; ?working_set=1|0 overrides it per page load.
       Entry.new(key: "web.working_set",          yaml_path: %w[web working_set],          type: :bool,    default: true,            expose: %i[env config cli], lifecycle: :web_start),

data/lib/samagotchi/desktop/macos.rb

@@ -259,6 +259,24 @@ module Samagotchi
         "the desktop helper's launch file sets #{baked.join(", ")} for its sessions' tools: chi desktop upgrade"
       end
 
+      # The config dir the helper's chi reads (its home.json, config.yml):
+      # the launch file's XDG_CONFIG_HOME when baked, else ~/.config.
+      # @return [String]
+      def launch_config_home
+        baked = read_launch["env"]
+        dir = baked["XDG_CONFIG_HOME"] if baked.is_a?(Hash)
+        # Spelled out: Paths.config_home's ~ is this process's HOME, not @env's.
+        dir.to_s.empty? ? File.join(@env["HOME"] || Dir.home, ".config") : dir
+      end
+
+      # Whether the helper's chi reads this chi's config dir (home.json,
+      # config.yml): false for a run with XDG_CONFIG_HOME elsewhere (a spec,
+      # a smoke run), whose home and bundles the helper never sees, though
+      # its launch file sits under the real ~/Library.
+      def reads_this_config?
+        File.expand_path(launch_config_home) == Paths.config_home(env: @env)
+      end
+
       # The chi version the launch file names, nil without one.
       def launch_version = read_launch["version"]
 
@@ -316,10 +334,7 @@ module Samagotchi
       # reads: the launch file's XDG_CONFIG_HOME when baked; disabled hosts
       # are left out. @return [Array<Hash>] name:, hosts:, state:
       def host_keys
-        baked = read_launch["env"]
-        dir = baked["XDG_CONFIG_HOME"] if baked.is_a?(Hash)
-        # Spelled out: Paths.config_home's ~ is this process's HOME, not @env's.
-        config_env = { "XDG_CONFIG_HOME" => dir.to_s.empty? ? File.join(@env["HOME"] || Dir.home, ".config") : dir }
+        config_env = { "XDG_CONFIG_HOME" => launch_config_home }
         hosts = ConfigFile.hosts_config(env: config_env).values.select(&:api_key_env).group_by(&:api_key_env)
         hosts.map do |name, entries|
           state = if HostKeys.from_keychain(name, env: @env) then :keychain

data/lib/samagotchi/engine.rb

@@ -15,6 +15,7 @@ require_relative "steer"
 require_relative "turn_note"
 require_relative "turn_endings"
 require_relative "turn_origin"
+require_relative "revise_anchor"
 require_relative "verify_anchor"
 require_relative "web/participant_view"
 require_relative "verdict"
@@ -1631,10 +1632,11 @@ module Samagotchi
       seconds = turn.elapsed
       synchronize_events do
         kept, event = yield(seconds)
-        stamp_verify_anchor(kept, turn)
+        revises = stamp_opening(kept, turn, outcome)
         replace_session_messages(turn.session, kept) if kept
         verdict = record_verdict(turn, outcome)
         event[:verdict] = verdict if verdict
+        event[:revises] = revises.to_h if revises
         emit_working_set(turn.on_event, turn.session, turn.session.messages)
         turn.session.status = Session::STATUS_IDLE
         record_last_turn(turn.session, outcome, seconds, turn.origin, event, limit: exhausted ? turn.limit : nil)
@@ -1647,16 +1649,63 @@ module Samagotchi
     end
     private :end_turn
 
-    def stamp_verify_anchor(messages, turn)
-      return unless turn.verify && messages.is_a?(Array)
+    # The turn's anchors, stamped on its opening message (the prompt, or a
+    # wake turn's note) in the messages it keeps: display metadata, never
+    # in the prompt (LLM::ChatLoop#plain keeps them, no wire sends them).
+    # A Verify turn's claim however it ended; a Revise turn's draft only
+    # once it completed with an answer (#revision_target). Returns the
+    # stamped ReviseAnchor (the end event's revises), or nil.
+    def stamp_opening(messages, turn, outcome)
+      return unless messages.is_a?(Array)
+
+      revises = revision_target(messages, turn, outcome)
+      fields = { verify: turn.verify&.to_h, revises: revises&.to_h }.compact
+      return if fields.empty?
 
       opening = messages.reverse.find do |message|
-        (message[:role] || message["role"]).to_s == "user" &&
-          (message[:turn_id] || message["turn_id"]).to_s == turn.id
+        Steer.turn_prompt?(message) && (message[:turn_id] || message["turn_id"]).to_s == turn.id
       end
-      opening[:verify] = turn.verify.to_h if opening
+      return unless opening
+
+      opening.merge!(fields)
+      revises
     end
-    private :stamp_verify_anchor
+    private :stamp_opening
+
+    # The turn a Revise turn revised (D6: "this turn revised that one"):
+    # only a completed turn with an answer (AnswerTail) has revised
+    # anything. A draft no prompt in the messages carries is no target (a
+    # stale page, a rolled-back turn); one a stamped turn already revised
+    # is re-targeted to its stack's top, the newest version, which the
+    # person meant ("this draft").
+    def revision_target(messages, turn, outcome)
+      return unless turn.revises && outcome == "completed"
+
+      slice = AnswerTail.turn_slice(messages, turn.id)
+      return unless slice&.any? { |message| AnswerTail.answer?(message) }
+
+      target = turn.revises.turn_id
+      seen = [turn.id]
+      until seen.include?(target)
+        return reject_revise_anchor(turn.revises, :turn_missing) unless AnswerTail.turn_slice(messages, target)
+
+        seen << target
+        newer = messages.reverse.find do |message|
+          Steer.turn_prompt?(message) && ReviseAnchor.from(message[:revises] || message["revises"])&.turn_id == target
+        end
+        return ReviseAnchor.new(turn_id: target) unless newer
+
+        target = (newer[:turn_id] || newer["turn_id"]).to_s
+      end
+      reject_revise_anchor(turn.revises, :cycle)
+    end
+    private :revision_target
+
+    def reject_revise_anchor(anchor, reason)
+      Log.warn(:turn, "revise_anchor_rejected", turn_id: anchor.turn_id, reason:)
+      nil
+    end
+    private :reject_revise_anchor
 
     def verified_anchor(session, anchor)
       return unless anchor
@@ -2150,8 +2199,9 @@ module Samagotchi
     # Continue that starts cold (after a model change).
     # +wall+: the wall time it started (MessageTime.now, once): the
     # :turn_started event's at and its user message's (and reminders') stamp.
+    # +verify+, +revises+: a Verify turn's claim, a Revise turn's draft.
     Turn = Struct.new(:session, :prompt, :continue, :on_event, :controller, :origin, :started_at, :messages, :ended,
-                      :settings, :id, :limit, :resumed, :resume_from, :wall, :verify) do
+                      :settings, :id, :limit, :resumed, :resume_from, :wall, :verify, :revises) do
       def resumed? = resumed ? true : false
 
       # The turn's boundary events carry the origin only when it names a
@@ -2215,6 +2265,9 @@ module Samagotchi
     # @param id [String, nil] the turn's id (a new uuid when nil): a caller
     #   that put the turn's first message in the session already (a context
     #   wake's note) names it with this id
+    # @param verify [VerifyAnchor, nil] a Verify turn's claim (its verdict)
+    # @param revises [ReviseAnchor, nil] a Revise turn's draft: stamped on
+    #   the prompt at the turn's end, metadata only (#stamp_opening)
     #
     # An Interrupt (SIGINT) cancels the turn: what it got to is kept in the
     # session as after a Stop (the prompt, the loop's finished tool
@@ -2226,9 +2279,11 @@ module Samagotchi
     # re-raises; a provider error adds error_kind:, retryable:, host: and a
     # one-line summary:.
     def run_turn(session, prompt, on_event: nil, max_iterations: nil, cancel_controller: nil, max_tool_output_chars: nil, pending_input: nil, continue: false,
-                 origin: TurnOrigin::NONE, images: [], id: nil, resumed: false, resume_from: nil, verify: nil, input_waiting: nil)
+                 origin: TurnOrigin::NONE, images: [], id: nil, resumed: false, resume_from: nil, verify: nil, revises: nil,
+                 input_waiting: nil)
       turn = begin_turn(session, prompt, on_event: on_event, cancel_controller: cancel_controller, origin: origin,
-                                         continue: continue, id: id, verify: verify, input_waiting: input_waiting)
+                                         continue: continue, id: id, verify: verify, revises: revises,
+                                         input_waiting: input_waiting)
       if continue
         turn.resumed = resumed
         turn.resume_from = resume_from
@@ -2276,7 +2331,8 @@ module Samagotchi
     # The turn's state before anything can fail it: the session running,
     # the turn flag, its cancel controller and sink. The cross-thread state
     # is set here and cleared in #release_turn only.
-    def begin_turn(session, prompt, on_event:, cancel_controller:, origin:, continue:, id: nil, verify: nil, input_waiting: nil)
+    def begin_turn(session, prompt, on_event:, cancel_controller:, origin:, continue:, id: nil, verify: nil, revises: nil,
+                   input_waiting: nil)
       origin = TurnOrigin.of(origin)
       # A participant's Verify fresh child: every turn is theirs (their
       # author, boundary and cap), whoever started it.
@@ -2304,7 +2360,8 @@ module Samagotchi
 
       Turn.new(session: session, prompt: continue ? nil : prompt, continue: continue, on_event: on_event,
                controller: effective_controller, origin: origin, started_at: Process.clock_gettime(Process::CLOCK_MONOTONIC),
-               id: id || SecureRandom.uuid, wall: MessageTime.now, verify: VerifyAnchor.from(verify))
+               id: id || SecureRandom.uuid, wall: MessageTime.now, verify: VerifyAnchor.from(verify),
+               revises: ReviseAnchor.from(revises))
     end
     private :begin_turn
 
@@ -3044,6 +3101,15 @@ module Samagotchi
       return if pending.nil?
 
       outcome, judged = pending.wait(turn.controller)
+      if outcome == :timeout
+        # The session starts on its default without a word otherwise: a
+        # slow System 1 host (a local one) is the usual cause.
+        timeout_ms = SystemOne::Client.configured_timeout_ms
+        Log.warn(:toolkit, "toolkit_suggest_timeout", session_id: turn.session.id, timeout_ms: timeout_ms,
+                                                      reason: "System 1 gave no answer within guardrails.system_one.timeout_ms")
+        @toolkit_binding.fell_back(turn.session, "System 1 took over #{timeout_ms} ms")
+        return
+      end
       unless outcome == :answered
         Log.info(:toolkit, "toolkit_suggest_#{outcome}", session_id: turn.session.id)
         return
@@ -3070,6 +3136,10 @@ module Samagotchi
                                                                             deferred: ToolkitSuggest.model_reply?(session.messages))
         switched ? "suggested" : "chosen"
       when "defer" then "defer"
+      when "no_judgment"
+        # System 1 failed (its own warn) or answered nothing usable.
+        @toolkit_binding.fell_back(session, "System 1 gave no answer")
+        "default"
       else "default"
       end
     end

data/lib/samagotchi/guardrail_wiring.rb

@@ -330,9 +330,10 @@ module Samagotchi
         return verdict
       end
 
-      answer = @ask.call(payload)
+      # The card and the session file carry the facts as the hash they were.
+      answer = @ask.call(payload.merge(approval: payload[:approval].to_h))
       system_one_label(judgment, answer, payload)
-      Guardrails::Approval.settle(verdict, answer, payload[:approval][:scopes])
+      Guardrails::Approval.settle(verdict, answer, payload[:approval].scopes)
     end
 
     private
@@ -391,9 +392,9 @@ module Samagotchi
       decision = system_one_decision(client, auto)
 
       id = log.judgment(session_id: @session_lookup.call&.id,
-                        rule: approval[:rule], source: approval[:source], tool: approval[:tool],
+                        rule: approval.rule, source: approval.source, tool: approval.tool,
                         **SystemOne::ApprovalQuestion.call_fields(approval),
-                        repo_name: approval[:repo_name],
+                        repo_name: approval.repo_name,
                         p: p, threshold: Config.get("guardrails.system_one.threshold"), model: client.model,
                         latency_ms: latency_ms, decision: decision, origin: "live")
       # A judgment the log cannot hold is no judgment: the user is asked.
@@ -418,12 +419,13 @@ module Samagotchi
     # user opted in, the never-list and chi's own files, the probability, and
     # the rule's record. Any one that fails leaves the ask to the user. The
     # entries are the judgment log read once for this ask.
+    # @param approval [Guardrails::ApprovalFacts] the ask's facts
     # @param entries [Array<Hash>] SystemOne::Log#entries
     # @param targets [Guardrails::Targets, nil] the call's, for its env:
     def system_one_auto_allow?(client, approval, p, entries, targets: nil)
       return false unless client.mode == "on"
 
-      rule = approval[:rule].to_s
+      rule = approval.rule.to_s
       return false if rule.empty?
       return false unless system_one_rules.include?(rule)
       return false if SystemOne::SelfProtect.refuse?(approval, targets: targets)
@@ -456,7 +458,7 @@ module Samagotchi
       id = judgment && judgment[:id]
       return nil if id.nil?
 
-      scopes = Array(payload[:approval][:scopes])
+      scopes = Array(payload[:approval].scopes)
       if !answer.is_a?(Samagotchi::QuestionAnswer)
         label = "none"
       elsif answer.parent_agent?

data/lib/samagotchi/guardrails/approval.rb

@@ -6,6 +6,41 @@ require_relative "../question_answer"
 
 module Samagotchi
   module Guardrails
+    # An ask's facts, as Approval.payload builds them (its approval:) and
+    # the question card shows them: the tool (tool, acts_as, label), what
+    # it acts on (command, paths, args, memory), where (cwd, repo_root,
+    # repo_name, branch), who asked and why (rule, source, reason), the
+    # offered scopes, an edit's preview (EditPreview.for) and, for a
+    # participant's turn, who asks (author, author_name, asked_by).
+    #
+    # In this process it is passed as this value; it crosses to the UIs and
+    # the session file (PendingQuestion's approval) as #to_h, the hash it
+    # always was: symbol keys, in member order, unset fields left out. A
+    # saved or sent one (string or symbol keys, missing fields, a key we
+    # don't know dropped) comes back through .from_h. memory and preview
+    # stay as given (string keys inside after a load).
+    ApprovalFacts = Data.define(:tool, :acts_as, :label, :command, :paths, :args, :memory, :cwd, :repo_root,
+                                :repo_name, :branch, :rule, :source, :reason, :scopes, :preview, :author,
+                                :author_name, :asked_by) do
+      def initialize(**fields)
+        super(**members.to_h { |m| [m, nil] }, **fields)
+      end
+
+      # @param raw [ApprovalFacts, Hash, nil] facts as built, saved or sent
+      # @return [ApprovalFacts, nil] nil for anything that is not facts
+      def self.from_h(raw)
+        return raw if raw.is_a?(ApprovalFacts)
+        return nil unless raw.is_a?(Hash)
+
+        new(**members.to_h { |m| [m, raw.key?(m) ? raw[m] : raw[m.to_s]] })
+      end
+
+      # The card's and the session file's shape: symbol keys, in member
+      # order, unset fields left out.
+      # @return [Hash{Symbol => Object}]
+      def to_h = super.compact
+    end
+
     # An ask as a question for the user (Engine#open_question), and the
     # answer back as a verdict. The question text is plain and complete, so
     # a UI that doesn't know approvals still shows everything; `approval:`
@@ -42,9 +77,10 @@ module Samagotchi
       #   their turn asks: it offers once only (PARTICIPANT_SCOPES), and the
       #   card names them (approval author:, author_name:, the header)
       # @param author_name [String, nil] their name (participants.json)
-      # @return [Hash] open_question fields; its caller adds user_only:
-      #   (ParentApprovals.protected_facts? on approval:, a file that
-      #   requires this one)
+      # @return [Hash] open_question fields, with approval: an ApprovalFacts
+      #   (its caller hands open_question approval.to_h); the caller adds
+      #   user_only: (ParentApprovals.protected_facts? on approval:, a file
+      #   that requires this one)
       def payload(verdict, label: nil, preview: nil, only: nil, author: nil, author_name: nil)
         asker = asker(author, author_name)
         only = PARTICIPANT_SCOPES if asker
@@ -60,7 +96,7 @@ module Samagotchi
           allow_freeform: true,
           effects: effects(scopes),
           kind: KIND,
-          approval: {
+          approval: ApprovalFacts.new(
             tool: targets&.tool || verdict.call[:name].to_s,
             # The tool the call acts as (an MCP tool behind call_tool).
             acts_as: targets&.acts_as,
@@ -86,7 +122,7 @@ module Samagotchi
             author: (author.to_s if asker),
             author_name: (author_name_for(author_name) if asker),
             asked_by: (format(ASKED_BY, asker) if asker)
-          }.compact
+          )
         }
       end