samagotchi 0.121.0 → 0.122.0

data/lib/samagotchi/bridge_client/stream_open.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "../bridge_secret"
+
+module Samagotchi
+  class BridgeClient
+    # The result of opening an SSE connection. Only Opened owns a socket the
+    # caller may read; refused sockets are consumed for their detail and closed.
+    module StreamOpen
+      Opened = Data.define(:sock, :status, :headers)
+      Refused = Data.define(:reason, :detail, :status)
+      Unreachable = Data.define(:attempts, :detail) do
+        def initialize(attempts:, detail: nil) = super
+      end
+
+      BODY_LIMIT = 16_384
+      BODY_TIMEOUT = 5.0
+
+      module_function
+
+      # The one place a stream's response status is interpreted. Through chi
+      # web, its mapped bridge-secret and not-live responses have their own
+      # status codes (502 and 503).
+      def classify(sock, status, headers)
+        return Unreachable.new(attempts: 0) unless sock
+        return Opened.new(sock: sock, status: 200, headers: headers) if status.to_i == 200
+
+        if status.to_i == 503
+          json = parse(refusal_body(sock, headers))
+          return Unreachable.new(attempts: 1, detail: json&.[]("detail"))
+        end
+
+        body = refusal_body(sock, headers)
+        json = parse(body)
+        detail = json&.[]("detail") || (body unless body.empty?)
+        code = status.to_i
+        error = json&.[]("error")
+        outcome = if code == 404
+                    Refused.new(reason: :unknown_session, detail: detail, status: code)
+                  elsif BridgeSecret.refused?(code, json || body)
+                    Refused.new(reason: :bridge_secret, detail: detail, status: code)
+                  elsif code == 403 && error == "proxied"
+                    Refused.new(reason: :proxied, detail: detail, status: code)
+                  elsif code == 403 && error == "cross_origin"
+                    Refused.new(reason: :cross_origin, detail: detail, status: code)
+                  elsif code == 502 && error == BridgeSecret::ERROR
+                    Refused.new(reason: :bridge_secret, detail: detail, status: code)
+                  else
+                    Refused.new(reason: :other, detail: detail, status: code)
+                  end
+        outcome
+      ensure
+        sock&.close unless (status || 0).to_i == 200
+      end
+
+      # A refusal body is bounded and interruptible by closing its socket.
+      # Content-Length replies stop at their declared size; older Bridges
+      # without it are read through EOF.
+      def refusal_body(sock, headers)
+        length = headers.to_h["content-length"]&.to_i
+        limit = length&.between?(0, BODY_LIMIT) ? length : BODY_LIMIT
+        body = +""
+        deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + BODY_TIMEOUT
+        while body.bytesize < limit
+          left = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          break unless left.positive? && sock.wait_readable(left)
+
+          body << sock.readpartial(limit - body.bytesize)
+        end
+        body.force_encoding(Encoding::UTF_8).scrub
+      rescue IOError, SystemCallError
+        body.force_encoding(Encoding::UTF_8).scrub
+      end
+
+      def parse(body)
+        json = JSON.parse(body)
+        json if json.is_a?(Hash)
+      rescue JSON::ParserError
+        nil
+      end
+      private_class_method :parse
+    end
+  end
+end

data/lib/samagotchi/bridge_client/stream_request.rb

@@ -32,8 +32,14 @@ module Samagotchi
       # @return [Array(TCPSocket, Integer, Hash), nil] the socket positioned
       #   at the body, the HTTP status and the response headers (names in
       #   lower case), or nil when the server can't be reached
+      # @raise [Errno::ETIMEDOUT] a connected server didn't finish its headers
       def open(host:, port:, path:, last_event_id: nil, headers: {}, timeout: nil)
-        sock = TCPSocket.new(host, port, connect_timeout: timeout || CONNECT_TIMEOUT)
+        begin
+          sock = TCPSocket.new(host, port, connect_timeout: timeout || CONNECT_TIMEOUT)
+        rescue SystemCallError, SocketError, IOError
+          return nil
+        end
+
         sock.write(request(host: host, port: port, path: path, last_event_id: last_event_id, headers: headers))
         deadline = timeout && (Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout)
         status = header_line(sock, deadline).to_s[STATUS_LINE, 1].to_i
