samagotchi 0.101.0 → 0.103.0

data/lib/samagotchi/cli/parent_wait.rb

@@ -4,6 +4,7 @@ require_relative "../session"
 require_relative "../reply_wait"
 require_relative "../parent_report"
 require_relative "exit"
+require_relative "../session_access"
 
 module Samagotchi
   module CLI
@@ -12,8 +13,8 @@ module Samagotchi
     # for it, and the wait for what comes next, reported the ParentReport
     # way (Ctrl-C included). The including class (a CLI::Command) defines
     # #parse (options, or an exit status) and #run_parsed(options), sets
-    # @stdout, @stderr and @state_dir, and may override the constants
-    # (specs stub them on the class).
+    # @stdout, @stderr and @access (a SessionAccess backend), and may
+    # override the constants (specs stub them on the class).
     module ParentWait
       POLL_INTERVAL = ReplyWait::POLL_INTERVAL
       # No live worker this long while waiting: it died before it could mark
@@ -30,7 +31,14 @@ module Samagotchi
         # With --format json stdout is one JSON object, whatever the end: a
         # failure before the wait is reported from stderr's last line.
         @stderr = ParentReport::LastLine.new(@stderr) if @json
-        status = run_parsed(options)
+        status = begin
+          run_parsed(options)
+        rescue SessionAccess::RemoteFailed => e
+          # A remote that went away mid-run: the command's line, and with
+          # --format json its object.
+          error_line("#{command_name}: #{e.message}")
+          Exit::FAILED
+        end
         if @json && !@reported && status == 1
           detail = @stderr.last.to_s.delete_prefix("#{command_name}: ")
           @stdout.puts(ParentReport.error_line(detail, session_id: @session_id))
@@ -45,9 +53,7 @@ module Samagotchi
       # error line; nil after the error line.
       # @return [String, nil]
       def resolve(given)
