samagotchi 0.101.0 → 0.103.0

data/lib/samagotchi/web/session_access_routes.rb

@@ -0,0 +1,343 @@
+# frozen_string_literal: true
+
+require_relative "../session"
+require_relative "../session_access/local"
+require_relative "../session_inbox"
+require_relative "../reply_wait"
+require_relative "../pending_question"
+require_relative "../context_sources"
+require_relative "../context_command"
+require_relative "../send_command"
+require_relative "../launch_mode"
+require_relative "../model_profile"
+
+module Samagotchi
+  module Web
+    # The routes chi's session commands need from another machine's chi web
+    # (chi --remote NAME …, SessionAccess::Remote), one per
+    # SessionAccess::Local operation that the page's own routes don't cover:
+    # a prefix resolved, the CLI's list rows, a wait's pre-send state and
+    # the wait itself, a note, a push into a context source. Each calls
+    # SessionAccess::Local, so a Remote maps 1:1 onto them. Included in
+    # App: its ROUTES name the handlers, and its helpers (json_response,
+    # parse_json, …) answer. See docs/architecture.md (chi web's routes for
+    # the session commands).
+    module SessionAccessRoutes
+      # A wait route answers within this many seconds (status timeout); the
+      # client asks again until its own --timeout.
+      WAIT_MAX_SECONDS = 30.0
+      # GET /api/info's feature: this chi web has these routes (a remote
+      # client checks it before its first session command).
+      FEATURE = "session_commands"
+      # GET /api/info's feature: this chi web has the routes a remote
+      # attached TUI needs (wake, worker; chi --remote NAME --attach).
+      ATTACH_FEATURE = "remote_attach"
+      # The longest POST …/wake waits for a worker's Bridge
+      # (TerminalUI::AttachLauncher::BRIDGE_WAIT, an attach's here).
+      WAKE_MAX_WAIT = 10.0
+
+      private
+
+      # This server's sessions, as a session command reaches them here.
+      def session_access = @session_access ||= SessionAccess::Local.new(state_dir: @state_dir)
+
+      # A refusal an exception carries: its stable +code+, +detail+ (what
+      # the page shows; the message by default), and for a remote client
+      # the exception's own message and the fields its class is built from
+      # (session_id, reason, …), so it can raise the same class.
+      def refusal_response(status, code, error, detail: error.message, **fields)
+        json_response(status, { error: code, detail: detail, message: error.message, **fields }.compact)
+      end
+
+      # The body as a Hash ({} when there is none), or nil when it isn't one.
+      def body_hash(req)
+        raw = request_body(req)
+        return {} if raw.to_s.strip.empty?
+
+        parsed = parse_json(raw)
+        parsed.is_a?(Hash) ? parsed : nil
+      end
+
+      def truthy_param?(value) = %w[1 true yes].include?(value.to_s.strip.downcase)
+
+      # GET /api/sessions/resolve?id=PREFIX: the full id of the session an id
+      # or a unique prefix names (SessionAccess::Local#resolve). 200 {id};
+      # 404 not_found; 400 ambiguous_id with ids (the sessions it names).
+      def handle_resolve(req)
+        given = req.params["id"].to_s
+        return error_response(404, "not_found", "no session #{given[0, 80]}") unless Session.valid_id?(given)
+
+        json_response(200, { id: session_access.resolve(given) })
+      rescue Session::AmbiguousId => e
+        refusal_response(400, "ambiguous_id", e, ids: e.ids)
+      rescue ArgumentError
+        error_response(404, "not_found", "no session #{given[0, 80]}")
+      end
+
+      # GET /api/sessions/:id?brief=1: the session as a session command
+      # reads it (SessionAccess::Local#show): the file's status (not the
+      # displayed one), its names, folder, model and parent_answers, its
+      # owner's kind, and the file's pending question, never its messages.
+      # A chi web from before ?brief answers the whole read, which has the
+      # session part too.
+      def handle_brief_read(id)
+        session = @session_class.load(id, state_dir: default_state_dir)
+        owner = session_access.owner(id)
+        json_response(200, {
+          brief: true,
+          session: { id: session.id, status: session.status, title: session.title,
+                     display_title: session.display_title, project_root: session.project_root,
+                     working_directory: session.working_directory, model_name: session.model_name,
+                     model_typed: session.model_typed, parent_answers: session.parent_answers,
+                     owner: owner&.kind },
+          pending_question: session.pending_question&.to_file
+        })
+      end
+
+      # GET /api/sessions/summaries: the rows chi sessions list prints
+      # (SessionManager.session_summaries: status, live, busy, owner, recap,
+      # ctx_pct, waiting, …), filtered as its flags filter. Params: dir (a
+      # folder: its project's sessions; none: every project's), cwd (in that
+      # folder or below), live=1, archived=1, tests=0 (leave test runs out),
+      # sort, order, limit. An array, newest first by default.
+      def handle_summaries(req)
+        dir, error = scope_dir(req.params["dir"])
+        return error if error
+
+        cwd = req.params["cwd"].to_s
+        cwd = nil if cwd.strip.empty?
+        return error_response(400, "invalid_cwd", "cwd is an absolute path: #{cwd[0, 200]}") if cwd && !cwd.start_with?("/")
+
+        rows = session_access.summaries(
+          live: truthy_param?(req.params["live"]), cwd: cwd, limit: sanitize_limit(req.params["limit"]),
+          include_tests: !%w[0 false no].include?(req.params["tests"].to_s.strip.downcase),
+          project_root: dir && ProjectScope.root_for(dir), include_archived: truthy_param?(req.params["archived"]),
+          sort: sanitize_sort(req.params["sort"]), order: sanitize_order(req.params["order"])
+        )
+        json_response(200, rows)
+      end
+
+      # POST /api/sessions/:id/wait/prepare: what chi send --wait and chi
+      # answer read before anything is sent (SessionAccess::Local#
+      # prepare_wait). Body (all optional): question_id (the question the
+      # baseline counts as reported; absent: the one pending now, null:
+      # none), turn (--turn: known_turn says whether it can be waited for),
+      # created (a session just created: no reply, no question), busy (chi
+      # send --wait with a message: refuse a running turn, 409 busy or
+      # waiting in SendCommand::Busy's words, with its fields: question,
+      # parent_strategy; queue: true, --queue, refuses only a waiting
+      # question). 200 {session_id, cursor, baseline:
+      # {messages, question_id, last_turn}, own_turn, known_turn, running,
+      # live, settled, last_turn_id}.
+      def handle_wait_prepare(req, id)
+        body = body_hash(req) or return error_response(400, "invalid_json", "invalid JSON body")
+        turn = body["turn"]
+        return error_response(400, "invalid_turn", "turn is a turn id") unless turn.nil? || turn.is_a?(String)
+
+        session = session_access.show(id)
+        if body["busy"] == true
+          owner = session_access.owner(id) if session.status == Session::STATUS_RUNNING
+          busy = SendCommand::Busy.for(session, owner: owner, queue: body["queue"] == true)
+          return json_response(409, busy_json(busy)) if busy
+        end
+
+        question_id = body.key?("question_id") ? body["question_id"]&.to_s : :pending
+        start = session_access.prepare_wait(id, session: session, question_id: question_id, turn: turn,
+                                                created: body["created"] == true)
+        json_response(200, wait_start_json(id, start))
+      end
+
+      # A Busy refusal: its words here, and its fields, which a chi --remote
+      # client words with its own commands (SessionAccess::Remote#busy).
+      def busy_json(busy)
+        { error: busy.error, detail: busy.message, message: busy.message, session_id: busy.session_id,
+          question: busy.question&.to_file, parent_strategy: (strategy_json(busy.strategy) if busy.strategy) }.compact
+      end
+
+      def strategy_json(strategy) = { name: strategy.name, allowed: strategy.allowed, origin: strategy.origin.to_s }
+
+      def wait_start_json(id, start)
+        { session_id: id, cursor: start.cursor, baseline: start.baseline.to_h, own_turn: start.own_turn,
+          known_turn: start.known_turn, running: start.running, live: start.live, settled: start.settled,
+          last_turn_id: start.last_turn_id }
+      end
+
+      # POST /api/sessions/:id/wait: ReplyWait for at most WAIT_MAX_SECONDS
+      # (SessionAccess::Local#wait_reply). Body: cursor, baseline
+      # ({messages, question_id, last_turn}, as the prepare route gave it),
+      # turn, queued, ended_before, owner_grace (seconds, null: wait for
+      # whatever wakes a worker), timeout (seconds, capped). 200: the
+      # ReplyWait::Result's fields (status: done, waiting_for_answer,
+      # no_reply, error, stopped, timeout or worker_gone; text, file,
+      # question, outcome, …; never the Session) and parent_strategy, what
+      # a parent may pick on the session's questions here
+      # (ParentReport.strategy_for). A timeout status: ask again. 503
+      # server_stopping when chi web stops mid-wait.
+      def handle_wait(req, id)
+        body = body_hash(req) or return error_response(400, "invalid_json", "invalid JSON body")
+        options, error = wait_options(body)
+        return error if error
+
+        session_access.show(id)
+        result = session_access.wait_reply(id, **options, poll_interval: @wait_poll_interval,
+                                               cancelled: -> { !@server_running.call })
+        return error_response(503, "server_stopping", "chi web is stopping; wait again") if result.status == :canceled
+
+        json_response(200, wait_result_json(result, session_access.parent_strategy(id)))
+      end
+
+      # The wait's ReplyWait arguments from the body: [options, nil] or
+      # [nil, a 400 response].
+      def wait_options(body)
+        strings = %w[cursor turn].to_h { |key| [key, body[key]] }
+        if strings.any? { |_, value| !value.nil? && !value.is_a?(String) }
+          return [nil, error_response(400, "invalid_wait", "cursor and turn are strings")]
+        end
+
+        baseline, error = wait_baseline(body["baseline"])
+        return [nil, error] if error
+
+        numbers = %w[timeout owner_grace].to_h { |key| [key, body[key]] }
+        if numbers.any? { |_, value| !value.nil? && !(value.is_a?(Numeric) && value.positive?) }
+          return [nil, error_response(400, "invalid_wait", "timeout and owner_grace are positive seconds")]
+        end
+
+        timeout = [numbers["timeout"] || WAIT_MAX_SECONDS, WAIT_MAX_SECONDS].min
+        [{ cursor: strings["cursor"], turn: strings["turn"], baseline: baseline, timeout: timeout,
+           owner_grace: numbers["owner_grace"], queued: body["queued"] == true, ended_before: body["ended_before"] == true }, nil]
+      end
+
+      def wait_baseline(raw)
+        return [nil, nil] if raw.nil?
+
+        fields = { "messages" => Integer, "question_id" => String, "last_turn" => String }
+        unless raw.is_a?(Hash) && raw.all? { |key, value| fields.key?(key) && (value.nil? || value.is_a?(fields[key])) }
+          return [nil, error_response(400, "invalid_wait", "baseline is {messages, question_id, last_turn}")]
+        end
+
+        [ReplyWait::Baseline.new(**raw.transform_keys(&:to_sym)), nil]
+      end
+
+      RESULT_FIELDS = %i[text file outcome limit error_kind retryable cancel_reason stopped_by kept_steps turn_id origin].freeze
+
+      def wait_result_json(result, strategy)
+        json = { status: result.status.to_s }
+        RESULT_FIELDS.each { |key| json[key] = result[key] }
+        json[:text] = json[:text]&.dup&.force_encoding(Encoding::UTF_8)&.scrub
+        json[:question] = result.question&.to_file
+        json[:parent_strategy] = strategy_json(strategy)
+        json
+      end
+
+      # POST /api/sessions/:id/wake {wait}: the session's worker for a remote
+      # attach (SessionAccess::Local#wake): the live one, else resumed and
+      # waited for up to +wait+ seconds (WAKE_MAX_WAIT, also the most). 200
+      # {session_id, woke, worker: {epoch, started_at, version, features},
+      # model_name, default_model (this machine's config, for the TUI's
+      # status row), parent_strategy, installed (the newest chi here)}; 409
+      # owned_by_tui (a chi REPL has it), 409 scratch (a leftover scratch
+      # session, as chi --attach here says); 504 worker_timeout (its Bridge
+      # didn't come in time); 404 not_found.
+      def handle_wake(req, id)
+        body = body_hash(req) or return error_response(400, "invalid_json", "invalid JSON body")
+        wait = body.fetch("wait", WAKE_MAX_WAIT)
+        return error_response(400, "invalid_wait", "wait is positive seconds") unless wait.is_a?(Numeric) && wait.positive?
+
+        woken = session_access.wake(id, wait: [wait, WAKE_MAX_WAIT].min)
+        unless woken.sidecar
+          late = format(LaunchMode::BRIDGE_LATE, id)
+          return json_response(504, { error: "worker_timeout", detail: late, message: late, session_id: id })
+        end
+
+        json_response(200, { session_id: id, woke: woken.woke, worker: worker_json(woken.sidecar),
+                             model_name: session_access.show(id).model_name,
+                             default_model: ModelProfile.default_model_name,
+                             parent_strategy: strategy_json(session_access.parent_strategy(id)),
+                             installed: @hub&.installed })
+      rescue SessionManager::OwnedByTUI => e
+        owned_by_tui(e)
+      rescue SessionAccess::Refused => e
+        refusal_response(409, e.code, e, session_id: id)
+      end
+
+      # GET /api/sessions/:id/worker: the session's worker now, never
+      # started (SessionAccess::Local#worker): a remote attach's
+      # rediscovery and its features after a restart. 200 {session_id,
+      # live, stopped, owner: worker|tui|null, worker: {epoch, started_at,
+      # version, features}|null, parent_strategy}; 404 not_found.
+      def handle_worker(_req, id)
+        state = session_access.worker(id)
+        json_response(200, { session_id: id, live: state.live?, stopped: state.stopped, owner: state.owner&.kind,
+                             worker: state.sidecar && worker_json(state.sidecar),
+                             parent_strategy: strategy_json(session_access.parent_strategy(id)) })
+      end
+
+      # A live worker as a remote client knows it: its epoch is its
+      # identity (the one in its event ids).
+      def worker_json(sidecar)
+        { epoch: sidecar.epoch, started_at: sidecar.started_at, version: sidecar.version, features: sidecar.features }
+      end
+
+      # POST /api/sessions/:id/notes {text, source}: a context note for the
+      # session (NoteDelivery, as chi note; source: where it came from,
+      # "cli" by default, never "broadcast"). 200 {status: "queued" (a
+      # worker adds it) or "waits" (the next start does), session_id,
+      # queued}; 409 owned_by_tui (status refused: a chi REPL has it); 400
+      # note_rejected (empty, or over 16 KiB).
+      def handle_notes(req, id)
+        body = body_hash(req) or return error_response(400, "invalid_json", "invalid JSON body")
+        text = body["text"]
+        source = body.fetch("source", "cli")
+        return error_response(400, "missing_fields", "text is required") unless text.is_a?(String)
+        return error_response(400, "invalid_source", "source is a word") unless source.is_a?(String) && !source.strip.empty?
+        return error_response(400, "invalid_source", "source broadcast is chi broadcast's own") if source.strip == "broadcast"
+
+        session_access.show(id)
+        result = session_access.note(id, text: text, source: source.strip)
+        if result.status == :refused
+          error = SessionManager::OwnedByTUI.new(id)
+          return refusal_response(409, "owned_by_tui", error, session_id: id, status: "refused", queued: 0)
+        end
+
+        json_response(200, { status: result.status.to_s, session_id: id, queued: result.queued })
+      rescue SessionInbox::NoteRejected => e
+        error_response(400, "note_rejected", e.message)
+      end
+
+      # POST /api/sessions/:id/context/:name/push {text, summary, wake,
+      # hint}: new text for the session's --push source (chi context push;
+      # the fields as a source's JSON output gives them, checked the same
+      # way). 200 {status: "pushed", name, before, revision, changed}; 404
+      # not_found (no such source); 409 not_push (a command source); 400
+      # invalid_text.
+      def handle_context_push(req, id, name)
+        body = body_hash(req) or return error_response(400, "invalid_json", "invalid JSON body")
+        return error_response(400, "missing_fields", "text is required") unless body["text"].is_a?(String)
+
+        fetched = begin
+          ContextSources.parse_output(JSON.generate(body.slice("text", "summary", "wake", "hint")))
+        rescue ContextSources::Invalid => e
+          return error_response(400, "invalid_text", e.message)
+        end
+        pushed = session_access.context_push(context_target(id), name, fetched)
+        case pushed.status
+        when :missing then error_response(404, "not_found", "no source #{name[0, 40]}")
+        when :not_push then error_response(409, "not_push", SessionAccess::ContextPush.not_push_message(name))
+        else json_response(200, { status: "pushed", name: name, before: pushed.before, revision: pushed.revision,
+                                  changed: pushed.before != pushed.revision })
+        end
+      rescue ContextSources::Invalid
+        error_response(404, "not_found", "no source #{name[0, 40]}")
+      end
+
+      # The session as chi context's Target (SessionAccess::Local's context
+      # calls take one).
+      # @raise [ArgumentError] no such session
+      def context_target(id)
+        session = session_access.show(id)
+        ContextCommand::Target.new(session_id: id, project_root: session.project_root, cwd: session.working_directory,
+                                   label: id[0, 8])
+      end
+    end
+  end
+end

