samagotchi 0.15.0 → 0.17.0

data/lib/samagotchi/bridge/card_store.rb

@@ -51,7 +51,7 @@ module Samagotchi
       # The events after which the file is written again: the ones that
       # change an entry or the turn count.
       SAVED_ON = (%i[card hook_notice empty_answer_retry question_requested question_answered question_cancelled
-                     turn_failed] + Events::TURN_KEPT).freeze
+                     question_relay turn_failed] + Events::TURN_KEPT).freeze
 
       # What a session's saved file lists, as a store started from it lists
       # (no turn running): the web's cards for a session no worker runs.
@@ -171,6 +171,7 @@ module Samagotchi
           add_turn_row({ type: :question, pending_question: Marshal.load(Marshal.dump(event[:pending_question])) }) if @running
         when :question_answered then resolve_question(event[:id], answer: event[:answer])
         when :question_cancelled then resolve_question(event[:id], cancelled: true, reason: event[:reason])
+        when :question_relay then mark_relay(event[:id], event[:relayed_to])
         end
       end
 
@@ -219,6 +220,20 @@ module Samagotchi
         entry&.merge!(Marshal.load(Marshal.dump(outcome.compact)))
       end
 
+      # The open question was relayed to a parent's user, or no longer is.
+      def mark_relay(id, relayed_to)
+        entry = @entries.reverse_each.find do |e|
+          e[:type] == :question && e.dig(:pending_question, :id).to_s == id.to_s
+        end
+        return unless entry
+
+        if relayed_to
+          entry[:pending_question][:relayed_to] = Marshal.load(Marshal.dump(relayed_to))
+        else
+          entry[:pending_question].delete(:relayed_to)
+        end
+      end
+
       def push(entry)
         @entries << entry
         notice = notice?(entry)

data/lib/samagotchi/bridge/turn_accumulator.rb

@@ -41,11 +41,23 @@ module Samagotchi
       #   continue, ordered parts (thinking / text / tool / input / steer /
       #   reminder / notice), pending_question and the last event_seq folded
       #   in. A finished tool part keeps the live row's action and duration_ms
-      #   too. A notice part holds the event of one of the turn's rows
-      #   (TurnNotice: a hook's notice, an empty-answer retry, a question and
-      #   its answer), which a UI replays through its live handler.
+      #   too, a running one the time it has run so far (elapsed_ms), so a
+      #   join times its row from its start. A notice part holds the event
+      #   of one of the turn's rows (TurnNotice: a hook's notice, an
+      #   empty-answer retry, a question and its answer), which a UI replays
+      #   through its live handler.
       def current_turn
-        @mutex.synchronize { @turn && Marshal.load(Marshal.dump(@turn)) }
+        @mutex.synchronize do
+          next nil unless @turn
+
+          turn = Marshal.load(Marshal.dump(@turn))
+          now = @clock.call
+          Array(turn[:parts]).each do |part|
+            started_at = part[:kind] == "tool" && part[:status] == "running" && @tool_started_at[[part[:iteration], part[:call_index]]]
+            part[:elapsed_ms] = ((now - started_at) * 1000).round if started_at
+          end
+          turn
+        end
       end
 
       # The turn in progress as conversation messages, for a plugin's
@@ -142,7 +154,10 @@ module Samagotchi
         call[:label] = part[:label] if part[:label]
         title = part[:title] ? { title: part[:title] } : {}
         events = [{ type: :tool_call_started, **call, params: part[:params], **title }]
-        return events if part[:status] == "running"
+        if part[:status] == "running"
+          events.first[:elapsed_ms] = part[:elapsed_ms] unless part[:elapsed_ms].nil?
+          return events
+        end
 
         activity = { tool: part[:tool], status: part[:status], params: part[:params], **title }
         activity[:action] = part[:action] if part[:action]
@@ -268,6 +283,12 @@ module Samagotchi
           @turn[:pending_question] = event[:pending_question]&.dup
         when :question_answered, :question_cancelled
           @turn[:pending_question] = nil
+        when :question_relay
+          pending = @turn[:pending_question]
+          if pending && pending[:id].to_s == event[:id].to_s
+            relayed_to = event[:relayed_to]
+            @turn[:pending_question] = relayed_to ? pending.merge(relayed_to: relayed_to) : pending.except(:relayed_to)
+          end
         end
         parts << { kind: "notice", event: TurnNotice.slice(event) } if TurnNotice.notice?(event)
       end

