samagotchi 0.148.0 → 0.150.0

data/lib/samagotchi/context_note.rb

@@ -16,11 +16,19 @@ module Samagotchi
     # context_source: the attached context source a note is about
     # (ContextAbsorber), so the UIs can tie it to its chip. A note's wall
     # time (MessageTime::KEY) is every entry's, kept beside these.
-    KEYS = %i[kind note_id source from_session from_cwd context_source].freeze
+    # objectives: the list an objectives note carries (Objectives), string
+    # keys inside.
+    KEYS = %i[kind note_id source from_session from_cwd context_source objectives].freeze
     HEADER = "CONTEXT NOTE"
     # A finished background task's note (TaskFinishNote): a header of its own.
     TASK_HEADER = "TASK FINISHED"
-    HEADERS = [HEADER, TASK_HEADER].freeze
+    # The session's objectives (Objectives): a frame that instructs by itself,
+    # so a session with no list sends no line about them.
+    OBJECTIVES_HEADER = "OBJECTIVES"
+    OBJECTIVES_FRAME = "[#{OBJECTIVES_HEADER}, set by the user. What the user wants this session to achieve; " \
+                       "replaces any earlier list. Keep work on it. Say when something falls outside it. " \
+                       "Don't change it yourself.]".freeze
+    HEADERS = [HEADER, TASK_HEADER, OBJECTIVES_HEADER].freeze
 
     FRAME_HEAD = /\A\[(?:#{HEADERS.map { |h| Regexp.escape(h) }.join("|")})[^\n]*\n/
 
@@ -30,18 +38,22 @@ module Samagotchi
     # note starts a turn chi runs for it (a context wake), as a wake turn's
     # delegate report does (Steer.turn_prompt?). +header+: the frame's
     # (HEADERS), not kept as a key: the content carries it. Its wall time
-    # (MessageTime::KEY) is +created_at+'s, else now.
+    # (MessageTime::KEY) is +created_at+'s, else now. +objectives+: an
+    # objectives note's payload (Objectives::List#to_payload).
     # @return [Hash] the conversation message
     def message(note_id:, text:, source:, created_at: nil, from_session: nil, from_cwd: nil, context_source: nil,
-                turn_start: nil, turn_id: nil, header: HEADER, **)
+                turn_start: nil, turn_id: nil, header: HEADER, objectives: nil, **)
       { role: "system", kind: KIND, note_id: note_id, source: source, from_session: from_session,
-        from_cwd: from_cwd, context_source: context_source, turn_start: (true if turn_start == true), turn_id: turn_id,
+        from_cwd: from_cwd, context_source: context_source, objectives: objectives,
+        turn_start: (true if turn_start == true), turn_id: turn_id,
         content: frame(text, source: source, created_at: created_at, from_session: from_session,
                              from_cwd: from_cwd, header: header),
         MessageTime::KEY => MessageTime.iso_of(created_at) || MessageTime.iso(MessageTime.now) }.compact
     end
 
     def frame(text, source:, created_at: nil, from_session: nil, from_cwd: nil, header: HEADER)
+      return "#{OBJECTIVES_FRAME}\n#{text}\n[END NOTE]" if header == OBJECTIVES_HEADER
+
       time = clock(created_at)
       from = label(source: source, from_session: from_session, from_cwd: from_cwd)
       "[#{header || HEADER} from #{from}#{", #{time}" if time}]\n#{text}\n[END NOTE]"

data/lib/samagotchi/engine.rb

@@ -51,6 +51,7 @@ require_relative "context_candidates"
 require_relative "context_candidates_log"
 require_relative "context_candidate_choice"
 require_relative "context_judge"
+require_relative "objectives_audit"
 require_relative "owner_prompt"
 require_relative "side_judgments"
 require_relative "toolkit_suggest"
@@ -156,6 +157,8 @@ module Samagotchi
       # steers) and the idle layer's activity clock. Built first: a plugin
       # may steer or ask whether a turn runs while it loads.
       @turn_state = TurnState.new(clock: -> { monotonic_now })
+      @objective_proposals = []
+      @objective_proposals_mutex = Mutex.new
       # A message for the running turn cutting its generation.
       @steer_cut = SteerCut.new(clock: -> { monotonic_now }, controller: -> { active_cancel_controller },
                                 cut_after: -> { steer_cut_after })
@@ -767,6 +770,8 @@ module Samagotchi
     # command's ask_model between turns).
     # @return [String, nil]
     def side_author(kind)
+      # Check this is only ever the owner's, whichever turn runs as it ends.
+      return nil if kind.to_s == ObjectivesCheck::SOURCE
       return nil unless turn_running? || kind.to_s == RECAP_SIDE_KIND
 
       @guardrail_wiring.turn_author
@@ -956,7 +961,7 @@ module Samagotchi
     ANNOUNCEABLE_EVENTS = %i[turn_enqueued turn_dequeued input_merged prompt_restored continue_offered continue_resolved
                              command_queued command_ran context_added card hook_notice guardrail_warning
                              plugin_init_started plugin_init_finished working_set_updated participants_changed
-                             verdict_recorded].freeze
+                             verdict_recorded objectives_updated turn_rolled_back].freeze
 
     # Put a transport-level event into the ordered event log. Unlike turn
     # events it reaches only persistent observers (no turn sink, no memory