data/lib/samagotchi/worker.rb

@@ -259,7 +259,7 @@ module Samagotchi
                                           })
       # A recap written while a continue offer waits says the turn stopped
       # unfinished (before the idle jobs start).
-      @engine.recap&.awaiting_continue = -> { @turn_flow.awaiting_continue? }
+      @engine.recap_awaiting_continue = -> { @turn_flow.awaiting_continue? }
       # The seq of the last turn's end event: a command queued before it was
       # queued while that turn ran.
       @turn_end_seq = 0
@@ -943,14 +943,17 @@ module Samagotchi
     # finishes) comes after its command_queued. The cards it shows go out at
     # once (btw's "thinking…" card), after its command_queued, which the
     # UIs draw its line at (Engine#running_anytime). Its handler reads
-    # copies (ctx.messages) and shows things through ctx only. One saves:
-    # /title, a field no turn writes, through Session#save, which takes the
-    # session's lock and writes a running turn's checkpoint (as
-    # WorkerSignals' save off the turn thread does), so the turn's own saves
-    # keep it.
+    # copies (ctx.messages) and shows things through ctx only. One that
+    # changed the session (/title, /recap off: fields no turn writes) is
+    # saved here, as a queued one is (#run_command), through Session#save,
+    # which takes the session's lock and writes a running turn's checkpoint
+    # (as WorkerSignals' save off the turn thread does), so the turn's own
+    # saves keep it.
     def start_anytime_command(command)
       @engine.spawn_anytime do
         result = command_result(command) { @engine.running_anytime { @commands.run(command.line, confirm: confirm?(command)) } }