-        id = Session.resolve_id(given, state_dir: @state_dir)
-        Session.load(id, state_dir: @state_dir)
-        @session_id = id
+        @session_id = @access.resolve(given)
       rescue ArgumentError => e
         error_line("#{command_name}: #{e.is_a?(Session::AmbiguousId) ? e.message : "no session #{given}"}")
         nil
@@ -70,16 +76,19 @@ module Samagotchi
       # @return [Integer] the exit status
       def wait_for_reply(id, cursor:, baseline:, timeout:, owner_grace: self.class::WORKER_GONE_AFTER, turn: nil,
                          queued: false, ended_before: false, report_turn_id: turn)
-        result = ReplyWait.call(id, state_dir: @state_dir, cursor: cursor, timeout: timeout, baseline: baseline,
-                                    owner_grace: owner_grace, poll_interval: self.class::POLL_INTERVAL, turn: turn,
-                                    queued: queued, ended_before: ended_before)
+        result = @access.wait_reply(id, cursor: cursor, timeout: timeout, baseline: baseline, owner_grace: owner_grace,
+                                        poll_interval: self.class::POLL_INTERVAL, turn: turn, queued: queued,
+                                        ended_before: ended_before)
         result.turn_id = report_turn_id if report_turn_id && !report_turn_id.to_s.empty?
         result.text = result.text&.dup&.force_encoding(Encoding::UTF_8)&.scrub
         @reported = true
-        # What a parent may pick there: config.yml tightened by the session's own.
-        strategy = ParentReport.strategy_for(id, state_dir: @state_dir)
+        # What a parent may pick there: config.yml tightened by the session's
+        # own. Machine-local (this machine's config.yml): remotely the
+        # server's (P2's wait route).
+        strategy = @access.parent_strategy(id)
         ParentReport.report(result, session_id: id, stdout: @stdout, stderr: @stderr, command: command_name,
-                                    json: @json, timeout: timeout, extra: report_extra, strategy: strategy)
+                                    json: @json, timeout: timeout, extra: report_extra, strategy: strategy,
+                                    via: @access.invocation)
       rescue Interrupt
         if @json
           @stdout.puts(ParentReport.json_line(ReplyWait::Result.new(status: :canceled, turn_id: report_turn_id), session_id: id,
@@ -87,7 +96,7 @@ module Samagotchi
           @stdout.flush
           @reported = true
         end
-        error_line("#{command_name}: still running: chi --attach #{id}")
+        error_line("#{command_name}: still running: #{@access.invocation.shows(id)}")
         Exit::INTERRUPTED
       rescue ArgumentError
         error_line("#{command_name}: the session is gone (deleted while waiting)")

data/lib/samagotchi/commands/registry.rb

@@ -96,6 +96,10 @@ module Samagotchi
       end
       private_class_method :listed_mid_turn
 
+      # A name is taken once, with one exception: core may give a name two
+      # entries, one the UIs run (local) and one the session runs, each with
+      # its own match (/recap shows in a UI, /recap off runs in the worker).
+      # #listing then has the name twice, /help and Tab once.
       # @param anytime [Boolean] mid_turn: :anytime (a bundle's command)
       # @param mid_turn [Symbol, #call, nil] see Entry; nil takes +anytime+
       # @param match [#call, nil] the default matches the name alone or the
@@ -104,7 +108,7 @@ module Samagotchi
       # @return [Entry]
       def register(name, description, id: nil, anytime: false, mid_turn: nil, local: false, uis: nil, match: nil,
                    source: "core", annotations: [], &handler)
-        raise ArgumentError, "command #{name} is already registered" if @entries.any? { |entry| entry.name == name }
+        raise ArgumentError, "command #{name} is already registered" unless name_free?(name, local: local, source: source)
 
         entry = Entry.new(id: id || name.delete_prefix("/").to_sym, name: name, description: description,
                           mid_turn: mid_turn || (anytime ? :anytime : :refuse), local: local, uis: uis, match: match || default_match(name),
@@ -203,6 +207,13 @@ module Samagotchi
         @entries << entry
       end
 
+      def name_free?(name, local:, source:)
+        taken = @entries.select { |entry| entry.name == name }
+        return true if taken.empty?
+
+        source == "core" && taken.size == 1 && taken.first.source == "core" && !taken.first.local != !local
+      end
+
       def default_match(name)
         after = /\A#{Regexp.escape(name)}\s/
         ->(text) { text == name || after.match?(text) }

data/lib/samagotchi/config.rb

@@ -22,6 +22,10 @@ module Samagotchi
   autoload :ModelSetting, File.expand_path("model_settings", __dir__)
   # The per-model/host seconds a cut waits (like Thinking for the level).
   autoload :SteerCutAfter, File.expand_path("steer_cut_after", __dir__)
+  # A refused --set (Config.coerce! raises its Error), and recap.sentences'
+  # check (IdleRecap::RecapPrompt): both load on first use.
+  autoload :SessionConfig, File.expand_path("session_config", __dir__)
+  autoload :IdleRecap, File.expand_path("idle_recap", __dir__)
 
   # Unified configuration registry implementing the implicit convention:
   #   ENV    SAMAGOTCHI_ATTR            (UPPER + prefix + _ = nesting)
@@ -39,8 +43,12 @@ module Samagotchi
   module Config
     # invalid: what an enum's invalid value falls to, when not the default
     # (guardrails.parent_answers: the strictest).
+    # session: true for a key a session may set for itself (chi --set KEY=VALUE,
+    # SessionConfig; its value is read through Config.get(key, session:)),
+    # check: a lambda that takes a typed value and returns nil, or the
+    # "takes ..." phrase a refused --set names (recap.sentences' N or N-M).
     Entry = Struct.new(:key, :yaml_path, :type, :default, :expose, :enum_values, :yaml_aliases, :lifecycle, :invalid,
-                       keyword_init: true) do
+                       :session, :check, keyword_init: true) do
       def env_key
         "SAMAGOTCHI_" + yaml_path.map { |p| p.upcase }.join("_")
       end
@@ -64,6 +72,9 @@ module Samagotchi
       def config_exposed?
         expose.include?(:config)
       end
+
+      # Whether a session may set the key for itself (chi --set).
+      def session? = session == true
     end
 
     # Section names: lower alnum only, no _ or -.
@@ -93,7 +104,9 @@ module Samagotchi
       # off on local ones. hosts.<name>.first_token_timeout wins.
       Entry.new(key: "server.first_token_timeout", yaml_path: %w[server first_token_timeout], type: :integer, default: nil,          expose: %i[env config], lifecycle: :worker_start),
 
-      Entry.new(key: "recap.enabled",            yaml_path: %w[recap enabled],             type: :bool,   default: nil,              expose: %i[env config], lifecycle: :worker_start),
+      # Both session-settable (chi --set recap.enabled=false): RecapSetup reads them through the session's layer.
+      Entry.new(key: "recap.enabled",            yaml_path: %w[recap enabled],             type: :bool,   default: nil,              expose: %i[env config], lifecycle: :worker_start,
+                session: true),
       Entry.new(key: "recap.model",              yaml_path: %w[recap model],               type: :string, default: nil,              expose: %i[env config cli], lifecycle: :worker_start),
       Entry.new(key: "recap.base_url",           yaml_path: %w[recap base_url],            type: :string, default: nil,              expose: %i[env config cli], lifecycle: :worker_start),
       Entry.new(key: "recap.host_ref",           yaml_path: %w[recap host_ref],            type: :string, default: nil,              expose: %i[env config cli], yaml_aliases: %w[host], lifecycle: :worker_start),
@@ -101,7 +114,9 @@ module Samagotchi
       Entry.new(key: "recap.timeout",            yaml_path: %w[recap timeout],             type: :float,   default: nil,             expose: %i[env config cli], lifecycle: :worker_start),
       Entry.new(key: "recap.min_user_turns",     yaml_path: %w[recap min_user_turns],      type: :integer, default: nil,             expose: %i[env config cli], lifecycle: :worker_start),
       # "N-M" or "N" sentences (1-10); unset = 2-4. Parsed by RecapPrompt.sentences_range.
-      Entry.new(key: "recap.sentences",          yaml_path: %w[recap sentences],           type: :string,  default: nil,             expose: %i[env config cli], lifecycle: :worker_start),
+      Entry.new(key: "recap.sentences",          yaml_path: %w[recap sentences],           type: :string,  default: nil,             expose: %i[env config cli], lifecycle: :worker_start,
+                session: true,
+                check: ->(value) { "N or N-M (1-#{IdleRecap::RecapPrompt::MAX_SENTENCES})" unless IdleRecap::RecapPrompt.sentences_range(value) }),
 
       # chi broadcast (Broadcast::Recipients, Broadcast::Tags): a session that ended no turn in this many hours (and
       # no worker or REPL runs) gets no broadcast; a ticket id in the note and in a session's branch or prompts
@@ -308,7 +323,7 @@ module Samagotchi
 
     # Top-level maps and lists read by their own code, whose entry names and
     # contents are the user's: ConfigFile.model_aliases / preloaded_memories /
-    # appended_prompt_files, Hooks::Loader, Engine#read_bundle_settings.
+    # appended_prompt_files, Hooks::Loader, ConfigFile.bundle_settings.
     FREE_FORM_MAPS = %w[model_aliases hooks bundles memories append_system_prompt].freeze
     # Maps of named entries and the keys an entry may hold
     # (ConfigFile.hosts_config, ConfigFile.model_settings).
@@ -324,6 +339,10 @@ module Samagotchi
     # And toolkit's kits (Toolkit.kits).
     SECTION_EXTRA_KEYS = { "guardrails" => %w[rules disable].freeze, "toolkit" => %w[kits].freeze }.freeze
 
+    # What a :bool value reads as (Config.coerce!), YAML 1.1's words and 1/0.
+    BOOL_WORDS = { "1" => true, "true" => true, "yes" => true, "on" => true,
+                   "0" => false, "false" => false, "no" => false, "off" => false }.freeze
+
     # Fast lookup maps
     BY_KEY = ENTRIES.each_with_object({}) { |e, h| h[e.key] = e }.freeze
 
@@ -342,58 +361,70 @@ module Samagotchi
         ENTRIES.select(&:cli_exposed?)
       end
 
-      # Coercion helpers
-      def coerce(entry, raw)
+      # The entries a session may set for itself (Entry#session?).
+      def session_entries
+        ENTRIES.select(&:session?)
+      end
+
+      # +raw+ as +entry+'s type, strictly: a value of another shape raises.
+      # :string as given (a YAML list joined with |), :integer, :float,
+      # :bool (true/yes/on/1, false/no/off/0/""), :enum in its canonical
+      # case; nil for nil, and for a blank value of any other type than
+      # :string and :bool. #coerce is its lenient twin (config.yml, env).
+      # @raise [SessionConfig::Error] "KEY takes WHAT, not RAW"
+      def coerce!(entry, raw)
         return nil if raw.nil?
+        # A YAML list for a "|"-separated setting (web.annotate_presets).
+        # As given, trailing spaces included ("Please ").
+        return raw.is_a?(Array) ? raw.join("|") : raw.to_s if entry.type == :string
 
-        # For string, preserve as-is (including trailing spaces like "Please ")
-        if entry.type == :string
-          # A YAML list for a "|"-separated setting (web.annotate_presets).
-          str = raw.is_a?(Array) ? raw.join("|") : raw.to_s
-          return nil if str.empty? && entry.type != :string
+        str = raw.to_s.strip
+        return false if entry.type == :bool && str.empty?
+        return nil if str.empty?
+
+        value = case entry.type
+                when :integer then Integer(str, exception: false)
+                when :float then Float(str, exception: false)
+                when :bool then BOOL_WORDS[str.downcase]
+                when :enum then entry.enum_values.find { |v| v.downcase == str.downcase }
+                else str
+                end
+        raise SessionConfig::Error, "#{entry.key} takes #{takes(entry)}, not #{raw.to_s.inspect}" if value.nil?
+
+        value
+      end
 
-          return str
+      # What +entry+'s type takes, as a refusal names it.
+      def takes(entry)
+        case entry.type
+        when :integer then "an integer"
+        when :float then "a number"
+        when :bool then "true or false"
+        when :enum then "#{entry.enum_values[0..-2].join(", ")} or #{entry.enum_values.last}"
+        else "text"
         end
-        str = raw.to_s.strip
-        return nil if str.empty? && entry.type != :string
+      end
 
+      # +raw+ as +entry+'s type (#coerce!), leniently: a value of another
+      # shape warns and falls back (the default; false for a bool; an
+      # enum's +invalid+ when it has one).
+      def coerce(entry, raw)
+        coerce!(entry, raw)
+      rescue SessionConfig::Error
         case entry.type
-        when :string
-          str
         when :integer
-          Integer(str, exception: false).tap do |v|
-            if v.nil?
-              Log.warn(:config, "invalid_value", echo: "Warning: invalid integer for #{entry.key} (#{entry.env_key}): #{raw.inspect} — using default", key: entry.key)
-              return entry.default
-            end
-          end
+          Log.warn(:config, "invalid_value", echo: "Warning: invalid integer for #{entry.key} (#{entry.env_key}): #{raw.inspect} — using default", key: entry.key)
+          entry.default
         when :float
-          val = Float(str, exception: false)
-          if val.nil?
-            Log.warn(:config, "invalid_value", echo: "Warning: invalid float for #{entry.key}: #{raw.inspect}", key: entry.key)
-            return entry.default
-          end
-          val
+          Log.warn(:config, "invalid_value", echo: "Warning: invalid float for #{entry.key}: #{raw.inspect}", key: entry.key)
+          entry.default
         when :bool
-          case str.downcase
-          when "1", "true", "yes", "on" then true
-          when "0", "false", "no", "off", "" then false
-          else
-            Log.warn(:config, "invalid_value", echo: "Warning: invalid bool for #{entry.key}: #{raw.inspect} — treating as false", key: entry.key)
-            false
-          end
-        when :enum
-          lowered = str.downcase
-          allowed = entry.enum_values.map(&:downcase)
-          unless allowed.include?(lowered)
-            using = entry.invalid ? "using #{entry.invalid}" : "using default"
-            Log.warn(:config, "invalid_value", echo: "Warning: invalid value for #{entry.key}: #{raw.inspect} (allowed: #{entry.enum_values.join(", ")}) — #{using}", key: entry.key)
-            return entry.invalid || entry.default
-          end
-          # return canonical casing from enum_values
-          entry.enum_values.find { |v| v.downcase == lowered }
+          Log.warn(:config, "invalid_value", echo: "Warning: invalid bool for #{entry.key}: #{raw.inspect} — treating as false", key: entry.key)
+          false
         else
-          str
+          using = entry.invalid ? "using #{entry.invalid}" : "using default"
+          Log.warn(:config, "invalid_value", echo: "Warning: invalid value for #{entry.key}: #{raw.inspect} (allowed: #{entry.enum_values.join(", ")}) — #{using}", key: entry.key)
+          entry.invalid || entry.default
         end
       end
 
@@ -406,10 +437,14 @@ module Samagotchi
       end
 
       # Same as #resolve, plus the layer the value came from:
-      # :cli, :env, :file or :default.
-      def resolve_with_origin(key, file_data: nil, env: ENV, cli_overrides: {})
+      # :session, :cli, :env, :file or :default. +session+ is a session's
+      # own values (SessionConfig::Settings#core, typed): a session-settable
+      # key's value there goes first, over the CLI (a worker gets its CLI
+      # as env, and the session's value was given for this session).
+      def resolve_with_origin(key, file_data: nil, env: ENV, cli_overrides: {}, session: nil)
         entry = find_by_key(key)
         raise ArgumentError, "unknown config key: #{key}" unless entry
+        return [session[entry.key], :session] if entry.session? && session&.key?(entry.key)
 
         # CLI wins
         if cli_overrides.key?(entry.key)
@@ -523,8 +558,9 @@ module Samagotchi
         end
       end
 
-      def get(key)
-        get_with_origin(key).first
+      # The live value of +key+; +session+ as #resolve_with_origin takes it.
+      def get(key, session: nil)
+        get_with_origin(key, session: session).first
       end
 
       # default.max_tokens: the most tokens one generation may produce, or
@@ -545,8 +581,8 @@ module Samagotchi
       end
 
       # [value, origin] for the live value #get returns; origin is one of
-      # :cli, :env, :file, :default.
-      def get_with_origin(key)
+      # :session, :cli, :env, :file, :default.
+      def get_with_origin(key, session: nil)
         entry = find_by_key(key)
         raise ArgumentError, "unknown config key: #{key}" unless entry
 
@@ -555,7 +591,7 @@ module Samagotchi
         # overrides captured via reload!
         path = Samagotchi::ConfigFile.global_path rescue nil
         file_data = Samagotchi::ConfigFile.read_yaml(path: path) if path
-        resolve_with_origin(entry.key, file_data: file_data, env: ENV, cli_overrides: cli_overrides)
+        resolve_with_origin(entry.key, file_data: file_data, env: ENV, cli_overrides: cli_overrides, session: session)
       end
 
       # Problems with the keys of a parsed config.yml, one message per key the

data/lib/samagotchi/context_command.rb

@@ -11,6 +11,7 @@ require_relative "cli/command"
 require_relative "cli/exit"
 require_relative "cli/flags"
 require_relative "redacted_inspect"
+require_relative "session_access/local"
 
 module Samagotchi
   # `chi context`: attach live external text to sessions (ContextSources).
@@ -76,10 +77,16 @@ module Samagotchi
       def project? = session_id.nil?
     end
 
+    # Why chi context rm NAME ID (and chi web's DELETE …/context/NAME?own=1)
+    # leaves a source the session's project has.
+    def self.project_source_message(name) = "#{name} is the project's: chi context rm #{name} --project, or mute it for this session"
+
     # @param argv [Array<String>] the arguments after "context"
     # @param clock [#call] now, for ls's ages ("4s ago")
+    # @param access [SessionAccess::Local, nil] where the sessions are;
+    #   default this machine's, in +state_dir+
     def initialize(argv, stdin: $stdin, stdout: $stdout, stderr: $stderr, state_dir: nil, env: ENV, cwd: Dir.pwd,
-                   clock: -> { Time.now })
+                   clock: -> { Time.now }, access: nil)
       @argv = argv.dup
       @stdin = stdin
       @stdout = stdout
@@ -88,6 +95,7 @@ module Samagotchi
       @env = env
       @cwd = cwd
       @clock = clock
+      @access = access || SessionAccess::Local.new(state_dir: @state_dir)
     end
 
     # @return [Integer] exit status: 0 done, 1 refused or failed, 2 usage
@@ -127,11 +135,10 @@ module Samagotchi
         name: name, cmd: options[:cmd], every_seconds: ContextSources.check_every!(options[:every]),
         why: ContextSources.one_line(options[:why], ContextSources::LINE_MAX_CHARS),
         hint: ContextSources.one_line(options[:hint], ContextSources::LINE_MAX_CHARS),
-        scope: nil, added_by: inside_session ? "agent" : "cli", created_at: Time.now.utc.iso8601
+        scope: nil, added_by: added_by, created_at: Time.now.utc.iso8601
       )
       each_target(options, args) do |target|