@@ -987,6 +992,63 @@ module Samagotchi
       synchronize_events { emit_working_set(nil, session, session.messages) }
     end
 
+    # The session's objectives as the page draws them (Objectives.view), when
+    # that differs from the last announced: after an edit (its file written,
+    # pending), once a list note is in, at a turn's end (its moves) and after
+    # a rollback. A session with no list announces nothing. It only informs:
+    # a failure is logged, never the turn's.
+    def announce_objectives(session = @session)
+      return unless session
+
+      synchronize_events do
+        view = Objectives.view(session.id, session.messages, state_dir: session_state_dir, running: live_conversation&.dup)
+        next if view.nil? || view == @objectives_announced
+
+        @objectives_announced = view
+        announce({ type: :objectives_updated, session_id: session.id, **view })
+      end
+    rescue StandardError => e
+      Log.warn(:turn, "objectives_announce_failed", error: e.class.name, msg: e.message)
+    end
+
+    # Check this (ObjectivesCheck)'s one side request. Its usage is in the
+    # session's side line. Raises as ctx.ask_model's request does.
+    # @param request [Array<Hash>] chat messages
+    # @param model [String, nil] a configured model; nil: the session's
+    # @return [String] the answer
+    def ask_objective_check(request, model:)
+      ask_side_model(request, timeout: ObjectivesCheck::TIMEOUT_SECONDS, max_tokens: ObjectivesCheck::MAX_TOKENS,
+                              cancel_controller: nil, model: model, source: ObjectivesCheck::SOURCE)
+    end
+
+    # A change the model proposes (the objectives tool), kept until the turn
+    # is over, as #context_choice's cards are: a card shown then is a quiet one, between turns, with its Apply kept
+    # over a restart (CardStore), not a running turn's that says it waits on the
+    # user. The same change twice in a turn is one card.
+    # @return [Boolean] false past Objectives::PROPOSALS_PER_TURN
+    def propose_objective(proposal)
+      @objective_proposals_mutex.synchronize do
+        next true if @objective_proposals.any? { |p| p.line == proposal.line }
+        next false if @objective_proposals.size >= Objectives::PROPOSALS_PER_TURN
+
+        @objective_proposals << proposal
+        true
+      end
+    end
+
+    def show_objective_proposals
+      proposals = @objective_proposals_mutex.synchronize { @objective_proposals.slice!(0..) }
+      proposals.each do |proposal|
+        id = "objectives-#{SecureRandom.hex(4)}"
+        show_card(source: Objectives::SOURCE, id: id, title: proposal.title, body: proposal.body,
+                  actions: [{ label: "Apply", command: proposal.action_line(id) },
+                            { label: "Dismiss", command: "/objectives --card #{id} dismiss" }])
+      end
+    rescue StandardError => e
+      Log.warn(:turn, "objectives_proposal_failed", error: e.class.name, msg: e.message)
+    end
+    private :show_objective_proposals
+
     # The strategy the working set is built under now, as LLMContextView
     # takes it: the running turn's, else the next turn's (#emit_working_set).
     # /working-set's ops act under it.
@@ -1018,11 +1080,14 @@ module Samagotchi
         next nil if Array(session.messages).any? { |m| m[:note_id] == note[:note_id] }
 
         message = ContextNote.message(**note)
