samagotchi 0.31.0 → 0.33.0

data/lib/samagotchi/guardrails/shell_lex.rb

@@ -33,15 +33,6 @@ module Samagotchi
         Lexer.new(text).tokens
       end
 
-      # lex's tokens, each with the range of +text+ it was read from
-      # appended ([:word, "x", specials, 0...1] / [:op, "&&", 2...4]), for a
-      # display that slices the original text. A heredoc body's range is
-      # the body and its terminator line. lex itself is unchanged by this.
-      def self.lex_with_spans(text)
-        lexer = Lexer.new(text)
-        lexer.tokens.zip(lexer.spans).map { |token, span| [*token, span] }
-      end
-
       # The token stream split at operators into word lists; ( and ) become
       # :open / :close markers.
       def self.simple_commands(tokens)

data/lib/samagotchi/guardrails/verdict.rb

@@ -5,9 +5,17 @@ module Samagotchi
     # The gate's verdict for one tool call. Voters (hooks now, rules later)
     # call #deny! or #ask!; the strictest vote wins (deny > ask > allow) and
     # a vote never relaxes it, so a deny is sticky. Of two equal votes the
-    # first one stays.
+    # first one stays, except that a protected rule's ask (PROTECTED_RULES)
+    # takes over an unprotected ask: its rule id is what a parent's answer
+    # and a stored approval are checked against, and the offered scopes
+    # narrow to both asks' common ones.
     class Verdict
       STRICTNESS = { allow: 0, ask: 1, deny: 2 }.freeze
+      # Rules that ask about chi's own config and hooks: the core
+      # ProtectedPaths asks and the guardrails bundle's shell rule; and a
+      # command source for attached context (it runs later, ungated). Only
+      # the user may allow them (ParentApprovals).
+      PROTECTED_RULES = %w[chi-config chi-hooks shell-touches-chi chi-context-cmd].freeze
       SCOPES = %w[once session repo rule].freeze
       DO_NOT_RETRY = "Do not retry it or reach the same result another way; ask the user how to proceed."
 
@@ -46,13 +54,18 @@ module Samagotchi
       # @param scopes [Array<String>, nil] which approval scopes the user may
       #   pick (default all of SCOPES)
       def ask!(reason, scopes: nil, rule: nil, source: nil, decided_by: "hook")
+        earlier = ask? ? @scopes : nil
         return self unless vote(:ask, reason, rule: rule, source: source, decided_by: decided_by)
 
         picked = Array(scopes).map(&:to_s) & SCOPES
-        @scopes = picked.empty? ? SCOPES : picked
+        picked = SCOPES if picked.empty?
+        picked &= earlier if earlier
+        @scopes = picked.empty? ? %w[once] : picked
         self
       end
 
+      def self.protected_rule?(rule) = PROTECTED_RULES.include?(rule.to_s)
+
       # A before_tool_call hook set the old event[:blocked] flag. Its model
       # text stays "blocked by guardrail: <reason>".
       def legacy_deny!(reason)
@@ -118,7 +131,7 @@ module Samagotchi
       end
 
       def vote(decision, reason, decided_by:, rule: nil, source: nil)
-        return false unless STRICTNESS.fetch(decision) > STRICTNESS.fetch(@decision)
+        return false unless STRICTNESS.fetch(decision) > STRICTNESS.fetch(@decision) || takes_over?(decision, rule)
 
         @decision = decision
         @reason = reason.to_s.strip
@@ -129,6 +142,11 @@ module Samagotchi
         @legacy = false
         true
       end
+
+      # A protected rule's ask over an unprotected one.
+      def takes_over?(decision, rule)
+        decision == :ask && ask? && Verdict.protected_rule?(rule) && !Verdict.protected_rule?(@rule)
+      end
     end
   end
 end

data/lib/samagotchi/log_line.rb

@@ -16,7 +16,7 @@ module Samagotchi
   # (debug dumps) are indented by four spaces and belong to the record above.
   module LogLine
     LEVELS = %w[DEBUG INFO WARN ERROR].freeze
-    TAGS = %w[turn http worker bridge web attached repl idle recap hooks plugins guardrails config memory model].freeze
+    TAGS = %w[turn http worker bridge web attached repl idle recap hooks plugins guardrails config memory model context].freeze
     INDENT = "    "
 
     Record = Struct.new(:ts, :level, :tag, :pid, :sid, :event, :fields, :payload, keyword_init: true)