@@ -47,7 +53,7 @@ module Samagotchi
         [sock, status, received]
       rescue SystemCallError, SocketError, IOError
         sock&.close rescue nil
-        nil
+        raise
       end
 
       # The request's bytes.

data/lib/samagotchi/bridge_client.rb

@@ -8,6 +8,7 @@ require_relative "worker_sidecar"
 require_relative "bridge_secret"
 require_relative "delivery"
 require_relative "chi_invocation"
+require_relative "bridge_client/stream_open"
 require_relative "bridge_client/sse_parser"
 require_relative "bridge_client/event_stream"
 require_relative "bridge_client/stream_request"
@@ -15,8 +16,8 @@ require_relative "bridge_client/stream_request"
 module Samagotchi
   # Client side of a session worker's Bridge: the 127.0.0.1 HTTP + SSE server
   # each SessionManager worker runs for its Engine (see Bridge). Discovery goes
-  # through the worker's `bridge.json` sidecar (WorkerSidecar) in the session
-  # directory.
+  # through WorkerLink (the worker's `bridge.json` sidecar, WorkerSidecar, in
+  # the session directory); .for_sidecar makes the client.
   #
   # Requests are raw one-shot HTTP/1.1 over a TCPSocket (`Connection: close`),
   # exactly what the Bridge's minimal server expects.
@@ -27,7 +28,7 @@ module Samagotchi
     # The request header that carries the Bridge's secret (Bridge#secret_ok?).
     SECRET_HEADER = BridgeSecret::HEADER
     STREAM_CONNECT_ATTEMPTS = 3
-    # Seconds #stream waits for the Bridge's response headers, per attempt:
+    # Seconds #open_stream waits for the Bridge's response headers:
     # a worker that took the connection and froze must not hold the web's
     # proxy thread (as EventStream::HEADER_TIMEOUT for the TUI's).
     STREAM_HEADER_TIMEOUT = 5.0
@@ -49,7 +50,7 @@ module Samagotchi
     Response = Struct.new(:status, :body, keyword_init: true) do
       def ok? = status == 200
 
-      # The Bridge refused it for want of its secret (BridgeSecret::REFUSED says what to do).
+      # The Bridge refused it for want of its secret (BridgeSecret.refused says what to do).
       def secret_refused? = BridgeSecret.refused?(status, body)
 
       # @return [Hash, nil] the body parsed as JSON, or nil when it is not
@@ -75,14 +76,6 @@ module Samagotchi
       "this session's worker runs an older chi and can't #{cant}; restart it: #{restart} (its turns still work)"
     end
 
-    # The live Bridge's sidecar in +session_dir+, or nil. A sidecar whose
-    # port refuses a quick connect is stale (its worker died) and is removed.
-    # @param session_dir [String]
-    # @return [WorkerSidecar, nil]
-    def self.live_sidecar(session_dir, host: HOST)
-      WorkerSidecar.live(session_dir, unlink: true, host: host)
-    end
-
     # The one way a client is made for a worker: its port and its secret
     # come from the same sidecar read, so a respawned worker (a new port, a
     # new secret) is reached by a client made after it, never by hand.
@@ -94,24 +87,11 @@ module Samagotchi
       new(session_id: session_id, port: sidecar.port, secret: sidecar.secret, host: host, read_timeout: read_timeout)
     end
 
-    # @return [BridgeClient, nil] a client for the live Bridge in +session_dir+
-    def self.discover(session_id, session_dir:, host: HOST, read_timeout: READ_TIMEOUT)
-      for_sidecar(session_id, live_sidecar(session_dir, host: host), host: host, read_timeout: read_timeout)
-    end
-
     # How often a wait for a new worker's Bridge looks: a missing sidecar is
     # one stat, and a 0.1 s step cost a create up to 0.1 s (the web's
     # create landed on 0.53/0.63/0.73 s).
     SPAWN_POLL_INTERVAL = 0.02
 