+        entry = note[:objectives] && Objectives.entry(note[:objectives], before: Objectives.build(session.messages))
         replace_session_messages(session, Array(session.messages) + [message])
         announce({ type: :context_added, session_id: session.id, note_id: note[:note_id], source: note[:source],
                    label: ContextNote.label_of(message), from_session: note[:from_session],
                    from_cwd: note[:from_cwd], text: note[:text], context_source: note[:context_source],
-                   created_at: note[:created_at] }.compact)
+                   created_at: note[:created_at], objectives: entry }.compact)
+        announce_objectives(session) if entry
+        objectives_audit.note(session, note)
         message
       end
     end
@@ -1677,6 +1742,7 @@ module Samagotchi
         event[:verdict] = verdict if verdict
         event[:revises] = revises.to_h if revises
         emit_working_set(turn.on_event, turn.session, turn.session.messages)
+        announce_objectives(turn.session)
         turn.session.status = Session::STATUS_IDLE
         record_last_turn(turn.session, outcome, seconds, turn.origin, event, limit: exhausted ? turn.limit : nil)
         emit_event(turn.on_event, turn.tag(event))
@@ -2366,6 +2432,7 @@ module Samagotchi
       ensure
         release_turn(probe_cancel_before)
         show_context_cards_after_turn
+        show_objective_proposals
       end
     end
 
@@ -2469,6 +2536,7 @@ module Samagotchi
       # The candidate judge: its asks run beside the turn; on mode's
       # attaches reach the model at the next between-turn delivery.
       start_context_judge(turn)
+      audit_objectives_incoming(turn)
       apply_toolkit!(session, turn.on_event)
       refresh_participants!(session)
       # A Stop during the waits above: the turn ends here,
@@ -2740,14 +2808,18 @@ module Samagotchi
 
       # Fire :after_turn hook (an answer or a Stop; an Interrupt or a failure
       # ends the turn in #run_turn without it), with a read-only
-      # copy of the conversation the turn stored, event[:present] for
+      # copy of the conversation the turn stored, event[:answer] (the answer's
+      # text: the native loop's stored message still holds its thought),
+      # event[:present] for
       # a display version of the answer (AnswerDisplay) and event[:refs]
       # for refs on it (AnswerRefs).
       session = turn.session
+      audit_objectives_outgoing(turn, result) unless canceled || result.exhausted?
       display = AnswerDisplay.new(session.messages)
       refs = AnswerRefs.new(session.messages, cwd: session.working_directory)
       after_turn = { type: :after_turn, status: canceled ? "canceled" : "completed",
-                     messages: hook_messages(session.messages) }
+                     messages: hook_messages(session.messages),
+                     answer: (result.text unless canceled || result.exhausted?) }
       after_turn[:present] = display.presenter(after_turn)
       after_turn[:refs] = refs.adder(after_turn)
       @hooks.fire(:after_turn, after_turn)
@@ -2855,7 +2927,8 @@ module Samagotchi
     # The running turn's conversation as its loop builds it (both loops
     # register it on the kernel's llm_context_turn): the same array the loop
     # appends to, not a copy, so read it on the turn's thread (the pending
-    # input drain, at an iteration boundary: TurnCheckpoint). nil when no
+    # input drain, at an iteration boundary: TurnCheckpoint), or from another
+    # only as a dup, read only (/objectives). nil when no
     # turn runs (llm_context_turn is never cleared, and still holds the
     # last turn's then).
     # @return [Array<Hash>, nil]
@@ -2885,7 +2958,10 @@ module Samagotchi
       raise ArgumentError, "no current session" unless @session
 
       messages = replace_session_messages(@session, clone_messages(checkpoint))
-      announce_working_set unless turn_running?
+      unless turn_running?
+        announce_working_set
+        announce_objectives
+      end
       messages
     end
 
@@ -3296,6 +3372,36 @@ module Samagotchi
     end
     private :start_context_judge
 