data/lib/samagotchi/memory_bundle/builder.rb

@@ -5,6 +5,7 @@ require "fileutils"
 require "tmpdir"
 require_relative "manifest"
 require_relative "placeholder"
+require_relative "../context_providers"
 require_relative "../memory_paths"
 require_relative "../model_overlay"
 
@@ -152,6 +153,10 @@ module Samagotchi
         requires_chi = prov_data && prov_data[:requires_chi]
         needs = prov_data && prov_data[:needs]
 
+        # ── Scripts and context providers: the installed bundle's ──
+        scripts_to_copy = installed_scripts(prov, prov_data)
+        context_providers = prov_data ? ContextProviders.parse_list(prov_data[:context_providers]) : []
+
         # Determine trust_level for the built bundle
         build_trust_level = @trust_level
         if (build_trust_level.nil? || build_trust_level.empty?) && prov_data && prov_data[:trust_level]
@@ -185,6 +190,11 @@ module Samagotchi
 
           FileUtils.cp(plugin_src, File.join(staging, File.basename(plugin_src))) if plugin_src
 
+          unless scripts_to_copy.empty?
+            FileUtils.mkdir_p(File.join(staging, "scripts"))
+            scripts_to_copy.each_value { |src| FileUtils.cp(src, File.join(staging, "scripts", File.basename(src))) }
+          end
+
           Manifest.write(
             dir: staging,
             name: resolved_name,
@@ -196,7 +206,9 @@ module Samagotchi
             trust_level: build_trust_level,
             plugin: plugin_src && { file: File.basename(plugin_src), sha256: Digest::SHA256.hexdigest(File.binread(plugin_src)) },
             requires_chi: requires_chi,
-            needs: needs
+            needs: needs,
+            scripts: scripts_to_copy.transform_values { |src| "sha256:#{Digest::SHA256.hexdigest(File.binread(src))}" },
+            context_providers: context_providers
           )
 
           case format
@@ -255,6 +267,15 @@ module Samagotchi
 
       private
 
+      # The installed bundle's scripts its record lists, file name => path
+      # in its scripts/ (a missing one is left out); {} without a record.
+      def installed_scripts(prov, prov_data)
+        return {} unless prov && prov_data && prov_data[:scripts].is_a?(Hash)
+
+        prov_data[:scripts].keys.map(&:to_s).sort.to_h { |file| [file, File.join(prov.scripts_dir, file)] }
+                           .select { |_, path| File.file?(path) }
+      end
+
       # Without an allowlist, a memory another installed bundle owns (its
       # record lists it) isn't the user's to share: left out, one line
       # each. The bundle being built (same name) keeps its own.

data/lib/samagotchi/memory_bundle/installer.rb

@@ -302,6 +302,8 @@ module Samagotchi
         # ── Plugin: <file> into <bundle_dir>/plugin/ (docs/plugins.md) ────
         # Like the rules, the bundle's plugin replaces an earlier one.
         plugin_file_for_provenance = install_plugin(manifest, normalized_dir, provenance)
+        # ── Scripts: scripts/<file> into <bundle_dir>/scripts/ ────────────
+        scripts_for_provenance = install_scripts(manifest, normalized_dir, provenance)
         warn_hooks_requires_chi(manifest, all_hooks_in_bundle)
         warn_rules_requires_chi(manifest, incoming_rules)
 
@@ -417,7 +419,9 @@ module Samagotchi
             plugin_file: plugin_file_for_provenance,
             requires_chi: manifest.requires_chi,
             needs: manifest.needs,
-            conflicts: @conflicts.keys
+            conflicts: @conflicts.keys,
+            scripts_files: scripts_for_provenance,
+            context_providers: manifest.context_providers
           )
         end
 
@@ -615,6 +619,44 @@ module Samagotchi
         dest
       end
 