+        # Saved before its command_ran: a client that reads the file on the reply finds it.
+        save_or_log(:command) { save_session } unless Array(result.changed).empty?
         announce_command(command, status: result.status.to_s, output: result.output, changed: Array(result.changed),
                                   anytime: true, confirm: result.confirm)
       rescue StandardError => e

data/lib/samagotchi/worker_sidecar.rb

@@ -10,10 +10,14 @@ module Samagotchi
   # Bridge (port, bind), when it started (a new worker behind the same
   # "worker" owner), the chi it runs (chi update, the web's stale-worker
   # badge), the input-file format it reads (SessionInbox::INPUT_FORMAT) and
-  # what else it can do (Bridge::FEATURES). The Bridge writes it on start
+  # what else it can do (Bridge::FEATURES), and its Bridge's epoch (the
+  # one worker identity: the epoch in every event id, so a remote client
+  # tells a restarted worker apart; nil from a worker before it). The
+  # Bridge writes it on start
   # and removes it on stop; one a dead worker left stays until a client's
   # probe finds its port closed (.live with unlink: true).
-  class WorkerSidecar < Data.define(:port, :bind, :session_id, :started_at, :version, :input_format, :features)
+  class WorkerSidecar < Data.define(:port, :bind, :session_id, :started_at, :version, :input_format, :features,
+                                    :epoch)
     FILE = "bridge.json"
     # Seconds a liveness probe waits for the port to take a connect.
     PROBE_TIMEOUT = 0.2
