samagotchi 0.159.0 → 0.161.0

data/lib/samagotchi/bridge/card_store.rb

@@ -4,6 +4,7 @@ require "json"
 require "fileutils"
 require_relative "../atomic_file"
 require_relative "../events"
+require_relative "../state_format"
 require_relative "card_places"
 
 module Samagotchi
@@ -62,6 +63,11 @@ module Samagotchi
     # count becomes +base_since+, and new openings add to it (#seed_v1).
     class CardStore
       CAPACITY = 20
+      FORMAT_VERSION = 2
+      FORMAT = StateFormat.new(
+        version: FORMAT_VERSION,
+        members: [StateFormat.required(:type), StateFormat.extra(:extra, in_version: FORMAT_VERSION)]
+      )
       NOTICE_TYPES = %i[hook_notice guardrail_warning empty_answer_retry steer_cut].freeze
       # Capped apart from the notices.
       LLM_CONTEXT_TYPES = %i[llm_context_edited].freeze
@@ -98,6 +104,8 @@ module Samagotchi
         @mutex = Mutex.new
         @entries = []
         @turn_log = []
+        @file_extra = {}
+        @format_read_only = false
         @running_turn = nil
         @continuing = false
         @failed_turn = nil
@@ -180,13 +188,14 @@ module Samagotchi
 
       def save
         return unless @path
+        return if @format_read_only
 
         entries = @entries.reject { |entry| entry[:type] == :guardrail_warning }
         # A session that never showed one gets no file.
         return if entries.empty? && !File.exist?(@path)
 
         FileUtils.mkdir_p(File.dirname(@path))
-        saved = { "version" => 2, "turn_log" => pruned_log(entries), "entries" => entries }
+        saved = @file_extra.merge("version" => FORMAT_VERSION, "turn_log" => pruned_log(entries), "entries" => entries)
         saved["failed_turn"] = @failed_turn if @failed_turn
         AtomicFile.write(@path, JSON.generate(saved))
       rescue StandardError
@@ -222,15 +231,34 @@ module Samagotchi
         return unless @path && File.file?(@path)
 
         data = JSON.parse(File.read(@path), symbolize_names: true)
-        return unless data.is_a?(Hash) && data[:entries].is_a?(Array)
+        return unless data.is_a?(Hash)
+
+        format_data = data.transform_keys(&:to_s)
+        format_data["entries"] = if data[:entries].is_a?(Array)
+                                   data[:entries].map { |entry| entry.is_a?(Hash) ? entry.transform_keys(&:to_s) : entry }
+                                 else
+                                   data[:entries]
+                                 end
+        document = FORMAT.read(format_data, collection: "entries")
+        if document.version > FORMAT_VERSION
+          raise StateFormat::InvalidDocument,
+                "cards.json has format version #{document.version}, newer than supported #{FORMAT_VERSION}; update chi before writing it"
+        end
+        @file_extra = document.extra.except("version", "entries", "turns", "turn_log", "failed_turn")
+        return unless data[:entries].is_a?(Array)
 
         if data[:turn_log].is_a?(Array)
           @turn_log = data[:turn_log].grep(String)
           @failed_turn = data[:failed_turn] if data[:failed_turn].is_a?(String)
-          @entries = seeded(data[:entries])
+          @entries = seeded(document.entries.map { |entry| entry.to_h.transform_keys(&:to_sym) })
         elsif data[:turns].is_a?(Integer)
           seed_v1(data)
         end
+      rescue StateFormat::InvalidDocument => e
+        @format_read_only = true
+        @turn_log = []
+        @entries = []
+        Log.warn(:bridge, "card_store_unreadable", error: e.message)
       rescue StandardError
         @turn_log = []
         @entries = []

data/lib/samagotchi/bridge/ring_buffer.rb

@@ -18,13 +18,17 @@ module Samagotchi
         @capacity = [1, capacity].max
         @mutex = Monitor.new
         @events = [] # Array<{seq:, data:}>
+        @dropped = false
       end
 
       # Append +data+ keyed by +seq+ (drop oldest beyond capacity).
       def push(seq:, data:)
         @mutex.synchronize do
           @events << { seq: seq, data: data }