+      # The manifest's scripts, copied into <bundle_dir>/scripts/ (the
+      # folder replaced: a script the new version dropped goes). A declared
+      # sha256 that differs warns, as a plugin's does.
+      # @return [Hash{String => String}] file name => installed path
+      def install_scripts(manifest, source_dir, provenance)
+        scripts = manifest&.scripts || {}
+        scripts.each_key do |file|
+          next if File.file?(File.join(source_dir, "scripts", file))
+
+          raise InstallError, "the manifest names scripts/#{file}, which the bundle doesn't have"
+        end
+        return {} if @dry_run
+
+        unchanged = scripts.keys.select do |file|
+          dest = File.join(provenance.scripts_dir, file)
+          File.file?(dest) && FileUtils.identical?(File.join(source_dir, "scripts", file), dest)
+        end
+        FileUtils.rm_rf(provenance.scripts_dir)
+        return {} if scripts.empty?
+
+        FileUtils.mkdir_p(provenance.scripts_dir)
+        scripts.to_h do |file, declared|
+          dest = File.join(provenance.scripts_dir, file)
+          FileUtils.cp(File.join(source_dir, "scripts", file), dest)
+          @results["scripts/#{file}"] = if unchanged.include?(file) then { status: "skipped", reason: "already up to date" }
+                                        elsif @upgrade && provenance.read then { status: "updated" }
+                                        else { status: "installed" }
+                                        end
+          FileUtils.chmod(0o755, dest)
+          actual = Digest::SHA256.hexdigest(File.binread(dest))
+          expected = declared.to_s.delete_prefix("sha256:")
+          if @strict && !expected.empty? && actual != expected
+            @warnings << "Checksum mismatch for script #{file}: expected #{expected[0..7]}..., got #{actual[0..7]}..."
+          end
+          [file, dest]
+        end
+      end
+
       # A model overlay (<name>.<key>.md, docs/memory.md) loads only with
       # its base, under the matching model: it gets no index line (every
       # model would see it as a memory of its own). Its base is looked for

data/lib/samagotchi/memory_bundle/manifest.rb

@@ -3,6 +3,7 @@
 require "yaml"
 require "digest"
 require "fileutils"
+require_relative "../context_providers"
 
 module Samagotchi
   module MemoryBundle
@@ -25,6 +26,15 @@ module Samagotchi
     #       why: reads PRs     #   optional
     #       hint: brew install gh   # optional
     #     - jq                 #   short form: just the command
+    #   scripts:               # optional — files in scripts/ a context
+    #     pr_context.rb: sha256:…   #   provider's command runs (installed into
+    #                          #   the bundle's own dir, scripts/)
+    #   context_providers:     # optional — URL → attached context source
+    #     - match: '\Ahttps://…/pull/(\d+)'   # (ContextProviders)
+    #       name: 'pr-\1'
+    #       cmd: '{ruby} {bundle_dir}/scripts/pr_context.rb {url}'
+    #       why: GitHub PR      #   optional
+    #       every_seconds: 300  #   optional
     #   includes: [a, b]       # optional — a profile (meta bundle): the
     #                          #   shipped bundles it installs; its dir holds
     #                          #   only manifest.yml (MemoryBundle::Profile)
@@ -33,12 +43,15 @@ module Samagotchi
 
       # A plugin file is a plain .rb name in the bundle's top directory.
       PLUGIN_FILE = /\A[A-Za-z0-9_][A-Za-z0-9_.-]*\.rb\z/
+      # A script is a plain file name in the bundle's scripts/.
+      SCRIPT_FILE = /\A[A-Za-z0-9_][A-Za-z0-9_.-]*\z/
       # A need is a plain executable name: no path, no spaces.
       NEED_COMMAND = /\A[A-Za-z0-9][A-Za-z0-9._+-]*\z/
       # A bundle name, as `chi bundle install <name>` takes a shipped one.
       BUNDLE_NAME = /\A[A-Za-z0-9][A-Za-z0-9_-]*\z/
 
-      attr_reader :name, :version, :scope, :description, :files, :hooks, :trust_level, :plugin, :requires_chi, :needs, :includes
+      attr_reader :name, :version, :scope, :description, :files, :hooks, :trust_level, :plugin, :requires_chi, :needs, :includes,
+                  :scripts, :context_providers
 
       def initialize(path:)
         @path = path
@@ -53,6 +66,8 @@ module Samagotchi
         @plugin = parse_plugin(raw["plugin"])
         @requires_chi = parse_requires_chi(raw["requires_chi"])
         @needs = self.class.parse_needs(raw["needs"])
+        @scripts = parse_scripts(raw["scripts"])
+        @context_providers = parse_context_providers(raw["context_providers"])
         @includes = parse_includes(raw["includes"])
       end
 