-        location = location_of(target)
-        location.add(source.with(scope: location.scope))
+        @access.context_add(target, source)
         @stdout.puts("#{target.label}  attached #{name}")
         true
       end
@@ -144,6 +151,7 @@ module Samagotchi
       if options[:cmd] || options[:push] || options[:every]
         return usage_error("a URL's command comes from its provider: give no --cmd, --push or --every")
       end
+      return add_remote_url(url, options, args) if @access.remote?
 
       resolved = ContextProviders.resolve(url)
       return fail_line("no installed bundle resolves #{url} (chi bundle install github-pr for GitHub PRs)") unless resolved
@@ -152,11 +160,10 @@ module Samagotchi
         name: resolved.name, cmd: resolved.cmd, every_seconds: resolved.every_seconds,
         why: ContextSources.one_line(options[:why] || resolved.why, ContextSources::LINE_MAX_CHARS),
         hint: ContextSources.one_line(options[:hint] || resolved.hint, ContextSources::LINE_MAX_CHARS),
-        scope: nil, added_by: inside_session ? "agent" : "cli", created_at: Time.now.utc.iso8601, provider: resolved.bundle
+        scope: nil, added_by: added_by, created_at: Time.now.utc.iso8601, provider: resolved.bundle
       )
       each_target(options, args) do |target|