-          @events.shift until @events.size <= @capacity
+          while @events.size > @capacity
+            @events.shift
+            @dropped = true
+          end
           nil
         end
       end
@@ -45,6 +49,12 @@ module Samagotchi
         @mutex.synchronize { @events.first&.[](:seq) }
       end
 
+      # @return [Boolean] whether a push has ever evicted an event: the window
+      # no longer starts where the capture did.
+      def dropped?
+        @mutex.synchronize { @dropped }
+      end
+
       def empty?
         @mutex.synchronize { @events.empty? }
       end

data/lib/samagotchi/bridge/sse_writer.rb

@@ -161,16 +161,19 @@ module Samagotchi
       def replay!(io, snapshot_seq)
         from_seq = @high_water
         oldest = @ring.oldest_seq
-        if @foreign_cursor || from_seq > snapshot_seq || (from_seq.positive? && oldest && from_seq < oldest - 1)
+        if @foreign_cursor || from_seq > snapshot_seq || (oldest && from_seq < oldest - 1 && (from_seq.positive? || @ring.dropped?))
           # Cursor is from another worker (epoch), ahead of the engine (a
           # worker restarted, plain cursor) or behind the
           # ring's buffered window (overflow): the server cannot replay the
           # gap, so it emits a reset marker and the client re-syncs. A cursor
           # at oldest - 1 has seen everything before the window, so it
-          # replays. A cold
-          # connect (from_seq == 0) replays the whole served window, and a
-          # fully caught-up cursor (from_seq == snapshot_seq) is NOT a reset
-          # case — it gets an empty replay and holds for live events.
+          # replays. A cold connect (from_seq == 0) is behind the window too
+          # once the ring has evicted an event (it would start mid-turn), so
+          # it resets; on a ring that never evicted (its first seq may be
+          # above 1: events before the Bridge started) it replays the whole
+          # window. A fully caught-up cursor (from_seq == snapshot_seq)
+          # is NOT a reset case — it gets an empty replay and holds for live
+          # events.
           emit_reset(io)
         else
           @ring.events_in_range(after_seq: from_seq, to_seq: snapshot_seq).each { |record| write_event(io, record[:data]) }

data/lib/samagotchi/bridge.rb

@@ -9,6 +9,7 @@ require "openssl"
 require "time"
 require_relative "atomic_file"
 require_relative "bridge_secret"
+require_relative "command_intake"
 require_relative "degrade"
 require_relative "delivery"
 require_relative "session_inbox"
@@ -159,6 +160,9 @@ module Samagotchi
       @connection_threads = []
       @stopped = false
       @mutex = Monitor.new
+      @post_turn_mutex = Mutex.new
+      @enqueued_requests = {}
+      @enqueued_request_order = []
       @refused_log_mutex = Mutex.new
       @refused_logged_at = {}
       @open_streams = 0
@@ -766,14 +770,23 @@ module Samagotchi
     def handle_cancel(_session_id, body)
       # Optional reason from JSON body
       reason = :manual
+      turn_id = nil
       if body && !body.strip.empty?
         parsed = parse_json(body)
         r = parsed.is_a?(Hash) ? (fetched(parsed, "reason") || fetched(parsed, "cancellation_reason")) : nil
         reason = CANCEL_REASONS.include?(r.to_s.strip) ? r.to_s.strip.to_sym : :manual
+        turn_id = fetched(parsed, "turn_id").to_s.strip if parsed.is_a?(Hash)
+        turn_id = nil if turn_id && turn_id.empty?
       end
 
       if @engine.turn_running? && @engine.active_cancel_controller
-        ok = @engine.cancel_current_turn!(reason)
+        # With a turn_id the engine compares it to the running turn's under
+        # its lock; clients that send none (older ones) cancel whichever runs.
+        ok = turn_id ? @engine.cancel_current_turn!(reason, turn_id: turn_id) : @engine.cancel_current_turn!(reason)
+        if ok == :turn_mismatch
+          return [{}, 409, { error: "turn_mismatch", detail: "the running turn is not the one named", session_id: @session_id }]
+        end
+
         return [{}, 202, { status: "cancel_requested", session_id: @session_id, reason: reason.to_s }] if ok
 
         [{}, 409, { error: "cancel_failed", detail: "could not cancel", session_id: @session_id }]