@@ -29,7 +33,7 @@ module Samagotchi
       port = data["port"]
       new(port: port.respond_to?(:to_i) ? port.to_i : 0, bind: data["bind"], session_id: data["session_id"],
           started_at: data["started_at"], version: data["version"], input_format: data["input_format"],
-          features: Array(data["features"]).map(&:to_s))
+          features: Array(data["features"]).map(&:to_s), epoch: data["epoch"]&.to_s)
     rescue JSON::ParserError, SystemCallError
       nil
     end
@@ -63,13 +67,16 @@ module Samagotchi
     # @return [Integer, nil] .live's port
     def self.live_port(session_dir, unlink:, host: "127.0.0.1") = live(session_dir, unlink: unlink, host: host)&.port
 
-    def initialize(port:, bind: nil, session_id: nil, started_at: nil, version: nil, input_format: nil, features: []) = super
+    def initialize(port:, bind: nil, session_id: nil, started_at: nil, version: nil, input_format: nil, features: [],
+                   epoch: nil) = super
 
-    # Written whole or not at all; input_format only when it names one.
+    # Written whole or not at all; input_format and epoch only when they
+    # name one.
     def write(session_dir)
       FileUtils.mkdir_p(session_dir)
       record = to_h.transform_keys(&:to_s)
       record.delete("input_format") if input_format.nil?