@@ -109,7 +124,7 @@ module Samagotchi
 
       # Writes a fresh manifest.yml from computed checksums at `dir`.
       def self.write(dir:, name:, version:, files:, scope: nil, description: "", hooks: nil, trust_level: nil,
-                     plugin: nil, requires_chi: nil, needs: nil)
+                     plugin: nil, requires_chi: nil, needs: nil, scripts: {}, context_providers: [])
         FileUtils.mkdir_p(dir)
         manifest = {
           "name" => name,
@@ -134,6 +149,8 @@ module Samagotchi
         manifest["requires_chi"] = requires_chi.to_s if requires_chi && !requires_chi.to_s.empty?
         needs = parse_needs(needs)
         manifest["needs"] = needs.map { |n| n.transform_keys(&:to_s).compact } unless needs.empty?
+        manifest["scripts"] = scripts.transform_keys(&:to_s) unless scripts.empty?
+        manifest["context_providers"] = context_providers.map(&:to_h) unless context_providers.empty?
         File.write(File.join(dir, "manifest.yml"), YAML.dump(manifest))
       end
 
@@ -213,6 +230,27 @@ module Samagotchi
         { file: file, sha256: sha }
       end
 
+      # scripts: {file => sha256} → the same, "sha256:" prefixed; {} when absent.
+      def parse_scripts(raw)
+        return {} if raw.nil?
+        raise ValidationError, "scripts: must be a mapping of file name to sha256" unless raw.is_a?(Hash)
+
+        raw.to_h do |file, sha|
+          file = file.to_s
+          raise ValidationError, "scripts: #{file.inspect} isn't a plain file name in scripts/" unless file.match?(SCRIPT_FILE)
+
+          sha = sha.to_s.strip
+          [file, sha.empty? || sha.start_with?("sha256:") ? sha : "sha256:#{sha}"]
+        end
+      end
+
+      # @return [Array<ContextProviders::Provider>]
+      def parse_context_providers(raw)
+        ContextProviders.parse_list(raw)
+      rescue ContextProviders::Invalid => e
+        raise ValidationError, e.message
+      end
+
       # includes: → the names in order, duplicates dropped; [] when absent.
       # A meta ships nothing of its own, so files, hooks or a plugin next
       # to it is a ValidationError.
@@ -226,8 +264,8 @@ module Samagotchi
 
           name
         end.uniq
-        if !names.empty? && (!@files.empty? || !@hooks.empty? || @plugin)
-          raise ValidationError, "a bundle with includes: holds only its includes (no files, hooks or plugin)"
+        if !names.empty? && (!@files.empty? || !@hooks.empty? || @plugin || !@scripts.empty?)
+          raise ValidationError, "a bundle with includes: holds only its includes (no files, hooks, plugin or scripts)"
         end
 
         names

data/lib/samagotchi/memory_bundle/provenance.rb

@@ -39,6 +39,12 @@ module Samagotchi
         File.join(@bundle_dir, "plugin")
       end
 
+      # The installed scripts' dir (scripts/<file>): what a context
+      # provider's command finds as {bundle_dir}/scripts.
+      def scripts_dir
+        File.join(@bundle_dir, "scripts")
+      end
+
       # The plugin file as installed, or nil when the bundle has none.
       def plugin_path(data = read)
         file = data && data[:plugin].is_a?(Hash) ? data[:plugin][:file].to_s : ""
@@ -129,8 +135,12 @@ module Samagotchi
       #   edits that conflict with it; their entries get conflict: true
       # @param includes [Array<String>, nil] a profile's recorded members
       #   (MemoryBundle::Profile); nil for a plain bundle
+      # @param scripts_files [Hash] file name => installed script; the
+      #   sha256 of each is recorded (ContextFetch checks it before a run)
+      # @param context_providers [Array<ContextProviders::Provider>]
       def write(files:, scope:, version:, source_path:, hooks: {}, trust_level: nil, source_commit: nil, hooks_files: {},
-                guardrails_files: {}, plugin_file: nil, requires_chi: nil, needs: nil, conflicts: [], includes: nil)
+                guardrails_files: {}, plugin_file: nil, requires_chi: nil, needs: nil, conflicts: [], includes: nil,
+                scripts_files: {}, context_providers: [])
         FileUtils.mkdir_p(@bundle_dir)
         bases_dir = File.join(@bundle_dir, "bases")
         FileUtils.mkdir_p(bases_dir)