@@ -1195,34 +1208,60 @@ module Samagotchi
       # 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.
+      # for the model. Only from a sender that may send commands
+      # (CommandIntake.allowed?: a person, chi answer): a delegate's, a
+      # schedule's or a plugin's /word line is a prompt, its shell line
+      # refused (403, nothing queued).
       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, author: author)
+        if CommandIntake.allowed?(client_id)
+          return queue_command_request(sid, prompt.to_s.strip, client_id: client_id, deadline: deadline, author: author)
+        elsif CommandIntake.shell_line?(prompt)
+          Log.warn(:bridge, "shell_line_refused", client_id: client_id)
+          return [{}, 403, { error: CommandIntake::REFUSED_ERROR, detail: CommandIntake::REFUSED }]
+        end
       end
 
-      enqueued_id = SecureRandom.uuid
+      enqueued_id = fetched(parsed, "enqueued_id")
+      enqueued_id = SessionInbox.new_enqueued_id unless SessionInbox.valid_enqueued_id?(enqueued_id)
+      enqueue_post_turn(sid: sid, prompt: prompt, client_id: client_id, no_interrupt: no_interrupt, author: author,
+                        anchors: anchors, images: images, delivery: delivery, deadline: deadline, pending_limit: pending_limit,
+                        enqueued_id: enqueued_id)
+    end
+
+    def enqueue_post_turn(sid:, prompt:, client_id:, no_interrupt:, author:, anchors:, images:, delivery:, deadline:,
+                          pending_limit:, enqueued_id:)
       # Before it is queued: a drain after this may have taken it (#cut_for_steer).
-      epoch = @engine.input_epoch
-      # Whether a queue waits for a running turn: read with the write under
-      # the event log, so no :turn_started or :turn_completed falls between.
-      # To an idle worker the queued file simply runs as the next turn.
-      queued_behind_turn = false
-      # Write and announce with the event log held: the worker can't emit
-      # this turn's :turn_started (or merge it mid-turn) before
-      # :turn_enqueued, and a failed write announces nothing.
-      enqueued = @engine.synchronize_events do
-        raise IntakeClosed if stopped?
-        next :expired if expired?("turn_expired", deadline, sid: sid, client_id: client_id)
-        next :too_many if pending_limit && pending_turns(author) >= pending_limit
-
-        # The owner's input never goes into a participant's read-only
-        # review turn (a steer, a cut): it queues behind it as the owner's
-        # own turn, and the ack and :turn_enqueued say so.
-        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, anchors: anchors).tap do |ok|
-          next unless ok
+      @post_turn_mutex.synchronize do
+        epoch = @engine.input_epoch
+        # Whether a queue waits for a running turn: read with the write under
+        # the event log, so no :turn_started or :turn_completed falls between.
+        # To an idle worker the queued file simply runs as the next turn.
+        queued_behind_turn = false
+        # Write and announce with the event log held: the worker can't emit
+        # this turn's :turn_started (or merge it mid-turn) before
+        # :turn_enqueued, and a failed write announces nothing.
+        enqueued = @engine.synchronize_events do
+          raise IntakeClosed if stopped?
+
+          existing = @enqueued_requests[enqueued_id]
+          if existing
+            next(existing[:prompt] == prompt.to_s ? :duplicate : :conflict)
+          end
+          next :duplicate if @engine.enqueued_id?(enqueued_id)
+          next :expired if expired?("turn_expired", deadline, sid: sid, client_id: client_id)
+          next :too_many if pending_limit && pending_turns(author) >= pending_limit
+          next :duplicate unless @engine.reserve_enqueued_id(enqueued_id)
+
+          # The owner's input never goes into a participant's read-only
+          # review turn (a steer, a cut): it queues behind it as the owner's
+          # own turn, and the ack and :turn_enqueued say so.
+          delivery = Delivery::QUEUE if @accumulator.participant_turn?
+          queued_behind_turn = Delivery.queue?(delivery) && !@accumulator.current_turn.nil?
+          unless enqueue_turn(prompt: prompt, client_id: client_id, enqueued_id: enqueued_id,
+                              no_interrupt: no_interrupt, images: images, delivery: delivery, author: author, anchors: anchors)
+            @engine.forget_enqueued_id(enqueued_id)
+            next false
+          end
 
           enqueued_event = { type: :turn_enqueued, enqueued_id: enqueued_id, client_id: client_id, prompt: prompt.to_s }
           enqueued_event[:images] = images unless images.empty?