data/lib/samagotchi/bridge.rb

@@ -24,6 +24,8 @@ require_relative "image_store"
 require_relative "log"
 require_relative "version"
 require_relative "worker_sidecar"
+require_relative "relay_verifier"
+require_relative "relay_watcher"
 
 module Samagotchi
   # Bridge is an optional HTTP transport that lets an external web / desktop
@@ -192,6 +194,7 @@ module Samagotchi
       await_answers(REQUEST_GRACE_SECONDS)
       @connection_threads.each { |t| t.kill rescue nil }
       @connection_threads.clear
+      @mutex.synchronize { @relay_watchers&.each { |t| t.kill rescue nil } }
       @accept_thread&.join(2)
       remove_sidecar
       nil
@@ -241,6 +244,16 @@ module Samagotchi
       end
     end
 
+    # The worker's own way in for a session command that came as a message
+    # (its first prompt, an input file): queued and announced as a POST
+    # /command's is (#handle_command).
+    # @return [String] its command_id
+    def queue_command(line, client_id: nil)
+      command = { command_id: SecureRandom.uuid, client_id: client_id, line: line.to_s.strip }
+      @engine.synchronize_events { queue_command_locked(command) }
+      command[:command_id]
+    end
+
     private
 
     # The Engine's commands: the built-ins and its plugins'.
@@ -429,6 +442,8 @@ module Samagotchi
       %w[POST command] => :handle_command,
       %w[POST exit] => :handle_exit_request,
       %w[POST recap] => :handle_recap,
+      %w[POST relay] => :handle_relay,
+      %w[POST relay/status] => :handle_relay_status,
       %w[GET state] => :handle_state,
       %w[GET stats] => :handle_stats,
       %w[GET snapshot] => :handle_snapshot
@@ -525,6 +540,38 @@ module Samagotchi
       end
     end
 
+    # What a parent's relay may say about this session's approval
+    # (BridgeClient#relay): opened and closed only change how the question
+    # shows (QuestionDesk#annotate); answered makes this worker ask the
+    # parent for the answer (RelayVerifier). No auth: a poke at opened or
+    # closed can at most show a wrong banner.
+    RELAY_ACTIONS = %w[opened closed answered].freeze
+    # Why a relay closed, as a parent says it; anything else is "closed".
+    RELAY_CLOSE_REASONS = %w[stopped closed child_gone answered_on_child].freeze
+
+    # POST /session/:id/relay {action, relay_id, question_id}. 200, 409 (no
+    # longer pending, or another relay's), 403 refused (a parent agent's
+    # allow), 422 relay_unverified, 400 a bad request.
+    def handle_relay(session_id, body)
+      parsed = parse_json(body)
+      return [{ "Allow" => "POST" }, 400, { error: "invalid_json" }] unless parsed.is_a?(Hash)
+
+      action, relay_id, qid = %w[action relay_id question_id].map { |key| fetched(parsed, key).to_s }
+      unless RELAY_ACTIONS.include?(action) && !relay_id.empty? && !qid.empty?
+        return [{ "Allow" => "POST" }, 400, { error: "missing_fields", detail: "action (opened, closed, answered), relay_id and question_id required" }]
+      end
+
+      case action
+      when "opened" then relay_opened(qid, relay_id)
+      when "closed"
+        reason = fetched(parsed, "reason").to_s
+        relay_closed(qid, relay_id, RELAY_CLOSE_REASONS.include?(reason) ? reason : "closed")
+      else
+        RelayVerifier.new(engine: @engine, state_dir: @state_dir, session_id: session_id)
+                     .answer(relay_id: relay_id, question_id: qid)
+      end
+    end
+
     # Dismiss the pending question (an empty answer, as in the REPL): the
     # tool returns without an answer and every UI gets :question_cancelled.
     # Only the question the client saw, and only while nobody has answered
@@ -575,17 +622,21 @@ module Samagotchi
       deadline = fetched(parsed, "deadline")
       return BAD_DEADLINE unless deadline_valid?(deadline)
 