+      record.delete("epoch") if epoch.nil?
       AtomicFile.write(self.class.path(session_dir), "#{JSON.pretty_generate(record)}\n")
     end
   end

data/lib/samagotchi/working_set.rb

@@ -39,24 +39,53 @@ module Samagotchi
     LIVE = "live"
     STALE = "stale"
     FORGOTTEN = "forgotten"
+    # Forgotten, every output of it by the user's drop (WorkingSetSteer).
+    DROPPED = "dropped"
 
     # One thing the model touched: +kind+ file|memory|url; +key+ a file's
     # absolute path (FileRef), a memory's name, a URL (whitespace
-    # collapsed); +state+ live|stale|forgotten; +tokens+ its content
+    # collapsed); +state+ live|stale|forgotten|dropped; +tokens+ its content
     # outputs as sent; +ops+ read|edit for a file, read|write for a memory,
     # read for a URL, in first-seen order; +count+ the runs that touched
-    # it; +first_id+ the first one's chi id (ToolIds).
-    Item = Data.define(:kind, :key, :state, :tokens, :ops, :count, :first_id)
+    # it; +first_id+ the first one's chi id (ToolIds); +pinned+ whether
+    # the user pinned it (WorkingSetPin: the model's forget_outputs refuses
+    # its outputs), whatever the strategy; +has_drop+ whether any of its
+    # content outputs holds the user's applied drop (an undrop has
+    # something to take back: a forgotten item too, its other outputs
+    # stubbed by the model's layers).
+    Item = Data.define(:kind, :key, :state, :tokens, :ops, :count, :first_id, :pinned, :has_drop)
+
+    # An item the user added (/working-set add) that the next turn's note
+    # asks the model to read: its identity (+kind+, +key+, as an Item's)
+    # and how the note names it (+label+: a file relative to the session's
+    # folder, "memory NAME", a URL).
+    Add = Data.define(:kind, :key, :label)
 
     # A projection and the conversation's size (entries) it was built
     # from: the web keeps the newer of an event's and a GET's by it.
