samagotchi 0.59.0 → 0.61.0

data/lib/samagotchi/plugin/context.rb

@@ -19,7 +19,9 @@ module Samagotchi
     # (chat messages, timeout:, max_tokens:, cancel_controller:) and returns
     # the answer text.
     # +messages_partial+ says whether +messages+ leaves out a running turn;
-    # +model_name+ (the session's resolved model ref, live after /model) and
+    # +prompt_files+ returns the files whose text the built system prompt
+    # holds (SystemPrompt#prompt_files, [] before a build); +model_name+
+    # (the session's resolved model ref, live after /model) and
     # +state_dir+ are what ctx.sessions forks with, and +setup+ (the
     # session's own SessionSetup), which a fork copies; +model_key+ is the
     # model's memory overlay key (ctx.model, ctx.model_key).
@@ -28,8 +30,8 @@ module Samagotchi
     # +frontend+ returns the Engine's interface (:repl, :worker,
     # :non_interactive), which ctx.frontend names for plugins.
     Host = Struct.new(:session_id, :cwd, :messages, :messages_partial, :notify, :ask_user, :cancelled, :card,
-                      :ask_model, :model_name, :model_key, :state_dir, :scratch, :setup, :steer, :stop_turn, :stop_generation,
-                      :frontend, keyword_init: true)
+                      :ask_model, :model_name, :model_key, :state_dir, :scratch, :setup, :prompt_files,
+                      :steer, :stop_turn, :stop_generation, :frontend, keyword_init: true)
 
     # ctx.ask_model failed: the model couldn't be reached, timed out, or
     # sent nothing usable. The message says why, for the user.
@@ -159,6 +161,17 @@ module Samagotchi
       # a plugin can say what its answer is about.
       def messages_partial? = !!@host.messages_partial&.call
 
+      # The files whose text the session's system prompt holds now, as
+      # absolute paths in prompt order (SystemPrompt#prompt_files): the
+      # AGENTS.md chain (the work tree top down to the cwd), then the
+      # appended files (append_system_prompt:, --append-system-prompt).
+      # [] before the first build and after one that drops them (a model
+      # or tools change). A Host without the member (a spec's) reads [].
+      # @return [Array<String>] frozen
+      def prompt_files
+        Array(@host.prompt_files&.call || []).freeze
+      end
+
       # Run +block+ as this plugin's handler for +event+: until it returns,
       # the helpers called on this thread act as the event's own. Nests (a
       # fire inside a handler gets its own event; the outer one is back