@@ -241,6 +251,12 @@ module Samagotchi
         manifest_data["requires_chi"] = requires_chi.to_s if requires_chi && !requires_chi.to_s.empty?
         manifest_data["needs"] = needs.map { |n| n.transform_keys(&:to_s).compact } if needs.is_a?(Array) && !needs.empty?
         manifest_data["includes"] = includes.map(&:to_s) if includes.is_a?(Array)
+        unless scripts_files.empty?
+          manifest_data["scripts"] = scripts_files.sort.to_h do |file, path|
+            [file.to_s, { "sha256" => "sha256:#{Digest::SHA256.hexdigest(File.binread(path.to_s))}" }]
+          end
+        end
+        manifest_data["context_providers"] = context_providers.map(&:to_h) unless context_providers.empty?
 
         write_manifest(manifest_data)
       end

data/lib/samagotchi/plugin/attached_context.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+require "time"
+require_relative "../context_sources"
+require_relative "../context_providers"
+require_relative "../session"
+
+module Samagotchi
+  module Plugin
+    # ctx.context (docs/plugins.md, Attached context): context a plugin
+    # attaches to its session (ContextSources), through an installed
+    # bundle's provider (a URL) or as its own command. In-process, like any
+    # plugin code: not gated as `chi context add --cmd` through execute is.
+    # The session's worker runs and absorbs it (ContextPoller).
+    class AttachedContext
+      # An attach that couldn't be done; the message says why.
+      class Error < StandardError; end
+
+      # @param host [Host] session_id and state_dir
+      def initialize(host, bundle:)
+        @host = host
+        @bundle = bundle
+      end
+
+      # Attach a source to this session. +url+: through an installed
+      # bundle's provider (+name+ and +why+ replace the provider's); else
+      # +name+ and +cmd+ (+hint+, +every_seconds+). A source of that name
+      # already attached stays as it is. One the user removed from the
+      # session (its name, or its URL) isn't attached again (#declined?)
+      # until the user adds it again.
+      # @return [String, nil] the source's name; nil when declined
+      # @raise [Error]
+      def attach(url: nil, name: nil, cmd: nil, why: nil, hint: nil, every_seconds: nil)
+        own = location or raise Error, "this session has no id yet"
+        source = url ? from_url(url, name: name, why: why) : from_cmd(name: name, cmd: cmd, why: why, hint: hint, every_seconds: every_seconds)
+        return nil if own.declined?(source.name) || (url && own.declined_hints.include?(source.hint))
+        return source.name if own.source(source.name)
+
+        own.add(source.with(scope: own.scope))
+        source.name
+      rescue ContextSources::Invalid, ContextProviders::Invalid => e
+        raise Error, e.message
+      end
+
+      # Whether the user removed +name+ from this session (so #attach skips it).
+      def declined?(name)
+        own = location
+        own ? own.declined?(name) : false
+      rescue ContextSources::Invalid
+        false
+      end
+
+      # This session's sources (its own, then its project's).
+      # @return [Array<Hash>] {name:, scope:, why:, hint:, fetched_at:, error:, provider:}
+      def list
+        id = @host.session_id.call
+        return [] unless id
+
+        session = Session.load(id, state_dir: state_dir)
+        ContextSources.attached(id, project_root: session.project_root, state_dir: state_dir).map do |attached|
+          snapshot = attached.snapshot
+          { name: attached.name, scope: attached.location.scope, why: attached.source.why,
+            hint: snapshot.hint || attached.source.hint, fetched_at: snapshot.fetched_at, error: snapshot.error,
+            provider: attached.source.provider }
+        end
+      end
+
+      private
+
+      def state_dir = @host.state_dir&.call || Session.default_state_dir
+
+      def location
+        id = @host.session_id.call
+        id && ContextSources.session_location(id, state_dir: state_dir)
+      end
+
+      def from_url(url, name:, why:)
+        resolved = ContextProviders.resolve(url) or raise Error, "no installed bundle resolves #{url}"
+        source(name: name ? ContextSources.check_name!(name) : resolved.name, cmd: resolved.cmd, why: why || resolved.why,
+               hint: resolved.hint, every_seconds: resolved.every_seconds, provider: resolved.bundle)
+      end
+
+      def from_cmd(name:, cmd:, why:, hint:, every_seconds:)
+        raise Error, "give url: or cmd: (with name:)" if cmd.to_s.strip.empty?
+
+        source(name: ContextSources.check_name!(name), cmd: cmd.to_s, why: why, hint: hint,
+               every_seconds: ContextSources.check_every!(every_seconds), provider: nil)
+      end
+
+      def source(name:, cmd:, why:, hint:, every_seconds:, provider:)
+        ContextSources::Source.new(
+          name: name, cmd: cmd, every_seconds: every_seconds,
+          why: ContextSources.one_line(why, ContextSources::LINE_MAX_CHARS),
+          hint: ContextSources.one_line(hint, ContextSources::LINE_MAX_CHARS), scope: nil,
+          added_by: "plugin:#{@bundle}", created_at: Time.now.utc.iso8601, provider: provider
+        )
+      end
+    end
+  end
+end