+    # System 1 on the objectives, in audit (ObjectivesAudit): the owner's turns
+    # only, and for a message a person's: a reminder's or a delegate's prompt isn't one.
+    def audit_objectives_incoming(turn)
+      return unless turn.prompt.is_a?(String) && turn.origin.human? && OwnerPrompt.turn?(session: turn.session, author: turn.origin.author)
+
+      objectives_audit.incoming(turn.session, turn.prompt)
+    end
+    private :audit_objectives_incoming
+
+    def audit_objectives_outgoing(turn, result)
+      return unless OwnerPrompt.turn?(session: turn.session, author: turn.origin.author)
+
+      objectives_audit.outgoing(turn.session, result.text)
+    end
+    private :audit_objectives_outgoing
+
+    # With saving off nothing would come of an ask, so none is made.
+    def objectives_audit
+      @objectives_audit ||= ObjectivesAudit.new(
+        side: @side_judgments, state_dir: -> { session_state_dir },
+        client_for: lambda do |judgment, session|
+          next nil unless system_one_runs.on?
+
+          system_one_recording(SystemOne::Client.from_config(host_registry: @host_registry, mode: ObjectivesAudit::MODE, tag: :system_one),
+                               judgment, session)
+        end
+      )
+    end
+    private :objectives_audit
+
     # A late proposal no owner prompt mentions (Plugin::Host
     # #candidate_proposed: github-pr's init task runs beside the first
     # turn): judged on the owner's prompts so far, the running turn's too.
@@ -3446,6 +3552,7 @@ module Samagotchi
         cwd: -> { @session&.working_directory },
         messages: -> { plugin_messages },
         messages_partial: -> { turn_running? && @running_turn_messages.nil? },
+        turn_running: -> { turn_running? },
         notify: ->(text, level, label, fallback_for: nil) { hook_notify(text, level, label, fallback_for: fallback_for) },
         ask_user: ->(question) { hook_ask_user(question) },
         # An init task's is its own (a Ctrl-C ends a turn, not the task).

data/lib/samagotchi/engine_peers.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "objectives"
+
 module Samagotchi
   # The views of an Engine its peers get: the kernel's tools
   # (Engine#initialize sets @kernel.peers) and a delegate's approval relay
@@ -28,6 +30,15 @@ module Samagotchi
       # The peer's name when +name+ is a source a peer bundle declared
       # (PeerSources), for context_read's header.
       def peer_label(name) = engine.peer_sources&.label_for(name)
+
+      # The session's objectives now (the objectives tool), nil outside one.
+      def objectives
+        session = engine.session
+        session && Objectives.current(session.id, session.messages, state_dir: engine.peer_state_dir)
+      end
+
+      # A proposed change: its card shows at the turn's end (Engine#propose_objective).
+      def propose_objective(proposal) = engine.propose_objective(proposal)
     end
 
     # What the approval relay needs from the parent's Engine (Peers#relay):

data/lib/samagotchi/git_env.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Samagotchi
+  # The variables that tell a git which repo to act on. A process started by
+  # git (`rebase --exec`, `bisect run`, a hook) inherits them, and then its
+  # `git -C dir ...`, or a clone into a temp dir, reads or writes that repo
+  # instead of dir. chi's own git calls on a path chi chose spawn with UNSET;
+  # git then finds the repo from its cwd or -C. A model's and a user's commands
+  # (execute, tasks, !cmd) are theirs: they keep what chi was given.
+  module GitEnv
+    # `git rev-parse --local-env-vars` (git_env_spec checks it) less
+    # GIT_CONFIG_COUNT, which only adds settings and which git never sets for
+    # a child: like ~/.gitconfig it is the user's (a CI's clone credentials),
+    # and the suite's own (spec_helper). spec/e2e/support/env.js asks git for
+    # the same list.
+    VARS = %w[
+      GIT_ALTERNATE_OBJECT_DIRECTORIES GIT_COMMON_DIR GIT_CONFIG GIT_CONFIG_PARAMETERS GIT_DIR GIT_GRAFT_FILE
+      GIT_IMPLICIT_WORK_TREE GIT_INDEX_FILE GIT_NO_REPLACE_OBJECTS GIT_OBJECT_DIRECTORY GIT_PREFIX
+      GIT_REPLACE_REF_BASE GIT_SHALLOW_FILE GIT_WORK_TREE
+    ].freeze
+
+    # What a spawn takes as its env: Process.spawn unsets a key mapped to nil.
+    # Not GIT_CONFIG_PARAMETERS, GIT_CONFIG_COUNT's older form (`git -c ...` around
+    # chi): settings for this git, not a repo, like a url.insteadOf for a clone.
+    # A test run clears it (VARS); what wants no config at all says so (TextMerge).
+    UNSET = (VARS - ["GIT_CONFIG_PARAMETERS"]).to_h { |name| [name, nil] }.freeze
+
+    module_function
+
+    # For a test run, as spec_helper and the kit's adapters load: its specs'
+    # `git -C tmp init` must not reach the real repo. Clears them for this
+    # process and all it starts, also from the copy Bundler keeps of the
+    # environment it started in: Bundler.with_unbundled_env and
+    # InstalledGem.unbundled_env_changes would put them back in a child.
+    def scrub!
+      clear(ENV)
+      clear(::Bundler::ORIGINAL_ENV) if defined?(::Bundler::ORIGINAL_ENV)
+    end
+
+    # @param env [#delete] ENV or a Hash
+    def clear(env) = VARS.each { |name| env.delete(name) }
+  end
+end