data/lib/samagotchi/prompt_files.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+require_relative "memory_paths"
+
+module Samagotchi
+  # The files whose text goes into the system prompt as they are
+  # (SystemPrompt): which AGENTS.md files a cwd loads, and how a file
+  # becomes a prompt section.
+  module PromptFiles
+    AGENTS_FILE = "AGENTS.md"
+
+    AGENTS_HEADER = "Project specific description:"
+
+    # A file's text as the prompt carries it: +path+ absolute, +text+ the
+    # section with its header.
+    Section = Data.define(:path, :text)
+
+    module_function
+
+    # The AGENTS.md files a session in +cwd+ loads, as absolute paths,
+    # outermost first: inside a git work tree every one from its top (a
+    # linked worktree's own checkout) down to the cwd; outside a repository
+    # only the cwd's ([] with none).
+    # @param cwd [String] where the prompt is built (Dir.pwd, not the
+    #   session's working directory: /tmp vs /private/tmp would change the
+    #   prompt bytes)
+    # @return [Array<String>]
+    def agents_paths(cwd)
+      chain_dirs(cwd).map { |dir| File.join(dir, AGENTS_FILE) }.select { |path| File.file?(path) }
+    end
+
+    # The sections of the AGENTS.md chain (#agents_paths) with text: the
+    # first keeps the plain header (a one-file session's prompt is as it
+    # always was), each further one names its directory relative to the
+    # work tree top ("Project specific description for pkg/:").
+    # @return [Array<Section>]
+    def agents_sections(cwd)
+      top = MemoryPaths.work_tree_root(cwd)
+      sections = []
+      agents_paths(cwd).each do |path|
+        dir = File.dirname(path)
+        header = sections.empty? ? AGENTS_HEADER : "Project specific description for #{relative_dir(dir, top) || dir}/:"
+        text = section(path, header)
+        sections << Section.new(path: path, text: text) if text
+      end
+      sections
+    end
+
+    # The directories whose AGENTS.md a session in +cwd+ reads, outermost first.
+    def chain_dirs(cwd)
+      cwd = File.expand_path(cwd)
+      top = MemoryPaths.work_tree_root(cwd)
+      return [cwd] unless top
+
+      rel = relative_dir(cwd, top)
+      return [top] if rel == "."
+      # A cwd the walk up didn't reach from (not expected): only its own and the top's.
+      return [top, cwd] if rel.nil?
+
+      parts = rel.split("/")
+      [top] + parts.each_index.map { |i| File.join(top, *parts[0..i]) }
+    end
+
+    # +dir+ relative to +top+ ("." for the top itself), nil when it isn't under it.
+    def relative_dir(dir, top)
+      return "." if dir == top
+
+      prefix = top.end_with?("/") ? top : "#{top}/"
+      dir.start_with?(prefix) ? dir.delete_prefix(prefix) : nil
+    end
+
+    # How a prompt file is named in the prompt and /stats: relative to the
+    # work tree +top+ when inside it, else with ~ for the home directory.
+    # @return [String]
+    def display_path(path, top:)
+      rel = top && relative_dir(path, top)
+      return rel if rel && rel != "."
+
+      home = Dir.home
+      path.start_with?("#{home}/") ? "~#{path.delete_prefix(home)}" : path
+    rescue ArgumentError
+      path
+    end
+
+    # A chi --append-system-prompt value: [absolute path, nil], or
+    # [absolute path, the reason it can't be used].
+    # @param cwd [String] the shell's cwd the value is relative to
+    # @return [Array(String, String)]
+    def check_cli_file(value, cwd: Dir.pwd)
+      begin
+        path = File.expand_path(value.to_s, cwd)
+      rescue ArgumentError
+        # A quoted "~nosuchuser/x" reaches chi unexpanded.
+        return [value.to_s, "no such user"]
+      end
+      reason = if !File.exist?(path) then "no such file"
+               elsif !File.file?(path) then "not a file"
+               elsif !File.readable?(path) then "can't be read"
+               end
+      [path, reason]
+    end
+
+    # Text this long goes into every request: chi warns once, at start.
+    LARGE_CHARS = 32_000
+
+    # The number of chars of +path+ when above LARGE_CHARS, else nil.
+    # @return [Integer, nil]
+    def large_size(path)
+      chars = File.read(path, encoding: "UTF-8").length
+      chars > LARGE_CHARS ? chars : nil
+    rescue StandardError
+      nil
+    end
+
+    # +path+'s text under +header+ ("<header>\n<text>", stripped); nil when
+    # the file is empty or can't be read.
+    # @return [String, nil]
+    def section(path, header)
+      content = File.read(path, encoding: "UTF-8").strip
+      return nil if content.empty?
+
+      "#{header}\n#{content}"
+    rescue StandardError
+      nil
+    end
+  end
+end