-    Snapshot = Data.define(:items, :at) do
-      def empty? = items.empty?
+    # +adds+: the pending note's adds (#pending_adds), not items yet.
+    Snapshot = Data.define(:items, :at, :adds) do
+      def initialize(items:, at:, adds: [])
+        super
+      end
 
-      # The JSON the event and the route carry: {items: [...], at:}.
-      def to_h = { items: items.map(&:to_h), at: at }
+      def empty? = items.empty? && adds.empty?
+
+      # The JSON the event and the route carry: {items: [...], at:}, and
+      # adds: [{kind, key, label}] while any is pending.
+      def to_h
+        hash = { items: items.map(&:to_h), at: at }
+        hash[:adds] = adds.map(&:to_h) unless adds.empty?
+        hash
+      end
     end
 
+    # The turn-start note (WorkingSetSteer#record!): a tail system message
+    # of this kind, its ops ([{"op", "kind", "key", "label"}]) in NOTE_OPS.
+    NOTE_KIND = "working_set"
+    NOTE_OPS = :working_set_ops
+    ADD = "add"
+
     FILE_OPS = { "read" => "read", "edit" => "edit", "write" => "edit" }.freeze
     CONTENT = %w[read memory_read web_fetch].freeze
     MEMORY_READ = Tools::MemoryRead::NAME