-    # Wait for a freshly spawned worker to publish its Bridge.
-    # @param timeout [Float] seconds
-    # @return [BridgeClient, nil] nil when no live sidecar appeared in time
-    def self.wait_for(session_id, session_dir:, timeout:, host: HOST)
-      sidecar = poll(timeout, interval: SPAWN_POLL_INTERVAL) { live_sidecar(session_dir, host: host) }
-      for_sidecar(session_id, sidecar, host: host)
-    end
-
     # Call the block every +interval+ seconds until it returns a truthy value
     # or +timeout+ seconds have passed (it is always called at least once).
     # @return [Object, nil] the block's first truthy value
@@ -314,22 +294,26 @@ module Samagotchi
     # @return [Array(Integer, Object)] the status and the parsed JSON body
     #   (nil when it isn't JSON); [nil, nil] when no reply came
     def get(path)
+      response = get_response(path)
+      [response.status, response.json]
+    rescue StandardError
+      [nil, nil]
+    end
+
+    # GET /session/:id/<path>, preserving the raw response and raising on I/O.
+    # @return [Response]
+    def get_response(path)
       sock = TCPSocket.new(@host, @port)
       sock.write("GET /session/#{@session_id}/#{path} HTTP/1.1\r\nHost: #{@host}:#{@port}\r\n#{secret_line}Connection: close\r\n\r\n")
       response = read_reply(sock, path)
-      sock.close rescue nil
       # A 500 whose text has "200" in it is not a 200.
       status = response && response[STATUS_LINE, 1]
-      return [nil, nil] unless status
+      raise IOError, "bridge #{path}: invalid response status" unless status
 
       body = response.split("\r\n\r\n", 2)[1] || ""
-      [status.to_i, begin
-        JSON.parse(body)
-      rescue JSON::ParserError
-        nil
-      end]
-    rescue StandardError
-      [nil, nil]
+      Response.new(status: status.to_i, body: body)
+    ensure
+      sock&.close rescue nil
     end
 
     # Monotonic SSE cursor of the live Engine, from GET /session/:id/state.
@@ -342,46 +326,49 @@ module Samagotchi
       nil
     end
 
-    # GET /session/:id/stream: yield the raw SSE body bytes as they arrive
-    # until the Bridge closes the stream.
-    # @param query [String] "" or "?from_seq=N"
-    # @param last_event_id [String, nil] reconnect cursor; the Bridge prefers it
-    #   over ?from_seq
-    # @param running [#call, nil] asked before every read, and every
-    #   STREAM_POLL seconds of silence: the stream ends once it returns
-    #   false. A quiet stream is never cut otherwise.
+    # Open GET /session/:id/stream and classify the response before the
+    # caller answers its own request.
     # @param header_timeout [Float] see STREAM_HEADER_TIMEOUT
-    def stream(query: "", last_event_id: nil, running: nil, header_timeout: STREAM_HEADER_TIMEOUT)
-      sock = nil
-      # Absorb the probe→connect race around a resumed worker's bridge:
-      # the sidecar probe can succeed a moment before the worker dies (or
-      # the bridge socket briefly refuses). A few quick bounded retries
-      # avoid the silent empty-200 that EventSource would otherwise keep
-      # re-opening.
-      status = nil
-      STREAM_CONNECT_ATTEMPTS.times do |attempt|
-        sock, status = connect_stream(query: query, last_event_id: last_event_id, timeout: header_timeout)
-        break if sock
-
-        sleep(0.15 * (attempt + 1))
-      end
-      return unless sock
-
-      # A refusal (a 403 such as bridge_secret) is no event stream: its JSON
-      # isn't passed on as one.
-      if status == 403
-        sock.close rescue nil
-        return
+    # @param attempts [Integer] retries for connection failures only
+    # @yield [sock] called after response headers arrive, before classifying a
+    #   refusal; EventStream uses it to publish the socket for #close
+    # @return [StreamOpen::Opened, StreamOpen::Refused, StreamOpen::Unreachable]
+    def open_stream(query: "", last_event_id: nil, header_timeout: STREAM_HEADER_TIMEOUT,
+                    attempts: STREAM_CONNECT_ATTEMPTS)
+      count = 0
+      while count < attempts
+        count += 1
+        connection = connect_stream(query: query, last_event_id: last_event_id, timeout: header_timeout)
+        if connection
+          sock, status, headers = connection
+          unless !block_given? || yield(sock)
+            sock.close rescue nil
+            return StreamOpen::Unreachable.new(attempts: count)
+          end
+          return StreamOpen.classify(sock, status, headers)
+        end
+        sleep(0.15 * count) if count < attempts
       end