data/lib/samagotchi/ref.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module Samagotchi
+  # One thing a click on a ref can do besides the kind's own (the web keeps
+  # those per kind, refs.js REF_ACTIONS): open +url+ in a new tab, shown as
+  # +label+ in the ref's menu. A plugin names it ("PR diff", "Open in Jira").
+  # The URL is http(s) only, checked here and again in the page
+  # (refs.js httpUrl): the page opens it as is, so a javascript:, data: or
+  # editor URL never gets there.
+  RefAction = Data.define(:id, :label, :url) do
+    # @raise [ArgumentError] an empty id or label, one over its cap
+    #   (MAX_ID, MAX_LABEL), or a URL that isn't an http(s) one with a host,
+    #   at most MAX_URL characters
+    def initialize(id:, label:, url:)
+      id = id.to_s.strip
+      label = label.to_s.strip
+      url = url.to_s.strip
+      raise ArgumentError, "a ref action needs an id" if id.empty?
+      raise ArgumentError, "a ref action needs a label" if label.empty?
+      raise ArgumentError, "a ref action's id is at most #{RefAction::MAX_ID} characters" if id.length > RefAction::MAX_ID
+      raise ArgumentError, "a ref action's label is at most #{RefAction::MAX_LABEL} characters" if label.length > RefAction::MAX_LABEL
+      raise ArgumentError, "a ref action's url must be http(s) with a host, at most #{RefAction::MAX_URL} characters" unless RefAction.http_url?(url)
+
+      super
+    end
+  end
+
+  class RefAction
+    MAX_URL = 2_000
+    MAX_ID = 64
+    MAX_LABEL = 100
+
+    # @return [Boolean] +url+ is an http or https URL with a host and no
+    #   userinfo (a "https://github.com@evil.example/" shows one host and
+    #   opens another, and a token in it would be copied around)
+    def self.http_url?(url)
+      return false if url.length > MAX_URL
+
+      uri = URI.parse(url)
+      uri.is_a?(URI::HTTP) && !uri.host.to_s.empty? && uri.userinfo.nil?
+    rescue URI::InvalidURIError
+      false
+    end
+
+    # @param value [RefAction, Hash] a plugin's {id:, label:, url:} (String
+    #   or Symbol keys)
+    # @raise [ArgumentError] anything else, or an invalid action
+    def self.from(value)
+      return value if value.is_a?(RefAction)
+      raise ArgumentError, "a ref action is a Hash {id:, label:, url:}" unless value.is_a?(Hash)
+
+      value = value.transform_keys(&:to_sym)
+      new(id: value[:id], label: value[:label], url: value[:url])
+    end
+  end
+
+  # A ref as data: a kind, a target, an optional label and the plugins'
+  # extra actions (RefAction), for a UI to trace it. The kind's own actions
+  # are the UI's (a file ref keeps the editor, show in turn and copy), so
+  # +actions+ only adds to them.
+  # - +kind+ "file": +target+ {path:, line:, end_line:}, the lines only when
+  #   positive, the end only past the start (FileRef's shape).
+  # - Any other kind ("issue", "commit", …): +target+ {id:}. The page shows
+  #   its +label+ (or the text it matched) and runs its first action.
+  # +to_h+ is the shape the page reads (refs.js bindRef). FileRef stays the
+  # rows' own ref; this is the one a plugin gives.
+  Ref = Data.define(:kind, :target, :label, :actions) do
+    # @raise [ArgumentError] a kind that isn't a short lowercase word, a
+    #   target without its kind's key, a non-list of actions, a bad action,
+    #   or a value over its cap (MAX_LABEL, MAX_ACTIONS, MAX_ID, MAX_PATH)
+    def initialize(kind:, target:, label: nil, actions: [])
+      kind = kind.to_s
+      raise ArgumentError, "a ref's kind is a short lowercase word (#{kind.inspect})" unless Ref::KIND.match?(kind)
+      raise ArgumentError, "a ref's actions are a list" unless actions.nil? || actions.is_a?(Array)
+      raise ArgumentError, "a ref has at most #{Ref::MAX_ACTIONS} actions" if Array(actions).length > Ref::MAX_ACTIONS
+
+      label = label.to_s.strip
+      raise ArgumentError, "a ref's label is at most #{Ref::MAX_LABEL} characters" if label.length > Ref::MAX_LABEL
+
+      super(kind: kind, target: Ref.target_for(kind, target), label: label.empty? ? nil : label,
+            actions: Array(actions).map { |action| RefAction.from(action) }.freeze)
+    end
+
+    # @return [Hash] {kind:, target:, label:, actions: [{id:, label:, url:}]},
+    #   no label when there is none
+    def to_h = { kind: kind, target: target, label: label, actions: actions.map(&:to_h) }.compact
+  end
+
+  class Ref
+    KIND = /\A[a-z][a-z0-9_-]{0,31}\z/
+    # FileRef::KIND, not required here (it loads the file tools).
+    FILE = "file"
+    # Caps, so a plugin can't bloat session.json or the page.
+    MAX_LABEL = 200
+    MAX_ACTIONS = 8
+    MAX_ID = 200
+    MAX_PATH = 4_096
+
+    # A plugin's {kind:, target:, label:, actions:} (String or Symbol keys).
+    # @raise [ArgumentError] as +new+
+    def self.from(value)
+      raise ArgumentError, "a ref is a Hash {kind:, target:, label:, actions:}" unless value.is_a?(Hash)
+
+      value = value.transform_keys(&:to_sym)
+      new(kind: value[:kind], target: value[:target], label: value[:label], actions: value[:actions] || [])
+    end
+
+    # +kind+'s target from +raw+: a file's path and lines, any other kind's id.
+    # @raise [ArgumentError] not a Hash, or without the kind's key
+    def self.target_for(kind, raw)
+      raise ArgumentError, "a ref's target is a Hash" unless raw.is_a?(Hash)
+
+      raw = raw.transform_keys(&:to_sym)
+      kind == FILE ? file_target(raw) : { id: required(raw[:id], :id, MAX_ID) }.freeze
+    end
+
+    def self.file_target(raw)
+      line = positive(raw[:line])
+      end_line = line && positive(raw[:end_line])
+      { path: required(raw[:path], :path, MAX_PATH), line: line, end_line: end_line && end_line > line ? end_line : nil }.compact.freeze
+    end
+    private_class_method :file_target
+
+    def self.required(value, key, max)
+      value = value.to_s.strip
+      raise ArgumentError, "a ref's target needs #{key}" if value.empty?
+      raise ArgumentError, "a ref's target #{key} is at most #{max} characters" if value.length > max
+
+      value
+    end
+    private_class_method :required
+
+    def self.positive(value)
+      number = Integer(value.to_s.strip, exception: false)
+      number&.positive? ? number : nil
+    end
+    private_class_method :positive
+  end
+end