data/lib/samagotchi/guardrails/context.rb

@@ -93,6 +93,8 @@ module Samagotchi
         return {} unless File.directory?(dir)
 
         paths = ["--show-toplevel", "--git-path", "hooks", "--git-common-dir"]
+        # In chi's own environment, on purpose: a tool's git inherits it, and a
+        # card or a rule must judge the repo that git acts on (GIT_DIR around chi too).
         out, status = Open3.capture2e("git", "-C", dir, "rev-parse", *paths, "--abbrev-ref", "HEAD")
         # A repo with no commits yet has no HEAD: only the paths answer.
         out, status = Open3.capture2e("git", "-C", dir, "rev-parse", *paths) unless status.success?

data/lib/samagotchi/guardrails/pair_boundary.rb

@@ -34,7 +34,8 @@ module Samagotchi
     #   - owner-voiced tools (OWNER_VOICED, and any delegate_* tool): what
     #     speaks or acts in the owner's name beyond this turn (a delegate, a
     #     reminder, a note to another session, a background task, a
-    #     forgotten output, the session's loaded tools); the tools that read
+    #     forgotten output, the session's loaded tools, a move on the owner's
+    #     objectives); the tools that read
     #     the owner's background tasks (OWNER_TASK_READERS); and memory_write:
     #     a memory reaches the owner's later sessions;
     #   - ask_user_question: there is no one on the participant's side to
@@ -51,7 +52,7 @@ module Samagotchi
       RULE = "pair-boundary"
       SOURCE = "core"
       OWNER_VOICED = %w[delegate register_reminder cancel_reminder send_note forget_outputs task_create task_stop
-                        find_tools].freeze
+                        find_tools objectives].freeze
       OWNER_VOICED_PREFIX = "delegate_"
       # The background task tools that read the owner's tasks (a pair turn
       # starts none: task_create is owner-voiced, and its execute is never

data/lib/samagotchi/guardrails/targets.rb

@@ -401,7 +401,10 @@ module Samagotchi
       # :unknown for one the text doesn't tell); [] for other tools.
       def git_dirs
         @git_dirs ||= if shell?
-                        # chi's own GIT_DIR is not the command's concern
+                        # The text's and the call's env: only. chi's own GIT_DIR and
+                        # GIT_WORK_TREE aren't counted here, though execute inherits
+                        # them and the command does act on that repo; GitInfo (the
+                        # repo root and common dir this is compared with) follows them.
                         shell_envs.each_with_index.flat_map do |(home, vars), i|
                           ShellGitDirs.for(@command, cwd: @cwd, home: home, env: i.zero? ? {} : @env, vars: vars)
                         end.uniq

data/lib/samagotchi/llm/chat_loop.rb

@@ -259,7 +259,7 @@ module Samagotchi
       # Claude model's cache breakpoint there (PromptCache) and drops it
       # for every other request.
       def system_message(entry, index)
-        text = entry[:content].to_s
+        text = Steer.wire_text(entry, entry[:content].to_s)
         split = index.zero? && @stable_length&.call(text)
         split ? { role: "system", content: text, cache_split: split } : { role: "system", content: text }
       end

data/lib/samagotchi/memory_bundle/asset_installer.rb

@@ -19,6 +19,8 @@ module Samagotchi
     # warnings, and #run returns what the record (Provenance#write) keeps.
     # A dev install (+dev+, `chi bundle install --dev`) links each file to
     # the source instead of copying it, and warns of no checksum mismatch.
+    # An edited file it replaces or removes is copied to the trash first,
+    # under its subfolder (Trash#copy_edit); a link never is.
     class AssetInstaller
       # What was installed: the paths Provenance#write records (each
       # empty / nil on a dry run).