+      StreamOpen::Unreachable.new(attempts: count)
+    rescue Errno::ETIMEDOUT
+      StreamOpen::Unreachable.new(attempts: [count, 1].max)
+    rescue SystemCallError, SocketError, IOError
+      StreamOpen::Unreachable.new(attempts: [count, 1].max)
+    end
 
+    # Read a successful stream opened by #open_stream.
+    # @param opened [StreamOpen::Opened]
+    # @param running [#call, nil] checked before every read and every
+    #   STREAM_POLL seconds of silence
+    def read_stream(opened, running: nil)
+      sock = opened.sock
       begin
         loop do
           if running
             break unless running.call
             next unless sock.wait_readable(STREAM_POLL)
           end
-          chunk = sock.readpartial(4096)
-          yield chunk
+          yield sock.readpartial(4096)
         rescue IOError, Errno::ECONNRESET, Errno::ECONNREFUSED # EOFError is an IOError
           break
         end

data/lib/samagotchi/bridge_secret.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "json"
+require_relative "chi_invocation"
 
 module Samagotchi
   # A session Bridge's secret, as both sides name it: the request header
@@ -12,16 +13,17 @@ module Samagotchi
     HEADER = "X-Chi-Bridge"
     # The 403's error.
     ERROR = "bridge_secret"
-    # What a request without this Bridge's secret, or with another one, is
-    # told, and what a client shows when it gets that: the asker comes from
-    # a chi that reads no secret, a chi web, an attached terminal or a
-    # session worker (a delegate's parent) started before chi was updated.
-    REFUSED = "the request didn't name this session worker's secret: a chi web, an attached terminal or a session " \
-              "worker started before chi was updated can't reach it; restart chi web, re-attach terminals " \
-              "(chi --attach ID) and restart the older session workers (chi sessions restart ID...)"
 
     module_function
 
+    # What every client shows when a worker refuses its secret.
+    def refused(session_id, via: ChiInvocation::HERE)
+      web = via.remote? ? via.web : "chi web"
+      "session #{session_id}'s worker refused this chi's request (it didn't name its secret): a chi web or " \
+        "terminal started before chi was updated can't reach it; restart #{web}, re-attach with " \
+        "#{via.attach(session_id)}, or restart the worker with #{via.command("sessions restart #{session_id}")}"
+    end
+
     # Whether a Bridge reply (+status+, raw +body+) is this refusal.
     def refused?(status, body)
       return false unless status.to_i == 403

data/lib/samagotchi/bundle_command/check.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require "prism"
 require "rbconfig"
 require "stringio"
 require "tmpdir"
@@ -214,8 +215,9 @@ module Samagotchi
         floor = lower_bound(manifest.requires_chi)
         return unless floor && File.file?(path(manifest.plugin[:file]))
 
-        calls = File.read(path(manifest.plugin[:file])).scan(API_CALL).flat_map { |call| [call, call.split(".").first(2).join(".")] }
-                    .uniq.select { |call| Plugin::Api::SINCE.key?(call) }
+        source = File.read(path(manifest.plugin[:file]))
+        calls = source.scan(API_CALL).flat_map { |call| [call, call.split(".").first(2).join(".")] }
+        calls = (calls + keyword_calls(source)).uniq.select { |call| Plugin::Api::SINCE.key?(call) }
         call = calls.max_by { |c| Gem::Version.new(Plugin::Api::SINCE[c]) } or return
         version = Plugin::Api::SINCE[call]
         return unless Gem::Version.new(version) > floor