data/lib/samagotchi/reply_wait.rb

@@ -106,10 +106,14 @@ module Samagotchi
 
         if session.status == Session::STATUS_RUNNING
           seen_running = true
-        elsif seen_running || turn_ended_since?(session, baseline)
+        elsif (seen_running && !baseline&.key?(:last_turn)) || turn_ended_since?(session, baseline)
           # It ran and is idle again with no new reply: canceled, failed or
           # empty. Before it was ever seen running, idle means a
-          # file-delivered message its worker has not picked up yet.
+          # file-delivered message its worker has not picked up yet. With
+          # the baseline's last_turn only a turn that ended since counts:
+          # a session left running by a worker that died goes idle when the
+          # next worker settles that turn (TurnCheckpoint.settle), before
+          # the sent message's turn runs.
           # The worker writes the reply before its idle save, so the read
           # above has it; one more look costs nothing should that change.
           return reply_past(id, state_dir: state_dir, cursor: cursor)&.tap { |r| r.session = session } ||

data/lib/samagotchi/session.rb

@@ -6,6 +6,7 @@ require "securerandom"
 require "time"
 require_relative "atomic_file"
 require_relative "context_note"
+require_relative "interrupted_turn"
 require_relative "last_turn"
 require_relative "llm_context_override"
 require_relative "session_setup"
@@ -53,6 +54,15 @@ module Samagotchi
     # from it (--mute): the worker rebuilds the same prompt on a respawn.
     # Names as given; the engine normalizes them.
     attr_accessor :preloaded_memory_names, :muted_memory_names
+    # The files chi --append-system-prompt put into the session's system
+    # prompt (absolute paths; config.yml's append_system_prompt: entries
+    # aren't stored): kept on respawns, copied by a fork and a continue
+    # (SessionSetup).
+    attr_reader :appended_prompt_files
+
+    def appended_prompt_files=(paths)
+      @appended_prompt_files = Array(paths).map(&:to_s).reject(&:empty?).uniq
+    end
     # The model notes the session's system prompt carried at its last build
     # (Array<PromptNote>: name, scope, chars, digest; ModelNotes), set by the
     # Engine at each build (a start, a resume's or a woken worker's first
@@ -98,6 +108,26 @@ module Samagotchi
     def last_turn=(value)
       @last_turn = LastTurn.from_file(value)
     end