@@ -33,7 +35,8 @@ module Samagotchi
       # @param existing [InstalledBundle, nil] the record before this install
       # @param results, warnings, conflicts the Installer's (results and
       #   warnings are added to)
-      def initialize(name:, source_dir:, manifest:, provenance:, existing:, results:, warnings:, conflicts:,
+      # @param trash [Trash] the Installer's
+      def initialize(name:, source_dir:, manifest:, provenance:, existing:, results:, warnings:, conflicts:, trash:,
                      force: false, strict: true, upgrade: false, dry_run: false, dev: false)
         @name = name
         @bundle_dir = source_dir
@@ -43,6 +46,7 @@ module Samagotchi
         @results = results
         @warnings = warnings
         @conflicts = conflicts
+        @trash = trash
         @force = force
         @strict = strict
         @upgrade = upgrade
@@ -112,6 +116,7 @@ module Samagotchi
 
         FileUtils.mkdir_p(@provenance.hooks_dir)
         unchanged = File.exist?(dest) && FileUtils.identical?(src, dest)
+        @trash.copy_edit(dest, as: "hooks/#{basename}", recorded: prev_sha, incoming: src)
         place(src, dest)
         @results[basename] = if unchanged
                                { status: "skipped", reason: "already up to date" }
@@ -135,6 +140,7 @@ module Samagotchi
           else
             FileUtils.mkdir_p(@provenance.hooks_dir)
             dest = File.join(@provenance.hooks_dir, basename)
+            @trash.copy_edit(dest, as: "hooks/#{basename}", recorded: @existing&.hooks&.dig(basename)&.sha256, incoming: src)
             place(src, dest)
             @results[basename] = { status: "installed" }
             @hook_files[basename] = dest
@@ -152,6 +158,7 @@ module Samagotchi
           if File.exist?(old_dest) && !@force && !File.symlink?(old_dest)
             @warnings << "Bundle no longer includes hook #{old_key_str} but local file exists — removing"
           end
+          @trash.copy_edit(old_dest, as: "hooks/#{old_key_str}", recorded: @existing.hooks[old_key_str]&.sha256)
           FileUtils.rm_f(old_dest)
         end
       end
@@ -190,6 +197,7 @@ module Samagotchi
           dest = File.join(target, File.basename(src))
           File.file?(dest) && FileUtils.identical?(src, dest)
         end
+        @trash.copy_edits(target, "guardrails", @existing&.guardrails, incoming_rules.to_h { |src| [File.basename(src), src] })
         FileUtils.rm_rf(target)
         return {} if incoming_rules.empty?
 
@@ -210,7 +218,10 @@ module Samagotchi
       def install_plugin
         plugin = @manifest&.plugin
         unless plugin
-          FileUtils.rm_rf(@provenance.plugin_dir) unless @dry_run
+          unless @dry_run
+            @trash.copy_edits(@provenance.plugin_dir, "plugin", @existing&.plugin_shas)
+            FileUtils.rm_rf(@provenance.plugin_dir)
+          end
           return nil
         end
 
@@ -228,6 +239,7 @@ module Samagotchi
 
         dest = File.join(@provenance.plugin_dir, plugin[:file])
         unchanged = File.file?(dest) && FileUtils.identical?(src, dest)
+        @trash.copy_edits(@provenance.plugin_dir, "plugin", @existing&.plugin_shas, { plugin[:file] => src })
         FileUtils.rm_rf(@provenance.plugin_dir)
         FileUtils.mkdir_p(@provenance.plugin_dir)
         place(src, dest)
@@ -265,6 +277,8 @@ module Samagotchi
           dest = File.join(@provenance.scripts_dir, file)
           File.file?(dest) && FileUtils.identical?(File.join(@bundle_dir, "scripts", file), dest)
         end
+        @trash.copy_edits(@provenance.scripts_dir, "scripts", @existing&.scripts,
+                          scripts.keys.to_h { |file| [file, File.join(@bundle_dir, "scripts", file)] })
         FileUtils.rm_rf(@provenance.scripts_dir)
         return {} if scripts.empty?
 

data/lib/samagotchi/memory_bundle/file_standing.rb

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+
+require "digest"
+require "time"
+
+module Samagotchi
+  module MemoryBundle
+    # What chi says of an edited bundle file, everywhere it reports one: the one
+    # owner of these words (chi update's row and --json, chi bundle list and
+    # status, chi self, chi bootstrap, SystemBundle.ensure!'s echo, the Installer's
+    # summary, the phone's push).
+    #
+    # A file is merged (it took the update) or behind: marked conflict on its
+    # record, with bytes other than the bundle's text it speaks of. A marked file
+    # brought level by hand isn't behind, and a missing one is a missing file.
+    module FileStanding
+      # Why a merge of a mark from an older chi didn't go ahead (Merger.merge_outcome).
+      LEGACY_BASE = "an older chi may have taken your text as the base, and the merge would remove lines from your file"
+      # A real conflict on such a mark: its base can't say what the bundle changed.
+      LEGACY_CONFLICT = "it conflicts with the bundle's text, and an older chi's base can't say what it missed"
+      # A marked file Remerge leaves for the next upgrade or restore.
+      WAITS_FOR_UPGRADE = "it matches its old base, and the bundle's next version replaces it"
+      FILE_MISSING = "the file is missing, and the bundle's next version puts it back"
+      UNSURE = "an older chi marked it, and the next upgrade checks it"
+      NOT_SHIPPED = "not in the bundle now, nothing to merge"
+
+      # What --force does to a file that stays behind, and to an edited one being removed.
+      FORCE_TAKES = "--force takes the bundle's version, your file copied to the trash first"
+      FORCE_MOVES = "--force moves it to the trash"
+      # Why a file an agent step was given stays behind (BundleCommand#settle_conflicts).
+      STILL_BEHIND = { untouched: "Nothing changed in %s: still behind.",
+                       markers: "%s still holds conflict markers: still behind.",
+                       incoming_gone: "The bundle's copy of %s is gone: still behind." }.freeze
+      # A chi update row's short word for the trash; the path is long for a table.
+      IN_THE_TRASH = "old copies: chi bundle trash"
+      # How many missed headings a line names.
+      SHOWN_MISSED = 3
+
+      # One file that stays behind. why: the clause saying why no merge was tried
+      # (.no_merge, or a plain reason), nil for a real conflict. missed: the
+      # headings of the sections the bundle changed. places: the changes under no
+      # heading. unsure: an older mark that no retry has looked at, with nothing to
+      # compare the file to, so chi can't say it is behind.
+      # What a record gives is read as it is shaped: anything else is nothing known.
+      Behind = Data.define(:file, :version, :why, :missed, :places, :unsure) do
+        def initialize(file:, version: nil, why: nil, missed: [], places: 0, unsure: false)
+          super(file: file, version: version, why: why.is_a?(String) ? FileStanding.text(why) : nil,
+                missed: (missed.is_a?(Array) ? missed : []).grep(String).map { |heading| FileStanding.text(heading) },
+                places: places.is_a?(Integer) && places.positive? ? places : 0, unsure: unsure)
+        end
+
+        # "stays behind 0.8.0: missed ## Objectives"
+        def state(dry_run: false)
+          return "may be behind#{" #{version}" if version}: #{UNSURE}" if unsure
+
+          head = "#{dry_run ? "would stay" : "stays"} behind#{" #{version}" if version}"
+          rest = [why, FileStanding.missed_words(missed, places)].compact.join("; ")
+          rest.empty? ? head : "#{head}: #{rest}"
+        end
+
+        # "x.md stays behind 0.8.0: missed ## Objectives"
+        def line(dry_run: false) = "#{FileStanding.text(file)} #{state(dry_run: dry_run)}"
+      end
+
+      # A merge no report has shown yet, as the file's record keeps it
+      # (Provenance#note_merged). Every merge leaves one: a worker's reaches nothing
+      # but its log, an automatic update's rows no person. It shows in chi bundle
+      # status while it exists. A report someone reads ends it: chi update's row, for
+      # what it printed (this run's merges too), and chi bundle upgrade's output. No
+      # start says it: most sessions never read that file.
+      MergeNote = Data.define(:file, :version, :at, :trash) do
+        # "merged 0.8.0 into your x.md on 2026-11-05 14:03"
+        def line
+          "#{FileStanding.merged_line([file], version)}#{" on #{FileStanding.local_time(at)}" if at}"
+        end
+      end
+
+      module_function
+
+      # +value+ as UTF-8, whatever it was tagged, what isn't valid replaced: a file
+      # name under LC_ALL=C and a heading must join in one line.
+      def text(value) = value.to_s.dup.force_encoding(Encoding::UTF_8).scrub
+
+      # "merged 0.8.0 into your x.md, y.md"
+      def merged_line(files, version, dry_run: false)
+        "#{dry_run ? "would merge" : "merged"}#{" #{version}" if version} into your #{files.map { |file| text(file) }.join(", ")}"
+      end
+
+      # The clause for a merge that couldn't answer: +why+ is TextMerge's reason
+      # or LEGACY_BASE, where chi can't even say the file holds edits.
+      def no_merge(why)
+        why == LEGACY_BASE ? "chi can't tell whether it holds edits of yours (#{why})" : "no merge possible (#{why})"
+      end
+
+      def still_behind(reason, file) = format(STILL_BEHIND.fetch(reason), text(file))
+
+      def left_as_it_is(message) = "left as it is (#{message})"
+
+      # "missed ## A, ## B, ## C and 2 more", "missed 2 places"; nil for nothing known.
+      def missed_words(headings, places)
+        return places.positive? ? "missed #{counted(places, "place")}" : nil if headings.empty?
+
+        more = [headings.size - SHOWN_MISSED, 0].max + places
+        words = "missed #{headings.first(SHOWN_MISSED).join(", ")}"
+        more.positive? ? "#{words} and #{more} more" : words
+      end
+
+      # "1 file behind"; "2 files may be behind" if chi isn't sure of one of them.
+      def behind_count(count, unsure: false) = "#{counted(count, "file")} #{"may be " if unsure}behind"
+
+      # "1 file stays behind", "2 files stay behind"; "1 file may be behind"
+      def stay_behind(count, unsure: false)
+        return behind_count(count, unsure: true) if unsure
+
+        "#{counted(count, "file")} #{count == 1 ? "stays" : "stay"} behind"
+      end
+
+      # The sentence of a push, merged and behind as counts: "" for neither.
+      def counts_sentence(merged:, behind:)
+        parts = []
+        parts << "Merged the update into #{counted(merged, "file")} you edited." if merged.to_i.positive?
+        parts << "#{stay_behind(behind)}." if behind.to_i.positive?
+        parts.join(" ")
+      end
+
+      # A report's clauses for one bundle: what merged, what stays behind with
+      # how to see it, what an earlier merge did.
+      # @param merged [Array<String>] files
+      # @param behind [Array<Behind>]
+      # @param earlier [Array<MergeNote>]
+      # @return [Array<String>]
+      def clauses(bundle, version, merged: [], behind: [], earlier: [], dry_run: false)
+        behind_lines = behind.map { |file| file.line(dry_run: dry_run) }
+        behind_lines[0] += " (#{diff_hint(bundle, behind.first.file)})" unless behind.empty?
+        [*(merged.empty? ? nil : merged_line(merged, version, dry_run: dry_run)), *behind_lines, *earlier.map(&:line)]
+      end
+
+      def diff_hint(bundle, file) = "chi bundle diff #{text(bundle)} #{text(file)}"
+
+      def local_time(stamp)
+        Time.iso8601(stamp.to_s).localtime.strftime("%Y-%m-%d %H:%M")
+      rescue ArgumentError
+        stamp.to_s
+      end
+
+      # The one answer to whether a file stays behind, for a report and a retry
+      # alike: marked, there, and not level with the bundle's text the mark speaks
+      # of. A missing file is a missing file (a project-scope record doesn't even
+      # say which project it means).
+      # @param incoming_sha [String, nil] that text's digest, for a mark with none
+      def behind?(path, entry, incoming_sha: entry[:incoming_sha])
+        entry[:conflict] == true && File.exist?(path) && differs?(path, incoming_sha)
+      end
+
+      # The file's bytes aren't what the mark says the bundle ships. One it can't
+      # read isn't known to be level. No digest (an older mark): it isn't known
+      # either, and a retry would have settled it.
+      def differs?(path, incoming_sha)
+        incoming_sha.nil? || Digest::SHA256.file(path).hexdigest != incoming_sha
+      rescue SystemCallError
+        true
+      end
+
+      def counted(count, noun) = "#{count} #{noun}#{"s" unless count == 1}"
+    end
+  end
+end