@@ -81,21 +110,95 @@ module Samagotchi
     # @param strategy [Symbol, Array<Symbol>] :none or the layers, as
     #   LLMContextView takes it (the session's current one)
     # @param stat [#call] File.stat, or a stand-in (specs)
+    # @param pins [Array<WorkingSetPin>] the session's pins
     # @return [Snapshot]
-    def build(conversation, cwd:, strategy:, stat: File.method(:stat))
+    def build(conversation, cwd:, strategy:, stat: File.method(:stat), pins: [])
+      conversation = Array(conversation)
+      view = LLMContextView.new(strategy: strategy)
+      pinned = pins.to_set { |pin| [pin.kind, pin.key] }
+      items = all_touches(conversation, cwd, view).group_by { |touch| [touch.kind, touch.key] }.map do |(kind, key), group|
+        item(kind, key, group, conversation, view, stat, pinned.include?([kind, key]))
+      end
+      Snapshot.new(items: items, at: conversation.size, adds: pending_adds(conversation))
+    end
+
+    # The index of the note the next turn will send (one after the last
+    # turn's entries: only system messages follow it), or nil.
+    def pending_note_index(messages)
+      (messages.size - 1).downto(0) do |index|
+        message = messages[index]
+        return nil unless message.is_a?(Hash) && message[:role].to_s == "system"
+        return index if message[:kind].to_s == NOTE_KIND
+      end
+      nil
+    end
+
+    # The ops the pending note lists ([{"op", "kind", "key", "label"}]).
+    def pending_ops(messages)
+      messages = Array(messages)
+      index = pending_note_index(messages)
+      index ? Array(messages[index][NOTE_OPS]).select { |op| op.is_a?(Hash) } : []
+    end
+
+    # The items the user added since the last turn, which the next turn's
+    # note asks the model to read.
+    # @return [Array<Add>]
+    def pending_adds(messages)
+      pending_ops(messages).select { |op| op["op"] == ADD }.map do |op|
+        Add.new(kind: op["kind"].to_s, key: op["key"].to_s, label: op["label"].to_s)
+      end
+    end
+
+    # One content output (read, memory_read, web_fetch) of an item: its
+    # chi +id+ (ToolIds), the +index+ of the tool_response entry holding
+    # it, whether the id is +derived+ (a legacy entry's: nothing can name
+    # it) and whether the model is still +sent+ it under the strategy.
+    # +shared_with+: the other names a memory_read of several names holds in the
+    # same output (an op on the output acts on them too), else empty.
+    Output = Data.define(:id, :index, :derived, :sent, :shared_with)
+
+    # The content outputs of the item +kind+/+key+ (#build's identity: a
+    # file's absolute path, a memory's name, a URL), in conversation
+    # order, by the same pairing #build uses, so what acts on an item's
+    # outputs and the projection never disagree. Edit-only items have
+    # none. A memory_read of several names is one output of each.
+    # @return [Array<Output>]
+    def outputs_of(conversation, kind:, key:, strategy:, cwd:)
       conversation = Array(conversation)
       view = LLMContextView.new(strategy: strategy)
+      all_touches(conversation, cwd, view).filter_map do |touch|
+        next unless touch.content && touch.kind == kind && touch.key == key
+
+        ref = touch.run.ref
+        Output.new(id: ref.id, index: touch.run.index, derived: ref.derived?,
+                   sent: still_sent?(touch, conversation, view), shared_with: shared_with(touch, key))
+      end
+    end
+
+    # The ids of the content outputs of the items +pins+ name (the ones
+    # the model's forget_outputs refuses), by the same pairing as #build.
+    # @param pins [Array<WorkingSetPin>]
+    # @return [Set<String>]
+    def pinned_ids(conversation, pins:, cwd:)
+      return Set.new if pins.empty?
+
+      conversation = Array(conversation)
+      pinned = pins.to_set { |pin| [pin.kind, pin.key] }
+      touches = all_touches(conversation, cwd, LLMContextView.new(strategy: LLMContextView::NONE))
+      touches.select { |touch| touch.content && pinned.include?([touch.kind, touch.key]) }.to_set { |touch| touch.run.ref.id }
+    end
+
+    # Every paired run's touches, with what +view+ sends of its output.
+    def all_touches(conversation, cwd, view)
       stored = LLMContextStale.paired_runs(conversation)