@@ -1230,26 +1269,43 @@ module Samagotchi
           enqueued_event[:author] = author if author
           @engine.announce(enqueued_event)
           @on_input&.call
+          true
+        end
+        if enqueued == :duplicate
+          ack = @enqueued_requests.dig(enqueued_id, :ack) ||
+                { status: "accepted", enqueued_id: enqueued_id, session_id: @session_id }
+          return [{}, 202, ack]
+        end
+        if enqueued == :conflict
+          return [{}, 409, { error: "enqueued_id_conflict",
+                             detail: "enqueued_id was already accepted for a different prompt" }]
         end
+        return deadline_passed("turn") if enqueued == :expired
+        return [{}, 429, { error: "too_many_turns", detail: ParticipantMessages::TOO_MANY_TURNS }] if enqueued == :too_many
+        return [{}, 500, { error: "enqueue_failed", detail: "could not write turn input" }] unless enqueued
+
+        # Queued (outside the event lock): a message sent as +cut+ cuts a
+        # running generation that has only been thinking for long, unless a
+        # plugin or a client chi doesn't know sent it. An image input never
+        # merges mid-turn, so it never cuts. Nothing else cuts: a message
+        # that says nothing (an older client, the web composer) goes in at
+        # the running turn's next step.
+        cut = nil
+        cut = @engine.cut_for_steer(Steer.source_for_client(client_id), epoch: epoch) if images.empty? && Delivery.cut?(delivery)
+        # A queue to an idle worker is a turn now: the ack says next_step.
+        ack_delivery = Delivery.queue?(delivery) && !queued_behind_turn ? Delivery::NEXT_STEP : delivery
+        ack = { status: "accepted", enqueued_id: enqueued_id, session_id: @session_id, delivery: ack_delivery }
+        ack[:cut] = cut.to_s if cut
+        ack[:cut_after] = @engine.steer_cut_after if cut == :waits
+        remember_enqueued_request(enqueued_id, prompt, ack)
+        [{}, 202, ack]
       end
-      return deadline_passed("turn") if enqueued == :expired
-      return [{}, 429, { error: "too_many_turns", detail: ParticipantMessages::TOO_MANY_TURNS }] if enqueued == :too_many
-      return [{}, 500, { error: "enqueue_failed", detail: "could not write turn input" }] unless enqueued
-
-      # Queued (outside the event lock): a message sent as +cut+ cuts a
-      # running generation that has only been thinking for long, unless a
-      # plugin or a client chi doesn't know sent it. An image input never
-      # merges mid-turn, so it never cuts. Nothing else cuts: a message
-      # that says nothing (an older client, the web composer) goes in at
-      # the running turn's next step.
-      cut = nil
-      cut = @engine.cut_for_steer(Steer.source_for_client(client_id), epoch: epoch) if images.empty? && Delivery.cut?(delivery)
-      # A queue to an idle worker is a turn now: the ack says next_step.
-      ack_delivery = Delivery.queue?(delivery) && !queued_behind_turn ? Delivery::NEXT_STEP : delivery
-      ack = { status: "accepted", enqueued_id: enqueued_id, session_id: @session_id, delivery: ack_delivery }
-      ack[:cut] = cut.to_s if cut
-      ack[:cut_after] = @engine.steer_cut_after if cut == :waits
-      [{}, 202, ack]
+    end
+
+    def remember_enqueued_request(id, prompt, ack)
+      @enqueued_requests[id] = { prompt: prompt.to_s, ack: ack }
+      @enqueued_request_order << id
+      @enqueued_requests.delete(@enqueued_request_order.shift) while @enqueued_requests.size > TurnState::ENQUEUED_ID_HISTORY
     end
 
     # POST /session/:id/turn/dequeue {enqueued_id, client_id?, deadline?}:
@@ -1281,7 +1337,10 @@ module Samagotchi
         next [:expired, nil] if expired?("dequeue_expired", deadline, sid: session_id, enqueued_id: id)
 
         SessionInbox.take_queued_input(session_dir, id).tap do |status, _|