-      command = { command_id: SecureRandom.uuid, client_id: fetched(parsed, "client_id"), line: line }
+      queue_command_request(session_id, line, client_id: fetched(parsed, "client_id"), deadline: deadline,
+                                              card: fetched(parsed, "card") == true)
+    end
+
+    # Queues +line+ (a session command) for the worker and announces its
+    # :command_queued, unless +deadline+ has passed. Returns [headers,
+    # status, body]: 202 with its command_id, or 408.
+    def queue_command_request(session_id, line, client_id:, deadline: nil, card: false)
+      command = { command_id: SecureRandom.uuid, client_id: client_id, line: line }
       # A card's action: the UIs leave its line out (the card is the echo).
-      command[:card] = true if fetched(parsed, "card") == true
+      command[:card] = true if card
       queued = @engine.synchronize_events do
         next false if expired?("command_expired", deadline, sid: session_id, client_id: command[:client_id])
 
-        @on_command.call(command)
-        # An anytime command runs now, beside a turn (D8): the UIs show its
-        # line here, so the cards it shows come after it.
-        anytime = command_registry.lookup(line)&.anytime ? { anytime: true } : {}
-        @engine.announce(type: :command_queued, **command, **anytime)
+        queue_command_locked(command)
         true
       end
       return deadline_passed("command") unless queued
@@ -593,6 +644,15 @@ module Samagotchi
       [{}, 202, { status: "accepted", command_id: command[:command_id], session_id: @session_id }]
     end
 
+    # With the event log held.
+    def queue_command_locked(command)
+      @on_command.call(command)
+      # An anytime command runs now, beside a turn (D8): the UIs show its
+      # line here, so the cards it shows come after it.
+      anytime = command_registry.lookup(command[:line])&.anytime ? { anytime: true } : {}
+      @engine.announce(type: :command_queued, **command, **anytime)
+    end
+
     # A client asks the worker to exit now (`/exit` in the attached TUI). The
     # worker decides with the event log held, so no POST /turn lands between
     # its check and its answer; it leaves from its loop after this reply.
@@ -651,6 +711,14 @@ module Samagotchi
       deadline = fetched(parsed, "deadline")
       return BAD_DEADLINE unless deadline_valid?(deadline)
 
+      # A session command sent as a message (chi send -m "/model x", chi -p,
+      # a UI whose command list lags) runs as the command, as typed in a
+      # TUI; an unknown /word stays a prompt. Not with images: those are
+      # for the model.
+      if images.empty? && @on_command && command_registry.command?(prompt.to_s)
+        return queue_command_request(sid, prompt.to_s.strip, client_id: client_id, deadline: deadline)
+      end
+
       enqueued_id = SecureRandom.uuid
       # Write and announce with the event log held: the worker can't emit
       # this turn's :turn_started (or merge it mid-turn) before
@@ -872,6 +940,53 @@ module Samagotchi
       headers["connection"].to_s.downcase == "close"
     end
 