+
+    # The mark of a turn a worker checkpointed and never finished
+    # (InterruptedTurn), as loaded; the next worker settles it and sets it
+    # to nil. While a turn runs, #turn_checkpoint's marker is saved instead.
+    attr_reader :interrupted_turn
+
+    # @param value [InterruptedTurn, Hash, nil]
+    def interrupted_turn=(value)
+      @interrupted_turn = InterruptedTurn.from_file(value)
+    end
+
+    # The running turn's checkpoint (TurnCheckpoint): {messages:, marker:}
+    # (marker an InterruptedTurn). While +status+ is running, every save
+    # writes these messages and the marker instead of #messages and
+    # #interrupted_turn, so a save in the middle of the turn (a question
+    # asked, the checkpoint's own) keeps the turn so far on disk; #messages
+    # itself is never touched. The turn's end sets status idle before it
+    # saves, so that save writes the real messages, without a marker. Not
+    # saved; the worker clears it after each turn.
+    attr_accessor :turn_checkpoint
     # The session's own llm_context values (LLMContextOverride: strategy,
     # apply rule, budget), before the model's; nil when it has none.
     # Saved, so a --resume and a respawned worker keep them; a plugin's
@@ -182,7 +212,8 @@ module Samagotchi
                    used_memory_names: [], project_root: nil,
                    preloaded_memory_names: [], muted_memory_names: [], parent_id: nil, scratch: false,
                    last_turn: nil, model_typed: nil, delegate: false, llm_context: nil, prompt_notes: [],
-                   continues: nil, thinking: nil, reasoning_history: nil)
+                   continues: nil, thinking: nil, reasoning_history: nil, appended_prompt_files: [],
+                   interrupted_turn: nil)
       @id = id
       @metadata_version = metadata_version
       @mode = mode
@@ -210,6 +241,9 @@ module Samagotchi
       self.llm_context = llm_context
       self.thinking = thinking
       self.reasoning_history = reasoning_history
+      self.appended_prompt_files = appended_prompt_files
+      self.interrupted_turn = interrupted_turn
+      @turn_checkpoint = nil
       @archived = false
     end
 
@@ -289,6 +323,7 @@ module Samagotchi
         llm_context: setup.llm_context,
         thinking: setup.thinking,
         reasoning_history: setup.reasoning_history,
+        appended_prompt_files: setup.appended_prompt_files,
         continues: continues
       )
     end
@@ -351,7 +386,9 @@ module Samagotchi
       "llm_context" => nil,
       "continues" => nil,
       "thinking" => nil,
-      "reasoning_history" => nil
+      "reasoning_history" => nil,
+      "appended_prompt_files" => [],
+      "interrupted_turn" => nil
     }.freeze
 
     # A session from a parsed session file. +messages+ false leaves the
@@ -463,11 +500,15 @@ module Samagotchi
       self
     end
 
-    # The session as #save writes it (FIELDS, in their order).
+    # The session as #save writes it (FIELDS, in their order); a running
+    # turn's checkpoint (#turn_checkpoint) in place of its messages.
     def to_h
+      checkpoint = checkpointed
       FIELDS.keys.to_h do |key|
         value = case key
-                when "messages" then @messages.map { |msg| scrub_utf8(stringify_message_keys(msg)) }
+                when "messages"
+                  (checkpoint ? checkpoint[:messages] : @messages).map { |msg| scrub_utf8(stringify_message_keys(msg)) }
+                when "interrupted_turn" then (checkpoint ? checkpoint[:marker] : @interrupted_turn)&.to_file
                 when "pending_question" then @pending_question && scrub_utf8(stringify_message_keys(@pending_question))
                 when "test_run" then !!@test_run
                 when "delegate" then @delegate
@@ -476,7 +517,7 @@ module Samagotchi
                 when "reasoning_history" then reasoning_history_file
                 when "prompt_notes" then @prompt_notes.map(&:to_file)
                 when "last_turn" then @last_turn&.to_file
-                when "used_memory_names", "preloaded_memory_names", "muted_memory_names"
+                when "used_memory_names", "preloaded_memory_names", "muted_memory_names", "appended_prompt_files"
                   Array(instance_variable_get(:"@#{key}"))
                 else instance_variable_get(:"@#{key}")
                 end
@@ -484,6 +525,13 @@ module Samagotchi
       end
     end
 