@@ -226,6 +228,29 @@ module Samagotchi
                                                                                       fix: "requires_chi: \">= #{version}\"")
       end
 
+      # Each API call's keywords in +source+, as "chi.toolkit(groups:)": the
+      # call's receiver as written, its name and the keyword (Prism sees
+      # them with or without parens, over lines). Nothing when it doesn't parse.
+      def keyword_calls(source)
+        result = Prism.parse(source)
+        return [] unless result.success?
+
+        found = []
+        nodes = [result.value]
+        while (node = nodes.pop)
+          nodes.concat(node.compact_child_nodes)
+          next unless node.is_a?(Prism::CallNode) && node.receiver && node.arguments
+
+          call = "#{node.receiver.slice}.#{node.name}"
+          node.arguments.arguments.grep(Prism::KeywordHashNode).each do |hash|
+            hash.elements.each do |pair|
+              found << "#{call}(#{pair.key.unescaped}:)" if pair.is_a?(Prism::AssocNode) && pair.key.is_a?(Prism::SymbolNode)
+            end
+          end
+        end
+        found
+      end
+
       def lower_bound(requirement)
         requirement.to_s.split(",").filter_map do |part|
           version = part.strip[LOWER_BOUND, 1]

data/lib/samagotchi/bundles/claude-peer/manifest.yml

@@ -1,6 +1,6 @@
 ---
 name: claude-peer
-version: 0.4.4
+version: 0.4.5
 scope: system
 description: "Pair this session with a Claude Code session you work with: the claude_send tool and /claude send it a part of the work (a plan step, a diff, a finding) to validate or as context, and Claude's answer comes back as the claude-outbox context; /claude install-skill installs Claude's chi-peer skill, which pairs"
 trust_level: reviewed
@@ -12,7 +12,7 @@ plugin:
   file: plugin.rb
   sha256: sha256:50f427d3862ae9d0d15693b4d887c528162b96c0320cc663df89d59d830d4660
 scripts:
-  pair: sha256:106d5b44020602fcd2d8065da30d10e1043e30c1b31ea82b4f27f7f79ada6592
+  pair: sha256:d8089ec422a816367d8c41393235223e06b21cbc0ae1e37b6fc22e94ea9a1497
   chi-peer-SKILL.md: sha256:b9366f8f4aee9c54d209368ce421eab7b971c03c75efab0415d1988fd40f9e60
 # The plugin needs Samagotchi::Plugin::Peer and chi.peer_source (chi 0.67.0).
 # An agreeing answer's closing wake (the skills say an OK wakes chi once)

data/lib/samagotchi/bundles/claude-peer/scripts/pair

@@ -26,17 +26,20 @@ while [ $# -gt 0 ]; do
   case "$1" in
     --inbox-socket)
       [ $# -ge 2 ] || usage
-      inbox=$2 shift 2
+      inbox=$2
+      shift 2
       [ -n "$inbox" ] || usage
       ;;
     --inbox-socket=*)
-      inbox=${1#--inbox-socket=} shift
+      inbox=${1#--inbox-socket=}
+      shift
       [ -n "$inbox" ] || usage
       ;;
     -h | --help) usage ;;
     *)
       [ -z "$target" ] || usage
-      target=$1 shift
+      target=$1
+      shift
       ;;
   esac
 done
@@ -84,10 +87,21 @@ case "$target" in
   *) id=$target ;;
 esac
 
-# A JSON string: backslashes, quotes, tabs and newlines escaped.
+# A JSON string: backslashes and quotes escaped, newlines, tabs and
+# carriage returns as \n, \t, \r, any other control character as \u00XX.
 json() {
-  printf '%s' "$1" | sed -e 's/\\/\\\\/g' -e 's/"/\\"/g' -e 's/	/\\t/g' |
-    awk 'BEGIN { ORS = ""; printf "\"" } NR > 1 { print "\\n" } { print } END { printf "\"" }'
+  printf '%s' "$1" | awk '
+    BEGIN {
+      ORS = ""; printf "\""
+      for (i = 1; i < 32; i++) esc[sprintf("%c", i)] = sprintf("\\u%04x", i)
+      esc["\t"] = "\\t"; esc["\r"] = "\\r"; esc["\\"] = "\\\\"; esc["\""] = "\\\""
+    }
+    NR > 1 { print "\\n" }
+    {
+      n = length($0)
+      for (i = 1; i <= n; i++) { c = substr($0, i, 1); print ((c in esc) ? esc[c] : c) }
+    }
+    END { printf "\"" }'
 }
 
 # Attaches a pushed source, unless the session has one of that name already.