+    # POST /session/:id/relay/status {relay_id}: what this (the parent's)
+    # worker's relay holds, for the child that verifies an answer
+    # (RelayVerifier). Read-only and no secret; 404 for an unknown id.
+    def handle_relay_status(_session_id, body)
+      parsed = parse_json(body)
+      return [{ "Allow" => "POST" }, 400, { error: "invalid_json" }] unless parsed.is_a?(Hash)
+
+      relay = @engine.relay_desk.status(fetched(parsed, "relay_id").to_s)
+      return [{}, 404, { error: "unknown_relay" }] unless relay
+
+      [{}, 200, relay]
+    end
+
+    # A parent's relay card for +qid+ opened: the question says so (the
+    # child's card and lists show where else it can be answered).
+    def relay_opened(qid, relay_id)
+      parent_id = begin
+        Session.load(@session_id, state_dir: @state_dir).parent_id
+      rescue ArgumentError
+        nil
+      end
+      return [{}, 422, { error: "relay_unverified", detail: "this session has no parent" }] unless parent_id
+
+      marker = { parent_id: parent_id, parent_short: parent_id[0, 8], relay_id: relay_id }
+      return [{}, 409, { error: "question_not_pending", detail: "no pending question #{qid}" }] unless @engine.annotate_question(qid, relayed_to: marker)
+
+      Log.info(:bridge, "relay_opened", sid: @session_id, id: qid, parent: parent_id[0, 8])
+      watch = RelayWatcher.start(engine: @engine, question_id: qid, relay_id: relay_id,
+                                 parent_dir: Session.session_dir(parent_id, state_dir: @state_dir))
+      @mutex.synchronize { @relay_watchers = (@relay_watchers || []).select(&:alive?) << watch }
+      [{}, 200, { status: "opened", question_id: qid }]
+    end
+
+    # The parent's relay card closed unanswered: the mark goes, if it is
+    # still that relay's.
+    def relay_closed(qid, relay_id, reason)
+      pending = @engine.pending_question
+      relay = pending && pending[:relayed_to]
+      unless pending && pending[:id].to_s == qid && relay && (relay[:relay_id] || relay["relay_id"]).to_s == relay_id
+        return [{}, 409, { error: "question_not_pending", detail: "no question #{qid} relayed by #{relay_id}" }]
+      end
+      return [{}, 409, { error: "question_not_pending", detail: "no pending question #{qid}" }] unless @engine.annotate_question(qid, relayed_to: nil, reason: reason)
+
+      Log.info(:bridge, "relay_closed", sid: @session_id, id: qid, reason: reason)
+      [{}, 200, { status: "closed", question_id: qid }]
+    end
+
     def write_sidecar
       # version: the chi this worker runs (chi update reports older ones).
       WorkerSidecar.new(port: @port, bind: @bind, session_id: @session_id, started_at: Time.now.iso8601(3),

data/lib/samagotchi/bridge_client.rb

@@ -180,6 +180,33 @@ module Samagotchi
       post("cancel", { reason: reason }, read_body: true)
     end
 
+    # How long the approval relay's calls wait for a reply: a parent's Stop
+    # isn't held for READ_TIMEOUT by a child that doesn't answer.
+    RELAY_TIMEOUT = 5
+    # How long a child waits for its parent's word on a relay (#relay_status).
+    RELAY_STATUS_TIMEOUT = 2
+
+    # POST /session/:id/relay on a child's worker: a parent's relay of the
+    # child's approval opened, closed or was answered (the child asks the
+    # parent which answer, #relay_status). 200 answered, 409 no longer
+    # pending, 403 refused (a parent agent's allow), 422 relay_unverified.
+    # @param action [String] "opened", "closed" or "answered"
+    # @return [Response]
+    # @raise [SystemCallError] the worker is gone or didn't answer in time
+    def relay(action:, relay_id:, question_id:, read_timeout: RELAY_TIMEOUT, **extra)
+      post("relay", { action: action, relay_id: relay_id, question_id: question_id, **extra },
+           read_body: true, read_timeout: read_timeout)
+    end
+
+    # POST /session/:id/relay/status on a parent's worker: what its relay
+    # +relay_id+ holds (child_id, child_question_id, state, answer, by); 404
+    # for one it doesn't know. A POST with a body: routes match exact paths.
+    # @return [Response]
+    # @raise [SystemCallError]
+    def relay_status(relay_id, read_timeout: RELAY_STATUS_TIMEOUT)
+      post("relay/status", { relay_id: relay_id }, read_body: true, read_timeout: read_timeout)
+    end
+
     # GET /session/:id/<path> as JSON.
     # @return [Hash, nil] the parsed body, or nil unless the Bridge answered 200
     def get_json(path)
@@ -283,11 +310,11 @@ module Samagotchi
     # the same one.
     def deadline = (Time.now.to_f + (@read_timeout * DEADLINE_SHARE)).round(3)
 
-    def post(path, payload, read_body:)
+    def post(path, payload, read_body:, read_timeout: @read_timeout)
       sock = TCPSocket.new(@host, @port)
       json_body = JSON.generate(payload)
       sock.write("POST /session/#{@session_id}/#{path} HTTP/1.1\r\nHost: #{@host}:#{@port}\r\nContent-Type: application/json\r\nContent-Length: #{json_body.bytesize}\r\nConnection: close\r\n\r\n#{json_body}")
-      reply = read_reply(sock, path, whole: read_body)
+      reply = read_reply(sock, path, whole: read_body, timeout: read_timeout)
       body = read_body ? reply.split("\r\n\r\n", 2)[1] : nil
       Response.new(status: reply[STATUS_LINE, 1].to_i, body: body)
     ensure
@@ -295,17 +322,17 @@ module Samagotchi
     end
 
     # The reply up to the Bridge's close (or its first line only), within
-    # @read_timeout in all.
+    # +timeout+ seconds in all (@read_timeout by default).
     # @raise [Errno::ETIMEDOUT]
-    def read_reply(sock, path, whole: true)
-      deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + @read_timeout
+    def read_reply(sock, path, whole: true, timeout: @read_timeout)
+      deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout
       reply = +""
       loop do
         break if !whole && reply.include?("\n")
 
         left = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
         unless left.positive? && sock.wait_readable(left)
-          raise Errno::ETIMEDOUT, "bridge #{path}: no reply within #{@read_timeout}s"
+          raise Errno::ETIMEDOUT, "bridge #{path}: no reply within #{timeout}s"
         end
 
         reply << sock.readpartial(16_384)

data/lib/samagotchi/bundle_command.rb

@@ -36,7 +36,7 @@ module Samagotchi
         build [--scope system|project] [--name NAME] [--version VER] [--description DESC] [--out PATH] [FILES...]
           Build local memories and installed hooks (and plugin) into a shareable bundle (dir or zip).
           --scope selects source dir (default: system). --out inferred from extension; default <name>.zip.
-          FILES... optional allowlist of *.md basenames to include (default: all).
+          FILES... optional allowlist of *.md basenames to include (default: all but installed bundles' ones).
     TEXT
 
     # Each subcommand's --help (and only --help: -h and help are taken as
@@ -57,7 +57,7 @@ module Samagotchi
         build [--scope system|project] [--name NAME] [--version VER] [--description DESC] [--out PATH] [FILES...]
           Build local memories and installed hooks into a shareable bundle (dir or zip).
           --scope selects source dir (default: system). --out inferred from extension; default <name>.zip.
-          FILES... optional allowlist of *.md basenames to include (default: all).
+          FILES... optional allowlist of *.md basenames to include (default: all but installed bundles' ones).
 
         Examples:
           chi bundle build --scope system
@@ -272,6 +272,7 @@ module Samagotchi
       begin
         uninstaller.run
         @stdout.puts "Uninstalled bundle '#{bundle_name}'"
+        puts_trashed(uninstaller.trashed_files, uninstaller.trash_dir)
         @stdout.puts "Removed: #{uninstaller.removed_files.join(', ')}" unless uninstaller.removed_files.empty?
         hook_removed = uninstaller.removed_files.count { |f| f.start_with?("hooks/") }
         @stdout.puts "Hooks removed: #{hook_removed}" if hook_removed > 0
@@ -311,9 +312,13 @@ module Samagotchi
       if result.gone
         @stdout.puts "Uninstalled bundle '#{name}'"
         @stdout.puts "Removed: #{result.removed.join(", ")}" unless result.removed.empty?
+        result.trash.each_value { |files, dir| puts_trashed(files, dir) }
+        result.warnings.each { |w| @stdout.puts w }
         return 0
       end
       @stdout.puts "Removed from #{name}: #{result.removed.join(", ")}" unless result.removed.empty?
+      result.trash.each_value { |files, dir| puts_trashed(files, dir) }
+      result.warnings.each { |w| @stdout.puts w }
       result.blocked.each { |member, why| @stdout.puts "Kept #{member}: #{why}" }
       @stderr.puts "Uninstall failed: #{name} stays installed until #{result.blocked.keys.join(", ")} goes " \
                    "(chi bundle uninstall #{name} --force)"
@@ -323,6 +328,11 @@ module Samagotchi
       1
     end
 
+    # Memory files an uninstall moved to the trash (MemoryBundle::Trash).
+    def puts_trashed(files, dir)
+      @stdout.puts "Moved to the trash: #{files.join(", ")} (#{dir})" if dir && !files.empty?
+    end
+
     def status(rest)
       name = rest.find { |a| !a.start_with?("--") }
       require "json"
@@ -557,6 +567,7 @@ module Samagotchi
         @stdout.puts "Built #{result[:files].size} file(s) to #{result[:out_path]}"
         @stdout.puts "Bundle: #{result[:name]} v#{result[:version]} scope=#{result[:scope]}"
         @stdout.puts "Files: #{result[:files].join(', ')}" unless result[:files].empty?
+        builder.warnings.each { |w| @stdout.puts w }
         unless result[:placeholder_warnings].empty?
           @stdout.puts "Placeholders:"
           result[:placeholder_warnings].each { |w| @stdout.puts "  #{w}" }

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

@@ -1,11 +1,11 @@
 ---
 name: samagotchi-system
-version: 0.15.0
+version: 0.17.0
 scope: system
 description: Default system memories — identity, self map, config modification protocol, memory guide and the delegated-session rules
 files:
   identity.md: sha256:29c2f7df9f6c5acbc5ec17000a4490741e55e426af15ca0d81c8706edd9bd027
-  self_map.md: sha256:93c788fadaf98adeb8946b4a357d2372bd6ebb439042d7cef8dda8fb44187315
+  self_map.md: sha256:69bc0ec091fdaeedf6e3aa7365275461fe3eba32b2dedc9cf45044176c356af5
   config_modification_protocol.md: sha256:d0e9d4a84652bf54ec2fd664f61c536637af9decdd22fcd982f52195bf9f5fb4
-  memory_guide.md: sha256:81b911b9a015f0924c48162b3dc4b6376309e743765074419a99fab46e480858
+  memory_guide.md: sha256:e535e31fcf29b4b32c270042851ecdd5f412ef2e3c56b0076963e3e1f1a08ef8
   delegated.md: sha256:0a71d5dfa7127df2d51cb5f0e7214240ed88777e36559430a8724c796d7ae561

data/lib/samagotchi/bundles/system/memory_guide.md

@@ -16,7 +16,7 @@ This memory teaches you (the agent) how to use Samagotchi memories — persisten
 | `project` | `<system dir>/projects/<basename>_<hash>/` (`MemoryPaths.project_dir`: `basename(root)` + 8-char `MD5(root)`, root = `MemoryPaths.project_root`) | Repo-specific conventions, workflow, stack decisions |
 
 - The project root is the git repository: its common git dir, which every linked worktree shares. All worktrees and subdirectories of one repository share one project folder; the system prompt shows the resolved root and folder. Outside a repository the root is the working directory. A separate clone is a different project.
-- `index.md` lives in each scope dir and contains auto-managed lines like `- **name** · scope · date · bytes — description`. Your free-form sections in `index.md` are preserved but managed lines are owned by `memory_write` (and refreshed when `write`/`edit` change a memory's file).
+- `index.md` lives in each scope dir and contains auto-managed lines like `- **name** · scope · date · bytes — description`; a memory a bundle installed adds `· from <bundle>` before the description. Your free-form sections in `index.md` are preserved but managed lines are owned by `memory_write` (and refreshed when `write`/`edit` change a memory's file).
 
 ## Tools you have
 
@@ -85,13 +85,13 @@ Bundles are versioned directories/zips/tar.gz/git URLs with a `manifest.yml` and
 
 | Command | Purpose |
 |---------|---------|
-| `install <source> [--scope system\|project] [--force]` | Install from dir/zip/tar.gz/git URL. `--force` overwrites existing entries, otherwise skips. Writes provenance to `.bundles/<name>/` (base snapshots + `manifest.json`) and updates `index.md`. Warns on double-brace placeholders and checksum mismatches (strict mode). |
+| `install <source> [--scope system\|project] [--force]` | Install from dir/zip/tar.gz/git URL. `--force` overwrites existing entries, otherwise skips them; a skipped file stays the user's (not recorded, never upgraded or removed by the bundle). Writes provenance to `.bundles/<name>/` (base snapshots + `manifest.json`) and updates `index.md`. Warns on double-brace placeholders and checksum mismatches (strict mode). |
 | `upgrade <source> [--force] [--dry-run] [--agent]` | 3-way merge upgrade (base vs current vs incoming) per `Merger.classify`: `install` (new file), `noop` (current==incoming), `fast_forward` (current==base, not edited → auto-update), `keep` (incoming==base → preserve local edits), `conflict` (both edited → warn, needs `--force` or interactive `memory_write` resolution). Pruned files (removed from new bundle) are kept if locally edited, otherwise warned. |
-| `uninstall <bundle> [--force]` | Removes bundle files (skips locally edited files unless `--force`) and `index.md` lines, deletes provenance dir. |
+| `uninstall <bundle> [--force]` | Moves the bundle's memory files to `.bundles/.trash/<bundle>-<time>/` (refuses locally edited ones unless `--force`; keeps a file another installed bundle also lists), removes their `index.md` lines, deletes the provenance dir. |
 | `status [<bundle>]` | Provenance + per-file `ok|modified|missing|no-index` vs stored checksum and base snapshot. |
 | `diff <bundle> [file]` | Prints `base` (provenance snapshot) vs `current` (on-disk) for each file. |
 | `list` | Lists installed bundles (`name v<version> scope files installed_at`, plus the shipped version when newer) and the bundles shipped with chi that are not installed (`install <name>` installs one), grouped under their profile; an installed profile shows `includes=` and `left out=`. |
-| `build [--scope system\|project] [--name NAME] [--version VER] [--description DESC] [--out PATH] [FILES...]` | **Inverse of install** — builds a shareable bundle from local memories and installed hooks. Infers `zip` vs `dir`/`tar.gz` from `--out` extension; default `chi_system_memories.zip` (system) or `chi_<repo>_memories.zip` (project, named after the project root) v`1.0.0` in `Dir.pwd`. `FILES...` is an optional allowlist of memory basenames (`identity` or `identity.md`); if omitted, all `*.md` except `index.md`/hidden/non-md are included. Installed hooks are copied to `hooks/` with their manifest metadata. Computes `sha256:` checksums and writes `manifest.yml` via `Manifest.write`. No provenance write. |
+| `build [--scope system\|project] [--name NAME] [--version VER] [--description DESC] [--out PATH] [FILES...]` | **Inverse of install** — builds a shareable bundle from local memories and installed hooks. Infers `zip` vs `dir`/`tar.gz` from `--out` extension; default `chi_system_memories.zip` (system) or `chi_<repo>_memories.zip` (project, named after the project root) v`1.0.0` in `Dir.pwd`. `FILES...` is an optional allowlist of memory basenames (`identity` or `identity.md`); if omitted, all `*.md` except `index.md`/hidden/non-md and the memories other installed bundles own (each named in a `Left out` line) are included. Installed hooks are copied to `hooks/` with their manifest metadata. Computes `sha256:` checksums and writes `manifest.yml` via `Manifest.write`. No provenance write. |
 
 **Scope resolution for install/build:**
 - CLI `--scope` wins over `manifest.yml` `scope`. Default is `system` if none given (`Installer#run`). For `project`, target is the project folder `<system dir>/projects/<basename>_<hash>` of the project root (`Installer#resolve_target_dir`).
@@ -119,7 +119,7 @@ chi bundle build --scope system --out updated.zip
 ### Provenance internals (for debugging)
 
 - Each installed bundle is recorded at `<system dir>/.bundles/<name>/manifest.json` + `bases/<file>.md` snapshots (`Provenance`). Used only for upgrade `Merger` and `status`/`diff`. Build does **not** write provenance.
-- `index.md` is best-effort — failures are swallowed (`Installer#update_target_index`).
+- A bundle records only the files it wrote. `index.md` updates aren't fatal: a failed one is a warning in the install/uninstall output.
 
 ## Best practices for the agent
 

data/lib/samagotchi/bundles/system/self_map.md

@@ -3,6 +3,7 @@
 ## Start here
 - `chi self` (via `execute`) prints my version, **source dir**, config path, hooks dir,
   memory dirs, sessions dir, model/host and bundles. Use its source dir; don't hunt via `which`/`gem list`/`find /`.
+  Its `model` row is this session's model (live after `/model`), `model key` my overlay key.
 - My current session id is in the system prompt; resume with `chi --resume <id>`.
 - My debug log is the `log` line of `chi self` (default `$XDG_STATE_HOME/samagotchi/samagotchi.log`,
   next to the sessions dir; not `~/.local/state` when `XDG_STATE_HOME` is set). One record per line,
@@ -25,7 +26,8 @@
 - `delegate` hands a task to a child session that runs in parallel and returns only its final
   reply (`delegate_result` waits for it; `session:` sends a follow-up to a child). A child is a
   normal session: it shows in `chi sessions list` with `↳ <parent>`, and the user can steer it
-  with `chi --attach <id>`; see `docs/sessions.md` "Delegating".
+  with `chi --attach <id>`. While I wait for a child, its tool approvals go to my user as my own
+  approvals (I see only how each was answered); see `docs/sessions.md` "Delegating".
 - Bundles extend me: memories, `hooks/*.rb`, `guardrails/*.yml`, and a `plugin.rb` that adds slash
   commands (`anytime:` ones run mid-turn), model tools (they can return images I see), hooks,
   cards, side answers (`ask_model`),

data/lib/samagotchi/empty_answer_retry.rb

@@ -41,7 +41,8 @@ module Samagotchi
       used_tokens.to_f / window_tokens >= CONTEXT_FULL_RATIO
     end
 
-    attr_reader :limit
+    # @return [Integer] the budget, and the attempts spent this turn
+    attr_reader :limit, :attempts
 
     def initialize(limit: self.class.limit)
       @limit = limit