-        location = location_of(target)
-        location.add(source.with(scope: location.scope))
+        @access.context_add(target, source)
         @stdout.puts("#{target.label}  attached #{source.name}")
         true
       end
@@ -164,6 +171,19 @@ module Samagotchi
       fail_line(e.message)
     end
 
+    # A URL on a remote: its installed bundles' providers resolve it there.
+    def add_remote_url(url, options, args)
+      why = ContextSources.one_line(options[:why], ContextSources::LINE_MAX_CHARS)
+      hint = ContextSources.one_line(options[:hint], ContextSources::LINE_MAX_CHARS)
+      each_target(options, args) do |target|
+        name = @access.context_add_url(target, url, why: why, hint: hint, added_by: added_by)
+        @stdout.puts("#{target.label}  attached #{name}")
+        true
+      end
+    rescue ContextProviders::Invalid => e
+      fail_line(e.message)
+    end
+
     def run_push(options, args)
       name = args.shift
       return usage_error("give the source's NAME") unless name
@@ -173,18 +193,20 @@ module Samagotchi
 
       fetched = ContextSources.parse_output(text)
       each_target(options, args) do |target|
-        attached = find(target, name) or next false
-        # A command source's text is its command's (R2): a push between
-        # two fetches would read as a change and then vanish.
-        unless attached.source.push?
-          error_line("#{command_name}: #{name} runs a command, which writes its text: push goes to a --push source")
+        pushed = @access.context_push(target, name, fetched)
+        case pushed.status
+        when :missing
+          no_source(target, name)
+          next false
+        when :not_push
+          # A command source's text is its command's (R2): a push between
+          # two fetches would read as a change and then vanish.
+          error_line("#{command_name}: #{SessionAccess::ContextPush.not_push_message(name)}")
           next false
         end
 