-          @engine.announce(type: :turn_dequeued, enqueued_id: id, client_id: client_id) if status == :removed
+          if status == :removed
+            @engine.drop_enqueued_id(id)
+            @engine.announce(type: :turn_dequeued, enqueued_id: id, client_id: client_id)
+          end
         end
       end
       dequeue_reply(taken, id, input)

data/lib/samagotchi/bridge_client.rb

@@ -8,6 +8,7 @@ require_relative "degrade"
 require_relative "worker_sidecar"
 require_relative "bridge_secret"
 require_relative "delivery"
+require_relative "session_inbox"
 require_relative "chi_invocation"
 require_relative "bridge_client/stream_open"
 require_relative "bridge_client/sse_parser"
@@ -197,9 +198,10 @@ module Samagotchi
     #   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,
-                  anchors: nil)
-      body = { session_id: @session_id, prompt: prompt, client_id: client_id }
+    def post_turn(prompt:, client_id: nil, enqueued_id: nil, no_interrupt: false, images: nil, delivery: nil, author: nil,
+                  pending_limit: nil, anchors: nil)
+      body = { session_id: @session_id, prompt: prompt, client_id: client_id,
+               enqueued_id: enqueued_id || SessionInbox.new_enqueued_id }
       body[:no_interrupt] = true if no_interrupt
       body[:author] = author if author
       body[:pending_limit] = pending_limit if author && pending_limit
@@ -246,10 +248,11 @@ module Samagotchi
     end
 
     # POST /session/:id/cancel. 202 = requested (body names the reason the
-    # Bridge took), 409 = no active turn.
+    # Bridge took), 409 = no active turn, or (error "turn_mismatch") not the
+    # +turn_id+ named: nothing was cancelled.
     # @return [Response]
-    def cancel(reason:)
-      post("cancel", { reason: reason }, read_body: true)
+    def cancel(reason:, turn_id: nil)
+      post("cancel", { reason: reason, turn_id: turn_id }.compact, read_body: true)
     end
 
     # POST /session/:id/tasks/stop: stop a background task this session's

data/lib/samagotchi/broadcast/scope_card.rb

@@ -46,7 +46,8 @@ module Samagotchi
         session = Session.load(recipient.id, state_dir: state_dir)
         prompts = user_texts(session.messages)
         branch = GitHead.branch(session.working_directory)
-        sources = ContextSources.attached(session.id, project_root: session.project_root, state_dir: state_dir)
+        sources = ContextSources.attached(session.id, project_root: session.project_root, project_id: session.project_id,
+                                                      state_dir: state_dir)
                                 .map { |attached| [attached.name, attached.source.hint] }
         ScopeCard.new(id: session.id, project: recipient.project && File.basename(recipient.project),
                       folder: folder(session.working_directory, recipient.project), branch: branch,

data/lib/samagotchi/broadcast_command.rb

@@ -249,13 +249,20 @@ module Samagotchi
     # +decisions+, prints a line per recipient and the summary, and logs it.
     def deliver_all(broadcast, decisions, cards)
       ok = true
+      # Two links of one chain are one session: the note goes once (Head).
+      got = {}
       lines = decisions.map do |d|
         next [d, "skipped", d.verdict.reason] unless d.deliver?
 
+        head = SessionInbox::Head.resolve(:note, d.recipient.id, state_dir: @state_dir)
+        next [d, "skipped", "#{head.id[0, 8]}, its chain's newest link, got it already"] if got[head.id]
+
         result = NoteDelivery.deliver(d.recipient.id, text: body(broadcast.text, d.verdict), source: SOURCE,
-                                                      state_dir: @state_dir)
+                                                      state_dir: @state_dir, resolved: head)
         next [d, "skipped", OwnerLock::TUI_BUSY] unless result.delivered?
 
+        got[result.id] = true
+
         [d, "delivered", "#{d.verdict.reason}#{"; waits for its next start" if result.status == :waits}"]
       rescue SessionInbox::NoteRejected, SystemCallError => e
         ok = false
@@ -333,7 +340,9 @@ module Samagotchi
         return 1
       end
       ids = sessions.map { |given| resolve_session(given) }