data/lib/samagotchi/plugin/context.rb

@@ -7,6 +7,7 @@ require_relative "../guardrails/context"
 require_relative "../idle_client"
 require_relative "side_question"
 require_relative "sessions"
+require_relative "attached_context"
 
 module Samagotchi
   module Plugin
@@ -98,6 +99,20 @@ module Samagotchi
       #   current_model_only names it
       def model_key = @host.model_key&.call
 
+      # Whether the session is a `chi scratch` one (deleted when it ends).
+      def scratch? = !!@host.scratch&.call
+
+      # Whether the session is a delegate child (Session#delegate?): a task
+      # another session handed over, not the user's own.
+      def delegate?
+        id = session_id
+        return false unless id
+
+        Session.load(id, state_dir: @host.state_dir&.call || Session.default_state_dir).delegate?
+      rescue ArgumentError
+        false
+      end
+
       # @return [String] the session's working directory
       def cwd = @host.cwd.call || Dir.pwd
 
@@ -210,6 +225,13 @@ module Samagotchi
         @sessions ||= Sessions.new(@host)
       end
 
+      # This session's attached context: attach a URL or a command, list
+      # (AttachedContext).
+      # @return [AttachedContext]
+      def context
+        @context ||= AttachedContext.new(@host, bundle: @bundle)
+      end
+
       # A single-select question through the question flow. Inside a
       # stream hook's handler (generation_progress) it asks no one (nil).
       # @return [Hash, nil] {selected:, freeform:, selected_indices:}, or nil

data/lib/samagotchi/plugin/sessions.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require_relative "../client_id"
 require_relative "../session"
 require_relative "../bridge_client"
 require_relative "../bridge/turn_accumulator"
@@ -62,7 +63,7 @@ module Samagotchi
 
         state_dir = self.state_dir
         sid = resolve(id, state_dir)
-        delivered = SessionManager.deliver_turn(sid, prompt: text.to_s, client_id: "plugin", state_dir: state_dir)
+        delivered = SessionManager.deliver_turn(sid, prompt: text.to_s, client_id: ClientId::PLUGIN, state_dir: state_dir)
         case delivered[:status]
         when :accepted then sid
         when :refused then raise Error, "session #{sid[0, 8]} refused the message (#{delivered.dig(:ack, "error")})"