+    # The running turn's checkpoint, while the turn runs (#turn_checkpoint).
+    def checkpointed
+      checkpoint = @turn_checkpoint
+      checkpoint if checkpoint && @status == STATUS_RUNNING
+    end
+    private :checkpointed
+
     # Mark a session as errored.
     def self.mark_error(session_id, reason:, state_dir: default_state_dir)
       session = load(session_id, state_dir: state_dir)

data/lib/samagotchi/session_manager.rb

@@ -22,6 +22,7 @@ require_relative "turn_note"
 require_relative "owner_lock"
 require_relative "bridge_client"
 require_relative "worker_sidecar"
+require_relative "worker_signals"
 require_relative "log"
 require_relative "log_path"
 require_relative "model_profile"
@@ -210,7 +211,8 @@ module Samagotchi
     # wakes the worker picks which config.yml it reads (docs/guardrails.md).
     private_class_method def self.spawn_options(session)
       # Own process group: workers outlive `chi web`, and a Ctrl-C in its
-      # terminal must not reach them.
+      # terminal must not reach them (the worker then leaves the process
+      # tree too: WORKER_DETACH_ENV).
       opts = { out: File::NULL, err: File::NULL, pgroup: true }
       # The worker's tools (and `!cmd`) run in the session's directory, not
       # in the cwd of whoever woke it (`chi web`, another terminal).
@@ -253,6 +255,10 @@ module Samagotchi
       SESSION_MARKER_ENV.each { |key| child_env[key] = nil }
       # A smoke's fake "newest installed" is for this process's notices only.
       child_env[InstalledVersions::ENV_KEY] = nil
+      # A worker process: run_session_loop traps signals, and leaves this
+      # process's tree.
+      child_env[WORKER_PROCESS_ENV] = "1"
+      child_env[WORKER_DETACH_ENV] = "1"
       # A gem-mode worker activates the newest installed chi itself: under
       # `bundle exec` (a Gemfile that has samagotchi) Bundler's RUBYOPT would
       # hold it to the bundle's version, and its badge would never clear.
@@ -688,8 +694,8 @@ module Samagotchi
     # so a resume right after spawns a fresh worker instead of finding the
     # dying one.
     # A turn still running is canceled first (STOP_CANCEL_WAIT), as the
-    # web's Cancel does: its Engine saves the prompt, which the TERM alone
-    # would lose with the worker.
+    # web's Cancel does: its worker saves it. The TERM stops (and saves)
+    # what still runs (WorkerSignals), with a short grace after the marker.
     # @return [Boolean, nil] with +wait+: whether the owner was gone in time
     # @raise [OwnedByTUI] when the interactive TUI owns the session
     def self.stop_session(session_id, state_dir: nil, wait: nil)
@@ -930,7 +936,8 @@ module Samagotchi
     # @param idle_exit_minutes [Numeric, nil] nil: session.idle_exit_minutes
     # @param poll_interval [Numeric, nil] seconds between the loop's fallback
     #   ticks (nil: Worker::FALLBACK_TICK_SECONDS); queued turns wake it at once
-    # A stopped session's worker exits 0 and a crashed one 1, there.
+    # A stopped session's worker exits 0 (a signalled one too) and a
+    # crashed one 1, there.
     # @return [Symbol] :idle_exit, :exit_requested or :restart
     def self.run_session_loop(session_id, state_dir: nil, owner_wait: OwnerLock::DEFAULT_WAIT,
                               idle_exit_minutes: nil, poll_interval: nil)
@@ -942,6 +949,12 @@ module Samagotchi
       Log.configure(stderr: false)
       Log.session_id = session_id
       session_dir = Session.session_dir(session_id, state_dir: sd)
+      # Read (and taken out of ENV, so nothing the worker runs inherits it)
+      # before anything else: set by spawn_options for a spawned worker.
+      spawned = ENV.delete(WORKER_PROCESS_ENV) == "1"
+      # Out of the spawner's process tree before the lock (it records this
+      # process's pid) and before any thread starts.
+      detach_from_spawner(session_dir) if ENV.delete(WORKER_DETACH_ENV) == "1"
       # Kept in a class ivar so the lock's File lives as long as the worker.
       @owner_lock = OwnerLock.acquire(session_dir, kind: "worker", wait: owner_wait)
       exit(0) unless @owner_lock