-      results = ids.compact.uniq.map { |id| deliver_anyway(record, id) }
+      # Two links of one chain are one session: the note goes once (Head).
+      results = ids.compact.map { |id| SessionInbox::Head.resolve(:note, id, state_dir: @state_dir) }
+                   .uniq(&:id).map { |head| deliver_anyway(record, head) }
       unless results.empty?
         begin
           @log.append_correction(id: record.id, at: @now, sessions: results)
@@ -359,22 +368,29 @@ module Samagotchi
       nil
     end
 
-    # @param id [String] a full session id (#resolve_session)
+    # @param head [SessionInbox::Resolved] the session named (+asked+, a full
+    #   id: #resolve_session) and the link that gets it (a continued one's
+    #   chain's newest)
     # @return [Broadcast::TriageLog::Delivery]
-    def deliver_anyway(record, id)
-      if record.delivered?(id)
+    def deliver_anyway(record, head)
+      id = head.asked
+      if record.delivered?(id) || record.delivered?(head.id)
         @stdout.puts(line_for(id, "skipped", "it got #{record.id} already"))
         return Broadcast::TriageLog::Delivery.new(session: id, result: "had it")
       end
 
-      result = NoteDelivery.deliver(id, text: passed_on_body(record), source: SOURCE, state_dir: @state_dir)
+      result = NoteDelivery.deliver(id, text: passed_on_body(record), source: SOURCE, state_dir: @state_dir,
+                                        resolved: head)
       unless result.delivered?
         @stdout.puts(line_for(id, "skipped", OwnerLock::TUI_BUSY))
         return Broadcast::TriageLog::Delivery.new(session: id, result: "refused")
       end
 
-      @stdout.puts(line_for(id, "delivered", "by hand#{"; waits for its next start" if result.status == :waits}"))
-      Broadcast::TriageLog::Delivery.new(session: id, result: "delivered")
+      how = "by hand#{"; to #{result.id[0, 8]}, its chain's newest link" if result.continued?}" \
+            "#{"; waits for its next start" if result.status == :waits}"
+      @stdout.puts(line_for(id, "delivered", how))
+      # Logged under the link that has it, so the next deliver finds it.
+      Broadcast::TriageLog::Delivery.new(session: result.id, result: "delivered")
     rescue SessionInbox::NoteRejected, SystemCallError => e
       @stdout.puts(line_for(id, "failed", e.message))
       Broadcast::TriageLog::Delivery.new(session: id, result: "failed")

data/lib/samagotchi/bundle_command.rb

@@ -2,6 +2,7 @@
 
 require_relative "cli/flags"
 require_relative "cli/exit"
+require_relative "live_versions"
 require_relative "memory_bundle"
 
 module Samagotchi
@@ -17,6 +18,7 @@ module Samagotchi
           Source is the path/URL to the bundle (dir/zip/tar.gz/git).
           --force overwrites existing entries (one that differs is copied to the trash first); default skips them.
           A bundle whose requires_chi this chi doesn't meet is refused; --force installs it anyway.
+          So is a memory, plugin or script whose bytes disagree with its manifest sha256; --force installs it too.
 
         upgrade <source|name> [--scope system|project] [--force] [--dry-run] [--agent|--no-agent]
           Upgrade a bundle (3-way: a file you didn't edit updates; one you edited takes a text
@@ -24,6 +26,7 @@ module Samagotchi
           A bare NAME upgrades the bundle installed under that name from the source it came from.
           --dry-run shows what would change. --agent launches interactive session on conflict.
           A bundle whose requires_chi this chi doesn't meet is refused; --force installs it anyway.
+          So is a file whose bytes disagree with its manifest sha256; --force installs it too.
 
         uninstall <bundle> [--scope system|project] [--force]
           Remove a bundle and its index entries (--force moves a locally edited file to the trash).
@@ -73,8 +76,8 @@ module Samagotchi
           Install a memory bundle from a directory, zip, tar archive, or git URL,
           or a bundle shipped with chi by name (see: chi bundle list).
           --force overwrites existing entries (one that differs is copied to the trash first); default skips them.
-          It also installs a bundle whose requires_chi this chi doesn't meet: without --force that install is
-          refused, and the bundle is not written anywhere.
+          It also installs a bundle whose requires_chi this chi doesn't meet and a file whose bytes disagree with
+          its manifest sha256: without --force both are refused, and the bundle is not written anywhere.
         install --dev PATH
           Install the bundle in the local directory PATH as a link to it: its plugin, rules and scripts
           are PATH's own files (an edit applies at the next worker or chi web restart, with no re-install) and
@@ -83,8 +86,9 @@ module Samagotchi
     TEXT
     UPGRADE_HELP = <<~TEXT
       Usage: chi bundle upgrade <source|name> [--scope system|project] [--force] [--dry-run] [--agent|--no-agent]
-        --force takes the bundle's file over an edited one, and installs a bundle whose requires_chi this chi
-        doesn't meet (without it such a bundle is refused).
+        --force takes the bundle's file over an edited one, installs a bundle whose requires_chi this chi
+        doesn't meet, and installs a file whose bytes disagree with its manifest sha256 (without it each is
+        refused, nothing written).
     TEXT
     UNINSTALL_HELP = "Usage: chi bundle uninstall <bundle> [--scope system|project] [--force]"
     BUILD_HELP = <<~TEXT