data/lib/samagotchi/bundles/codex-peer/manifest.yml

@@ -1,6 +1,6 @@
 ---
 name: codex-peer
-version: 0.3.3
+version: 0.3.4
 scope: system
 description: "Pair this session with an OpenAI Codex CLI session you work with: the codex_send tool and /codex send it a part of the work (a plan step, a diff, a finding) to validate or as context, with codex queue, and Codex's answer comes back as the codex-outbox context; /codex install-skill installs Codex's chi-peer skill, which pairs"
 trust_level: reviewed
@@ -12,7 +12,7 @@ plugin:
   file: plugin.rb
   sha256: sha256:b03465566272891237ac1906980ff6956579a4703d3a42c414ce50a81de551f6
 scripts:
-  pair: sha256:0830dcb856debea0e4a2a0eb0da8a73b9e9ac2444da957d2928ec734280186a1
+  pair: sha256:a61c3d311ce3f3e5386e90f0f867f649a39763a5883877e731e43d84dd9c85aa
   chi-peer-SKILL.md: sha256:7c392ac04c115ea1e762ad562b5c4c44c3eca71558ba5d9dfeaeabdd533b6a82
 # The plugin needs Samagotchi::Plugin::Peer and chi.peer_source (chi 0.67.0).
 # An agreeing answer's closing wake (the skills say an OK wakes chi once)

data/lib/samagotchi/bundles/codex-peer/scripts/pair

@@ -93,10 +93,21 @@ MSG
   exit 1
 }
 
-# A JSON string: backslashes, quotes, tabs and newlines escaped.
+# A JSON string: backslashes and quotes escaped, newlines, tabs and
+# carriage returns as \n, \t, \r, any other control character as \u00XX.
 json() {
-  printf '%s' "$1" | sed -e 's/\\/\\\\/g' -e 's/"/\\"/g' -e 's/	/\\t/g' |
-    awk 'BEGIN { ORS = ""; printf "\"" } NR > 1 { print "\\n" } { print } END { printf "\"" }'
+  printf '%s' "$1" | awk '
+    BEGIN {
+      ORS = ""; printf "\""
+      for (i = 1; i < 32; i++) esc[sprintf("%c", i)] = sprintf("\\u%04x", i)
+      esc["\t"] = "\\t"; esc["\r"] = "\\r"; esc["\\"] = "\\\\"; esc["\""] = "\\\""
+    }
+    NR > 1 { print "\\n" }
+    {
+      n = length($0)
+      for (i = 1; i <= n; i++) { c = substr($0, i, 1); print ((c in esc) ? esc[c] : c) }
+    }
+    END { printf "\"" }'
 }
 
 # Attaches a pushed source, unless the session has one of that name already.

data/lib/samagotchi/bundles/github-pr/manifest.yml

@@ -1,6 +1,6 @@
 ---
 name: github-pr
-version: 0.5.0
+version: 0.5.1
 scope: system
 description: Attaches the branch's open GitHub pull request to a session as context (and any PR URL with chi context add or the web's "+ URL"); the agent gets a note when reviews, comments, checks or its state change; in the web, a path:line in an answer links to that line of the PR; the auto_attach setting can offer the PR with a card first, or attach nothing
 trust_level: reviewed
@@ -11,7 +11,7 @@ needs:
   hint: brew install gh, then gh auth login
 plugin:
   file: plugin.rb
-  sha256: sha256:b9e3d7a837ecaa2b0e53f3d62d2ccedd532f4d1b5d6faefd5adc9570cb3c4efe
+  sha256: sha256:cfadb7668528302b3631681e570899230b6878c80ccbc87dfb16c80d43dead7b
 scripts:
   pr_context.rb: sha256:a883d2780e89c68c0d7b6d5e0fcb22c273f17bb167e79064e0e99db6bd2ee6f0
 context_providers:

data/lib/samagotchi/bundles/github-pr/plugin.rb

@@ -649,12 +649,8 @@ class LineLinker
     out << head[pos..] << text[MAX_SCAN..].to_s
   end
 
-  # The URL for +path+'s lines +from+..+to+ (+to+ nil: one line), or nil:
-  # no PR has the file, or more than one does.
-  def url_for(path, from, to = nil) = line_for(path, from, to)&.fetch(:url)
-
-  # {url:, diff:, path:, line:, end_line:} for +path+'s lines (see #url_for),
-  # or nil.
+  # {url:, diff:, path:, line:, end_line:} for +path+'s lines +from+..+to+
+  # (+to+ nil: one line), or nil: no PR has the file, or more than one does.
   def line_for(path, from, to = nil)
     found = @prs.filter_map do |pr, data|
       file = resolve(data.files, path)

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

@@ -1,11 +1,11 @@
 ---
 name: samagotchi-system
-version: 0.121.0
+version: 0.122.0
 scope: system
 description: Default system memories — identity, self map, config modification protocol, memory guide and the delegated-session rules
 files:
   identity.md: sha256:29c2f7df9f6c5acbc5ec17000a4490741e55e426af15ca0d81c8706edd9bd027
   self_map.md: sha256:df3f8da539a9f5812f79e089c2c8b9894da6124a89654f292160046a6bb060da
   config_modification_protocol.md: sha256:ff4efccf2bdde453fc4e6741df8c18f78da78e353f6b1a5a64d0e7a631aea258
-  memory_guide.md: sha256:dfb3982cf281bf7920d018ea65b68b5755f86d8bd1e03bab9db42393a94ec7e0
+  memory_guide.md: sha256:3b9ff779ee962f1307d56937c826d5e581923114f3f39455b779ca618b363cd7
   delegated.md: sha256:a0d6ddcd4a8be06526d964898611775fd251cfd9d145a9d16afaccaa503597bd

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

@@ -86,6 +86,19 @@ Shape (plain Markdown, no frontmatter):
 - **Updating**: when a step turned out different, update the skill in the same turn: `edit` those steps in its file (`<scope dir>/skill_<name>.md`), or rewrite it with `memory_write`; keep the rest as it was, add a dated Changelog line. No confirmation needed.
 - **The `skills` bundle** (`chi bundle install skills`, optional) adds `/skill save [name] [--system]`, `/skill list`, `/skill show <name>`, `/skill diff <name> [N]`; it keeps older versions and shows a short diff line after each update.
 