-        before, written = attached.location.locked(name) do
-          [attached.location.snapshot(name).revision, attached.location.record_text(name, fetched)]
-        end
-        @stdout.puts("#{target.label}  #{name}: #{written.revision == before ? "unchanged" : "new text"} (#{written.revision[0, 12]})")
+        @stdout.puts("#{target.label}  #{name}: #{pushed.revision == pushed.before ? "unchanged" : "new text"} " \
+                     "(#{pushed.revision[0, 12]})")
         true
       end
     end
@@ -194,7 +216,7 @@ module Samagotchi
       return usage_error("unknown format #{format.inspect}: use --format text|json") unless [nil, "text", "json"].include?(format)
 
       targets = targets(options, args) or return CLI::Exit::FAILED
-      rows = targets.flat_map { |target| rows_for(target) }
+      rows = targets.flat_map { |target| @access.context_entries(target).map { |entry| row(target, entry) } }
       if format == "json"
         @stdout.puts(JSON.pretty_generate(rows))
       elsif rows.empty?
@@ -212,10 +234,10 @@ module Samagotchi
       targets = targets(options, args) or return CLI::Exit::FAILED
       return usage_error("show takes one target") if targets.size > 1
 
-      attached = find(targets.first, name) or return CLI::Exit::FAILED
-      snapshot = attached.snapshot
+      entry = @access.context_entry(targets.first, name) or return no_source(targets.first, name)
+      snapshot = entry.snapshot
       if options[:json]