@@ -949,8 +962,11 @@ module Samagotchi
       fallback = ENV.delete(BOOT_FALLBACK_ENV)
       Log.info(:worker, "start", cwd: Dir.pwd, version: VERSION)
       Log.warn(:worker, "boot_fallback", version: VERSION, error: fallback) if fallback
+      # A spawned worker stops its turn on TERM/HUP/INT and saves it; a
+      # loop run in-process (specs) traps nothing.
+      signals = spawned ? WorkerSignals.new.install! : WorkerSignals::NONE
       worker = Worker.new(session_id: session_id, state_dir: sd, session_dir: session_dir,
-                          idle_exit_minutes: idle_exit_minutes, poll_interval: poll_interval)
+                          idle_exit_minutes: idle_exit_minutes, poll_interval: poll_interval, signals: signals)
       result = begin
         worker.run
       rescue StandardError, ScriptError => e
@@ -959,11 +975,19 @@ module Samagotchi
         raise
       ensure
         @owner_lock.release
+        # A signal from here on ends the process as Ruby's default does.
+        signals.restore!
       end
       Log.info(:worker, "stop", reason: result)
       # A stopped session is left as it is: no resume for input that came
-      # in, no discard.
+      # in, no discard. One whose worker a signal stopped isn't discarded
+      # either; input that came in (queued behind the turn it stopped)
+      # wakes a new worker, as after an idle exit.
       exit(0) if result == :stopped
+      if result == :signal
+        resume_session(session_id, state_dir: sd) unless SessionInbox.find_new_input_files(session_dir).empty?
+        exit(0)
+      end
       exit(1) if result == :crashed
       # Only after the release: a writer that still saw this worker as the
       # owner may have queued input since the last check. Either it finds no
@@ -981,6 +1005,31 @@ module Samagotchi
       result
     end
 
+    # A spawned worker leaves its spawner's process tree: a killer that
+    # walks the tree by parent pid (a terminal closing, a tool's teardown
+    # of a `chi send --wait` it ran in the background) no longer reaches it.
+    # This process (the spawner's child, which its Process.detach waits on)
+    # forks the worker, which starts a session of its own (setsid: no
+    # controlling terminal, no SIGHUP from one) and returns to run the loop;
+    # this one waits until the worker holds the session's OwnerLock, or has
+    # exited, or WORKER_START_GRACE passed, and exits: the spawner's waiter
+    # stays alive exactly while the worker starts (#still_starting?). The
+    # worker is reparented to init (launchd), which reaps it.
+    private_class_method def self.detach_from_spawner(session_dir)
+      worker = Process.fork
+      unless worker
+        Process.setsid
+        return
+      end
+
+      deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + WORKER_START_GRACE
+      until Process.waitpid(worker, Process::WNOHANG) || OwnerLock.owner(session_dir)&.pid == worker ||
+            Process.clock_gettime(Process::CLOCK_MONOTONIC) >= deadline
+        sleep(OwnerLock::RETRY_INTERVAL)
+      end
+      Process.exit!(0)
+    end
+
     # Delete a session its worker left empty. Checked again now the lock is
     # free: a note or input may have come in since the worker looked, and a
     # worker woken meanwhile owns it (delete_session refuses). A `chi send`
@@ -1024,6 +1073,13 @@ module Samagotchi
     # format are read by a NEWER chi than the one writing them. Change them
     # only additively (spec/worker_contract_spec.rb).
     BOOT_FALLBACK_ENV = "SAMAGOTCHI_BOOT_FALLBACK"
+    # "1" in a worker spawn_options started: it traps signals (WorkerSignals).
+    # run_session_loop deletes it from ENV as it reads it.
+    WORKER_PROCESS_ENV = "SAMAGOTCHI_WORKER_PROCESS"
+    # "1" in a worker spawn_options started: run_session_loop leaves the
+    # spawner's process tree first (detach_from_spawner); deleted from ENV
+    # as it is read, so an rspec run by the worker's execute never forks.
+    WORKER_DETACH_ENV = "SAMAGOTCHI_WORKER_DETACH"
 
     def self.worker_command(session_id, state_dir:, gem_spec: InstalledGem.spec)
       boot = "require 'samagotchi/session_manager'; " \