@@ -246,7 +250,12 @@ module Samagotchi
         end
       end
       installer = installer_for(expanded_source, bundle_name, prepared: prepared, scope: scope, force: force, upgrade: true, dry_run: dry_run)
-      run_installer(installer, failed: "Upgrade") do |manifest|
+      # The record and the manifest as they were/are, for the hint below: it
+      # reads which plugin the run touched.
+      before = Samagotchi::MemoryBundle::Provenance.new(name: bundle_name).record
+      manifest = nil
+      status = run_installer(installer, failed: "Upgrade") do |run_manifest|
+        manifest = run_manifest
         print_plugin(manifest, plugin: !dry_run)
         next dry_run_done if dry_run
 
@@ -256,6 +265,8 @@ module Samagotchi
 
         print_provenance(bundle_name, manifest)
       end
+      restart_hint(before, manifest, installer) if !dry_run && status != 1
+      status
     end
 
     # The source normalized once (a git clone, a zip or tar extract) and the
@@ -266,6 +277,7 @@ module Samagotchi
     # @return [Array(MemoryBundle::PreparedSource, String), nil]
     def prepare_or_fail(expanded_source, word)
       prepared = Samagotchi::MemoryBundle::PreparedSource.prepare(expanded_source)
+      Samagotchi::MemoryBundle::Manifest::HooksRetired.refuse_source_files(prepared.dir)
       named = [prepared, Samagotchi::MemoryBundle::Manifest.read(dir: prepared.dir).name]
     rescue Samagotchi::MemoryBundle::SourceNormalizer::UnknownSourceError,
            Samagotchi::MemoryBundle::Manifest::ValidationError => e
@@ -299,7 +311,10 @@ module Samagotchi
     end
 
     def installer_for(source, name, scope:, force:, **)
-      Samagotchi::MemoryBundle::Installer.new(source: source, name: name, scope: scope, force: force, strict: true, **)
+      # A bundle the user installs: a memory, plugin or script whose bytes
+      # disagree with its manifest sha is refused, not warned (--force past it).
+      Samagotchi::MemoryBundle::Installer.new(source: source, name: name, scope: scope, force: force, strict: true,
+                                              refuse_mismatch: true, **)
     end
 
     # Runs +installer+, prints its summary, then yields the manifest.
@@ -339,6 +354,41 @@ module Samagotchi
       0
     end
 