-        @stdout.puts(JSON.pretty_generate({ "source" => attached.source.to_h, "snapshot" => snapshot.to_h }))
+        @stdout.puts(JSON.pretty_generate({ "source" => entry.source.to_h, "snapshot" => snapshot.to_h }))
         return 0
       end
       unless snapshot.text?
@@ -229,7 +251,8 @@ module Samagotchi
 
     # Runs the command in this process, not the worker's: the result shows
     # here, and the worker sees the new snapshot on its next loop. The
-    # source's lock keeps the two from running it at once.
+    # source's lock keeps the two from running it at once. Local only
+    # (SessionAccess::Contract): it runs the command on this machine.
     def run_refresh(options, args)
       name = args.shift
       return usage_error("give the source's NAME") unless name
@@ -271,15 +294,12 @@ module Samagotchi
 
       ContextSources.check_name!(name)
       each_target(options, args) do |target|
-        location = location_of(target)
-        if location.remove(name)
+        case @access.context_remove(target, name)
+        when :removed
           @stdout.puts("#{target.label}  detached #{name}")
           next true
-        end
-
-        project = !target.project? && ContextSources.project_location_for(target.project_root, state_dir: @state_dir)
-        if project&.source(name)
-          error_line("#{command_name}: #{name} is the project's: chi context rm #{name} --project, or mute it for this session")
+        when :project
+          error_line("#{command_name}: #{self.class.project_source_message(name)}")
         else
           error_line("#{command_name}: no source #{name} for #{target.label}")
         end