+## Toolkit memories
+
+A memory named `toolkit_<name>` defines a kit named `<name>`. Its body is one fenced YAML block with `base`, `add`,
+`remove`, `groups` and a required `description`; never include `prompt:`. Only registered tools are declared, and
+the built-in names (`full`, `lean`, `child`, `review`) are reserved. Project kits take precedence over system kits;
+config and bundle kits take precedence over both. `/toolkit` lists a memory kit's source, and `--mute
+toolkit_<name>` skips it for the session.
+
+Write a kit when the user asks for one, when they use `/toolkit add` to choose the same tools for the same kind of
+work twice, or when `chi toolkit report` shows a kit repeatedly short of a tool for one kind of prompt. A tweak to a
+config or bundle kit is a new memory kit based on it (`base: staging`, for example), never a `config.yml` edit.
+Writing or updating a toolkit memory is free like writing a skill; say so in the reply.
+
 ## Memory Bundles — shareable packs
 
 Bundles are versioned directories/zips/tar.gz/git URLs with a `manifest.yml` and any of: memories (`*.md`), `hooks/*.rb` (bundle hooks, `docs/hooks.md`), `guardrails/*.yml` (rules, `docs/guardrails.md`), a `plugin.rb` (commands, tools, hooks, services; `docs/plugins.md`). They are shareable and installable.

data/lib/samagotchi/child_move.rb

@@ -6,7 +6,7 @@ require "time"
 require_relative "atomic_file"
 require_relative "session"
 require_relative "session_inbox"
-require_relative "worker_sidecar"
+require_relative "worker_link"
 require_relative "log"
 require_relative "tools/delegate_cursor"
 
@@ -93,13 +93,11 @@ module Samagotchi
     # installed (SessionManager.worker_command): it moves.
     # @return [String, nil]
     def unmovable(child_id, state_dir:)
-      owner = SessionManager.session_owner(child_id, state_dir: state_dir) or return nil
-      return "open in a chi REPL; close it there" if owner.tui?
+      link = WorkerLink.resolve(Session.session_dir(child_id, state_dir: state_dir), unlink: false)
+      return "open in a chi REPL; close it there" if link.owner&.tui?
+      return nil if !link.live? || link.features.include?(FEATURE)
 
-      sidecar = WorkerSidecar.live(Session.session_dir(child_id, state_dir: state_dir), unlink: false)
-      return nil if sidecar.nil? || sidecar.features.include?(FEATURE)
-
-      "older chi worker#{" #{sidecar.version}" if sidecar.version}; restart it"
+      "older chi worker#{" #{link.version}" if link.version}; restart it"
     end
 
     # Move +ids+ (direct children of +from+) to +to+: the intent, the

data/lib/samagotchi/children_status.rb

@@ -5,6 +5,7 @@ require_relative "session"
 require_relative "archive_store"
 require_relative "git_head"
 require_relative "reply_wait"
+require_relative "worker_link"
 require_relative "tools/delegate"
 require_relative "tools/delegate_cursor"
 
@@ -106,7 +107,7 @@ module Samagotchi
     # The keys of a children_of row that state_of and child read, for a
     # session counts loaded itself.
     def summary_of(session, state_dir:)
-      live = SessionManager.worker_live?(session.id, state_dir: state_dir)
+      live = WorkerLink.resolve(Session.session_dir(session.id, state_dir: state_dir), unlink: false).worker_owned?
       { live: live, busy: live && session.status == Session::STATUS_RUNNING, status: session.status,
         updated_at: session.updated_at, waiting: session.waiting_question(live: live)&.dig(:kind),
         preview: session.last_prompt.to_s }

data/lib/samagotchi/config.rb

@@ -249,6 +249,11 @@ module Samagotchi
       # delegate child's. toolkit.kits (the user's own) is read by Toolkit.kits.
       Entry.new(key: "toolkit.default",          yaml_path: %w[toolkit default],          type: :string, default: nil,              expose: %i[env config], lifecycle: :session_creation),
       Entry.new(key: "toolkit.child",            yaml_path: %w[toolkit child],            type: :string, default: nil,              expose: %i[env config], lifecycle: :session_creation),
+      # Toolkit suggestion (ToolkitSuggest): off, audit, or on; on currently behaves as audit and never changes a session.
+      Entry.new(key: "toolkit.suggest.mode",     yaml_path: %w[toolkit suggest mode],     type: :enum,   default: "off", expose: %i[config], enum_values: %w[off audit on], lifecycle: :worker_start),
+      Entry.new(key: "toolkit.suggest.threshold", yaml_path: %w[toolkit suggest threshold], type: :float, default: 0.5, expose: %i[config], lifecycle: :worker_start),
+      Entry.new(key: "toolkit.suggest.defer_turns", yaml_path: %w[toolkit suggest defer_turns], type: :integer, default: 3, expose: %i[config], lifecycle: :worker_start),
+      Entry.new(key: "toolkit.suggest.defer_tokens", yaml_path: %w[toolkit suggest defer_tokens], type: :integer, default: 5000, expose: %i[config], lifecycle: :worker_start),
 
       Entry.new(key: "default.max_tokens",       yaml_path: %w[default max_tokens],       type: :integer, default: nil,              expose: %i[env config cli], lifecycle: :next_matching_use),
       Entry.new(key: "max_tool_output_chars",    yaml_path: %w[max_tool_output_chars],    type: :integer, default: 10_000,          expose: %i[env config cli], lifecycle: :next_matching_use),