data/lib/samagotchi/process_group.rb

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+module Samagotchi
+  # A command run in a process group of its own, so a stop reaches what it
+  # started too: TERM the group, a grace, then KILL it. Execute, TaskRuntime
+  # and ContextFetch spawn and stop their commands here, each with its own
+  # grace and its own "has it stopped?" check (the leader gone, the pipes
+  # closed, the pid reaped).
+  #
+  # The mcp bundle's client keeps its own copy (stdin closed first, then
+  # the group): a bundle may use chi's classes only from the chi its
+  # requires_chi names, and no released chi has this one yet.
+  module ProcessGroup
+    # A group that is gone, or one that isn't ours to signal.
+    QUIET = [Errno::ESRCH, Errno::EPERM].freeze
+    READ_CHUNK_BYTES = 65_536
+
+    module_function
+
+    # Process.spawn in a new process group, whose id is the pid.
+    # @return [Integer] the pid
+    def spawn(env, *argv, **) = Process.spawn(env, *argv, pgroup: true, **)
+
+    # Sends +sig+ to every process in the group +pgid+.
+    # @param leader [Boolean] when the group can't be signalled, signal the
+    #   process +pgid+ alone (a leader that left its group)
+    # @param quiet [Array<Class>] the errors that mean there is nothing to
+    #   signal; any other is raised
+    # @return [Boolean] whether a signal was sent
+    def signal(pgid, sig, leader: false, quiet: QUIET)
+      check!(pgid)
+      Process.kill(sig, -pgid)
+      true
+    rescue *quiet
+      return false unless leader
+
+      begin
+        Process.kill(sig, pgid)
+        true
+      rescue *quiet
+        false
+      end
+    end
+
+    # A pid chi may signal or ask about: an Integer above 1. kill(0) and
+    # kill(-1) reach chi's own group and every process of the user, so a
+    # pid that isn't one (a broken or edited record) never gets that far.
+    def signalable?(pid) = pid.is_a?(Integer) && pid > 1
+
+    # @raise [ArgumentError] unless #signalable?
+    def check!(pid)
+      raise ArgumentError, "not a process group chi may signal: #{pid.inspect}" unless signalable?(pid)
+    end
+
+    # Whether +pid+ runs and leads its own group, as #spawn's process does
+    # (not, then, a reused pid in some other group).
+    def leader?(pid)
+      signalable?(pid) && Process.getpgid(pid) == pid
+    rescue Errno::ESRCH, Errno::EPERM
+      false
+    end
+
+    # Whether +pid+ is still running (or a zombie not reaped yet).
+    # @raise [ArgumentError] unless #signalable?
+    def alive?(pid)
+      check!(pid)
+      Process.kill(0, pid)
+      true
+    rescue Errno::ESRCH
+      false
+    rescue Errno::EPERM
+      true
+    end
+
+    # TERMs the group, waits up to +grace+ for +stopped+, then KILLs it.
+    # @param stopped [#call] true once it has stopped (default: the leader
+    #   is gone)
+    # @param wait [#call] (seconds) between two checks (default: a sleep)
+    # @param signal_options [Hash] for #signal (leader:, quiet:)
+    # @return [Boolean] true when it stopped within the grace (no KILL sent)
+    # @raise [ArgumentError] unless #signalable?
+    def stop(pgid, grace:, poll:, stopped: -> { !alive?(pgid) }, wait: ->(seconds) { sleep(seconds) }, **signal_options)
+      check!(pgid)
+      signal(pgid, "TERM", **signal_options)
+      deadline = monotonic + grace
+      until (done = stopped.call) || monotonic >= deadline
+        wait.call(poll)
+      end
+      return true if done
+
+      signal(pgid, "KILL", **signal_options)
+      false
+    end
+
+    def monotonic = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+    # Reads a pipe in chunks on a thread of its own, so the output read so
+    # far survives the pipe being closed under it (or the thread killed).
+    class PipeReader
+      # @param cap [Integer, nil] the most bytes it keeps
+      # @param keep [:head, :tail] past the cap: :head stops reading (and
+      #   #over? is true), :tail keeps the last +cap+ bytes
+      def initialize(io, cap: nil, keep: :head, chunk: READ_CHUNK_BYTES)
+        @io = io
+        @buffer = String.new(encoding: Encoding::BINARY)
+        @over = false
+        @thread = Thread.new do
+          Thread.current.report_on_exception = false
+          loop { break unless take(io.readpartial(chunk), cap, keep) }
+        rescue IOError # EOFError is one
+          nil
+        end
+      end
+
+      def done? = !@thread.alive?
+
+      # Whether a :head reader stopped at its cap.
+      def over? = @over
+
+      # @return [Thread, nil] the thread when it ended within +seconds+
+      def wait(seconds) = @thread.join(seconds)
+
+      def kill = @thread.kill
+
+      # Closes the pipe once the thread had +poll+ to end by itself (a
+      # reader still blocked gets IOError), then ends the thread, killing it
+      # after +grace+. The text is safe to read afterwards.
+      def finish(poll:, grace:)
+        @thread.join(poll) unless done?
+        close_quietly
+        @thread.kill unless @thread.join(grace)
+      end
+
+      # What it read, in +encoding+ (default: the pipe's).
+      def text(encoding = @io.external_encoding || Encoding.default_external)
+        @buffer.dup.force_encoding(encoding)
+      end
+
+      private
+
+      # @return [Boolean] whether to read on
+      def take(chunk, cap, keep)
+        if cap && keep == :head && @buffer.bytesize + chunk.bytesize > cap
+          @over = true
+          return false
+        end
+
+        @buffer << chunk
+        @buffer = @buffer.byteslice(-cap, cap) if cap && keep == :tail && @buffer.bytesize > cap
+        true
+      end
+
+      def close_quietly
+        @io.close unless @io.closed?
+      rescue IOError
+        nil
+      end
+    end
+  end
+end