@@ -287,6 +307,7 @@ module Samagotchi
       end
     end
 
+    # Local only (SessionAccess::Contract): the session's muted/ files here.
     def run_mute(options, args) = mute_or_unmute(options, args, mute: true)
     def run_unmute(options, args) = mute_or_unmute(options, args, mute: false)
 
@@ -327,10 +348,11 @@ module Samagotchi
         return [target]
       end
       if args.empty?
-        own = inside_session
+        own = inside_session unless @access.remote?
         unless own
-          error_line("#{command_name}: give session ids (or unique prefixes), or --project; " \
-                     "inside a chi session it's that session")
+          # Remotely no default: the session chi runs in is this machine's.
+          error_line("#{command_name}: give session ids (or unique prefixes)" \
+                     "#{", or --project; inside a chi session it's that session" unless @access.remote?}")
           return nil
         end
         args = [own]
@@ -340,6 +362,8 @@ module Samagotchi
       resolved.all? ? resolved.uniq : nil
     end
 
+    # A project's sources: local only (SessionAccess::Contract), this
+    # machine's checkout.
     def project_target
       unless MemoryPaths.in_repo?(@cwd)
         error_line("#{command_name}: --project needs a git repository, and #{@cwd} is in none")
@@ -354,8 +378,8 @@ module Samagotchi
     end
 
     def session_target(given)
-      id = Session.resolve_id(given, state_dir: @state_dir)
-      session = Session.load(id, state_dir: @state_dir)
+      id = @access.resolve_id(given)
+      session = @access.show(id)
       Target.new(session_id: id, project_root: session.project_root, cwd: session.working_directory, label: id[0, 8])
     rescue ArgumentError => e
       message = e.is_a?(Session::AmbiguousId) ? e.message : "no session #{given}"
@@ -363,64 +387,47 @@ module Samagotchi
       nil
     end
 
+    # Who adds a source: an agent (chi's execute runs this in a session)
+    # or the user's cli.
+    def added_by = inside_session ? "agent" : "cli"
+
     # The session chi's execute runs this in (SAMAGOTCHI_PARENT_SESSION;
-    # "chi" is a run with no session).
+    # "chi" is a run with no session). Machine-local (a session on this
+    # machine): remotely it is no default target (#targets), the ids are
+    # given.
     def inside_session
       id = @env.fetch("SAMAGOTCHI_PARENT_SESSION", "").to_s.strip
       id.empty? || id == "chi" ? nil : id
     end
 
-    # The folder a target's own sources live in.
-    def location_of(target)
-      if target.project?
-        ContextSources.project_location_for(target.project_root, state_dir: @state_dir)
-      else
-        ContextSources.session_location(target.session_id, state_dir: @state_dir)
-      end
-    end
+    # The folder a target's own sources live in (refresh, mute: local only).
+    def location_of(target) = @access.context_location(target)
 
-    # A source as the target sees it (a session: its own, then its project's).
+    # A source as the target sees it (a session: its own, then its
+    # project's), for refresh and mute (local only).
     # @return [ContextSources::Attached, nil] nil after an error line
     def find(target, name)
-      ContextSources.check_name!(name)
-      found = if target.project?
-                location = location_of(target)
-                source = location.source(name)
-                source && ContextSources::Attached.new(source: source, location: location, shadowed: false)
-              else
-                attached_to(target).find { |a| a.name == name }
-              end
-      error_line("#{command_name}: no source #{name} for #{target.label}") unless found
+      found = @access.context_attached(target, name)
+      no_source(target, name) unless found
       found
     end
 
-    def attached_to(target, shadowed: false)
-      ContextSources.attached(target.session_id, project_root: target.project_root, state_dir: @state_dir,
-                                                 shadowed: shadowed)
-    end
-
-    def rows_for(target)
-      if target.project?
-        location = location_of(target)
-        return location.sources.map { |source| row(target, source, location.snapshot(source.name)) }
-      end
-
-      own = ContextSources.session_location(target.session_id, state_dir: @state_dir)
-      subs = own.subscriptions
-      attached_to(target, shadowed: true).map do |a|
-        snapshot = a.snapshot
-        read = subs[a.name]&.read
-        row(target, a.source, snapshot, muted: own.muted?(a.name), shadowed: a.shadowed,
-                                        unread: snapshot.text? && read != snapshot.revision)
-      end
+    # @return [Integer] 1, after the line
+    def no_source(target, name)
+      error_line("#{command_name}: no source #{name} for #{target.label}")
+      CLI::Exit::FAILED
     end
 
-    def row(target, source, snapshot, muted: nil, shadowed: nil, unread: nil)
+    # One line of ls (its --format json object).
+    # @param entry [SessionAccess::ContextEntry]
+    def row(target, entry)
+      source = entry.source
+      snapshot = entry.snapshot
       { "target" => target.label, "session_id" => target.session_id, "name" => source.name, "scope" => source.scope,
         "cmd" => source.cmd, "every_seconds" => source.every_seconds, "why" => source.why, "hint" => source.hint,
         "added_by" => source.added_by, "created_at" => source.created_at, "fetched_at" => snapshot.fetched_at,
         "revision" => snapshot.revision, "summary" => snapshot.summary, "error" => snapshot.error,
-        "muted" => muted, "shadowed" => shadowed, "unread" => unread }.compact
+        "muted" => entry.muted, "shadowed" => entry.shadowed, "unread" => entry.unread }.compact
     end
 
     def print_rows(rows, labels:)