-      sent = if view.none?
+      # Under none with no drop the view sends the conversation as it is.
+      messages = view.messages(conversation)
+      sent = if messages.equal?(conversation)
                {}
              else
-               LLMContextStale.paired_runs(view.messages(conversation)).to_h { |run| [run.ref.id, run.text] }
+               LLMContextStale.paired_runs(messages).to_h { |run| [run.ref.id, run.text] }
              end
-      touches = stored.flat_map { |run| touches(run, sent.fetch(run.ref.id, run.text), cwd) }
-      items = touches.group_by { |touch| [touch.kind, touch.key] }.map do |(kind, key), group|
-        item(kind, key, group, conversation, view, stat)
-      end
-      Snapshot.new(items: items, at: conversation.size)
+      stored.flat_map { |run| touches(run, sent.fetch(run.ref.id, run.text), cwd) }
     end
 
     # The items +run+ touched (none when it failed or was interrupted).
@@ -127,6 +230,9 @@ module Samagotchi
       ToolResponse.interrupted_text?(text) || text.sub(ToolResponse::LEAD, "").lstrip.start_with?("Error")
     end
 
+    # The other names +touch+'s output holds (a memory_read of several).
+    def shared_with(touch, key) = touch.share > 1 ? found_names(touch.run) - [key] : []
+
     # A memory_read's names (Tools::MemoryRead.parse_names: none for the
     # index listing), less the ones its output says weren't found.
     def found_names(run)
@@ -136,19 +242,19 @@ module Samagotchi
       names - missing
     end
 
-    def item(kind, key, group, conversation, view, stat)
+    def item(kind, key, group, conversation, view, stat, pinned)
       first = group.first
       contents = group.select(&:content)
       tokens = contents.sum { |touch| touch.sent.length / TokenUsage::CHARS_PER_TOKEN / touch.share }.ceil
       state = if contents.any? && contents.none? { |touch| still_sent?(touch, conversation, view) }
-                FORGOTTEN
+                contents.all? { |touch| dropped?(touch, conversation) } ? DROPPED : FORGOTTEN
               elsif kind == FILE && changed?(key, group.last.run, conversation, stat)
                 STALE
               else
                 LIVE
               end
       Item.new(kind: kind, key: key, state: state, tokens: tokens, ops: group.map(&:op).uniq, count: group.size,
-               first_id: first.run.ref.id)
+               first_id: first.run.ref.id, pinned: pinned, has_drop: contents.any? { |touch| dropped?(touch, conversation) })
     end
 
     # Whether the model is still sent +touch+'s output: whole (with the
@@ -161,11 +267,17 @@ module Samagotchi
       return true if sent == stored || sent == with_id(stored, touch.run.ref.id)
 
       edit = LLMContextEdit.on(conversation[touch.run.index])[touch.run.ref.id]
-      return true unless edit&.applied? && view.layers.include?(edit.kind)
+      return true unless edit && view.sends?(edit)
 
       edit.kind == :forget ? edit.keep? : edit.note.match?(BY_EDIT)
     end
 
+    # Whether +touch+'s output holds the user's applied drop.
+    def dropped?(touch, conversation)
+      edit = LLMContextEdit.on(conversation[touch.run.index])[touch.run.ref.id]
+      !edit.nil? && edit.kind == LLMContextEdit::DROP && edit.applied?
+    end
+
     def with_id(text, id)
       match = text.match(ToolResponse::LEAD)
       match ? "#{match[0]}[##{id}] #{match.post_match}" : nil
@@ -195,6 +307,6 @@ module Samagotchi
 
     def field(hash, key) = hash.key?(key) ? hash[key] : hash[key.to_s]
 
-    private_class_method :touches, :failed?, :found_names, :item, :still_sent?, :with_id, :changed?, :stamp_of, :field
+    private_class_method :all_touches, :touches, :failed?, :found_names, :shared_with, :item, :still_sent?, :dropped?, :with_id, :changed?, :stamp_of, :field
   end
 end