+    # A run wrote or took away a file (Installer#results' words).
+    CHANGED_WORDS = %i[installed updated merged removed restored].freeze
+
+    # Only a bundle's plugin stays in a worker's memory: its rules reload by
+    # their stamp (GuardrailWiring#rules_stamp), its scripts run from the files
+    # the install replaced, and chi no longer loads class-file hooks. So an
+    # upgrade or uninstall that changed the plugin -- or brought one in --
+    # leaves the old code in every session already up: one line, after the
+    # result, with how many sessions and the command for each. Nothing when the
+    # plugin is unchanged or there never was one, nothing with no worker that
+    # can be restarted.
+    # @param before [InstalledBundle, nil] the bundle's record as it was before
+    #   the run (an uninstall deletes it, so take it first)
+    # @param manifest [MemoryBundle::Manifest, nil] the manifest this run
+    #   installed; nil for an uninstall
+    # @param installer [Installer, nil] the run, for what it wrote to the plugin
+    def restart_hint(before, manifest = nil, installer = nil)
+      return if before.nil? || before.error?
+
+      plugin_files = [before.plugin&.file, manifest&.plugin&.dig(:file)].compact.uniq
+      changed = if installer
+                  plugin_files.any? { |file| CHANGED_WORDS.include?(installer.results[file]&.word) }
+                else
+                  !before.plugin.nil?
+                end
+      return unless changed
+
+      ids = Samagotchi::LiveVersions.workers.select(&:restart).map { |worker| worker.session_id.to_s[0, 8] }
+      return if ids.empty?
+
+      commands = ids.map { |id| "chi sessions restart #{id}" }
+      @stdout.puts "#{ids.size} session#{"s" unless ids.size == 1} " \
+                   "#{ids.size == 1 ? "runs" : "run"} the old code: #{commands.join(", ")}"
+    end
+
     # An upgrade that kept edited files: launch an agent to merge them
     # (--agent, or yes on a terminal), or say how to take the bundle's.
     # An upgrade that kept edited files exits 2, as a usage error does
@@ -426,6 +476,7 @@ module Samagotchi
         @stdout.puts uninstaller.trash_copy_line if uninstaller.trash_copy_line
         @stdout.puts "Removed: #{uninstaller.removed_files.join(", ")}" unless uninstaller.removed_files.empty?
         uninstaller.warnings.each { |w| @stdout.puts w }
+        restart_hint(record)
         0
       rescue Samagotchi::MemoryBundle::Uninstaller::UninstallError => e
         @stderr.puts "Uninstall failed: #{e.message}"; 1

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

@@ -1,11 +1,11 @@
 ---
 name: samagotchi-system
-version: 0.159.0
+version: 0.161.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:750822b3488b302c6e32638e6224f270d8e06b50ea85cd6e0bb5a6ff12eed1d8
   config_modification_protocol.md: sha256:44cf7bdac8e526805bff36b76b54fefecd41db30ca525c2ed661d78fe9155dd8
-  memory_guide.md: sha256:91e8fd248a155afad6b825097d9ee0a0215ba0b79092c8ab25501c0fc19dedfc
+  memory_guide.md: sha256:bdd34f34063df1b4ae74f7cda7c31080986d155e535ee4526d673c70edac8292
   delegated.md: sha256:a0d6ddcd4a8be06526d964898611775fd251cfd9d145a9d16afaccaa503597bd

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

@@ -13,7 +13,7 @@ This memory teaches you (the agent) how to use Samagotchi memories — persisten
 | Scope | Path | Use for |
 |-------|------|---------|
 | `system` | `$XDG_CONFIG_HOME/samagotchi/memories/`, default `~/.config/samagotchi/memories/` (`MemoryPaths.system_dir`) | User-wide preferences, identity, cross-project knowledge |
-| `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 |
+| `project` | `<system dir>/projects/<key>/` (`MemoryPaths.project_dir`: a git project's `<basename>_<hash>`, `basename(root)` + 8-char `MD5(root)`, root = `MemoryPaths.project_root`; a marked project's id from its `.chi/project.yml`, `<basename>-<8 hex>`, kept when the folder moves) | 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 that folder (not the root: in a linked worktree, work stays in the worktree). A separate clone is a different project. Outside a repository, a folder marked by `chi project init` (its `.chi/project.yml`) is the project for it and every subfolder; outside both, the root is the working directory.
 - `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).
@@ -122,7 +122,7 @@ Bundles are versioned directories/zips/tar.gz/git URLs with a `manifest.yml` and
 | `build [--scope system\|project] [--name NAME] [--version VER] [--description DESC] [--out PATH] [FILES...]` | **Inverse of install** — builds a shareable bundle from local memories and an installed bundle's plugin, rules and scripts. 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. 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 (`MemoryPaths.scope_dir`).
+- 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/<key>` of the project (`MemoryPaths.scope_dir`).
 
 **Example flows:**
 ```bash