@@ -1046,6 +1102,8 @@ module Samagotchi
       command = worker_command(session.id, state_dir: state_dir)
       pid = env ? Process.spawn(env, *command, **opts) : Process.spawn(*command, **opts)
       # Reaped when it exits: a long-lived spawner (chi web) keeps no zombies.
+      # +pid+ is the worker's starter, which exits once the worker it forked
+      # holds the lock (detach_from_spawner): the lock's pid is the worker's.
       note_spawn(session.id, state_dir: state_dir, waiter: Process.detach(pid))
       Log.info(:worker, "spawn", sid: session.id, child_pid: pid)
       pid

data/lib/samagotchi/session_metrics.rb

@@ -142,9 +142,13 @@ module Samagotchi
       :cuts,
       :capped,
       :model,
-      # The turn the user started by answering the step-limit question with
-      # Continue (:turn_started's +continue+); its record carries it.
+      # A turn with no prompt of its own (:turn_started's +continue+): a
+      # step-limit Continue, a reminder's or a wake's turn; its record
+      # carries it.
       :continue,
+      # The turn the user started by answering the step-limit question with
+      # Continue (:turn_started's +resumed+): it resumed the run before it.
+      :resumed,
       :id,
       :started_at,
       :started_monotonic,
@@ -558,6 +562,7 @@ module Samagotchi
           capped: 0,
           model: nil,
           continue: event[:continue] ? true : false,
+          resumed: event[:resumed] ? true : false,
           id: event[:turn_id] || SecureRandom.uuid,
           started_at: now.iso8601(3),
           started_monotonic: monotonic_time,
@@ -597,6 +602,7 @@ module Samagotchi
           # Every record says, so the report can tell a file with no Continue
           # from one written before the mark.
           record[:continue] = @turn.continue
+          record[:resumed] = @turn.resumed
           record.merge!(turn_token_fields(@turn))
           @turn_records << record
           count_turn(record)

data/lib/samagotchi/session_setup.rb

@@ -10,15 +10,20 @@ module Samagotchi
   # (SessionManager.spawn_session, a continue, a plugin's fork, the web's
   # create, chi send --new): +llm_context+ is an LLMContextOverride or nil,
   # +thinking+ a level Symbol (Thinking.session_level) or nil,
-  # +reasoning_history+ a level Symbol (ReasoningHistory.session_level) or nil.
+  # +reasoning_history+ a level Symbol (ReasoningHistory.session_level) or nil,
+  # +appended_prompt_files+ the absolute paths chi --append-system-prompt
+  # named (their text goes into the system prompt; [] with none).
   #
   # It doesn't save itself: the session keeps each setting in its own field
   # and file key, and resolves it on its own. A delegate child starts
   # without one; a continue and a fork copy their session's (.of).
-  SessionSetup = Data.define(:llm_context, :thinking, :reasoning_history) do
-    def initialize(llm_context: nil, thinking: nil, reasoning_history: nil) = super
+  SessionSetup = Data.define(:llm_context, :thinking, :reasoning_history, :appended_prompt_files) do
+    def initialize(llm_context: nil, thinking: nil, reasoning_history: nil, appended_prompt_files: [])
+      super(llm_context: llm_context, thinking: thinking, reasoning_history: reasoning_history,
+            appended_prompt_files: Array(appended_prompt_files).map(&:to_s).freeze)
+    end
 
-    def empty? = llm_context.nil? && thinking.nil? && reasoning_history.nil?
+    def empty? = llm_context.nil? && thinking.nil? && reasoning_history.nil? && appended_prompt_files.empty?
 
     # A session's own setup, for a session that starts from it.
     # @param session [Session, nil]
@@ -26,7 +31,8 @@ module Samagotchi
     def self.of(session)
       return new if session.nil?
 
-      new(llm_context: session.llm_context, thinking: session.thinking, reasoning_history: session.reasoning_history)
+      new(llm_context: session.llm_context, thinking: session.thinking, reasoning_history: session.reasoning_history,
+          appended_prompt_files: session.appended_prompt_files)
     end
   end
 end