samagotchi 0.92.0 → 0.93.0

data/lib/samagotchi/testing/host.rb

@@ -27,10 +27,7 @@ module Samagotchi
           messages: -> { recorder[:messages] },
           messages_partial: -> { recorder[:messages_partial] },
           notify: ->(text, level, label, fallback_for: nil) { recorder.notify(text, level, label, fallback_for) },
-          ask_user: lambda { |question:, options:, header:, allow_freeform:, hook:, effects: nil|
-            recorder.ask_user(question: question, options: options, header: header, allow_freeform: allow_freeform, hook: hook,
-                              effects: effects)
-          },
+          ask_user: ->(question) { recorder.ask_user(question) },
           cancelled: -> { recorder[:cancelled] },
           card: ->(**card) { recorder.card(**card) },
           ask_model: lambda { |request, timeout:, max_tokens:, cancel_controller:, model: nil, source: nil|
@@ -89,10 +86,7 @@ module Samagotchi
       def build(recorder)
         Hooks::Runtime.new(
           notify: ->(text:, level:, hook:, fallback_for: nil) { recorder.notify(text, level, hook, fallback_for) },
-          ask_user: lambda { |question:, options:, header:, allow_freeform:, hook:, effects: nil|
-            recorder.ask_user(question: question, options: options, header: header, allow_freeform: allow_freeform, hook: hook,
-                              effects: effects)
-          },
+          ask_user: ->(question) { recorder.ask_user(question) },
           stop_turn: ->(reason:, hook:) { recorder.stop(:turn, reason, hook) },
           steer: ->(text:, hook:) { recorder.steer(text, hook) },
           stop_generation: ->(reason:, hook:) { recorder.stop(:generation, reason, hook) }

data/lib/samagotchi/testing/recorder.rb

@@ -3,6 +3,7 @@
 require_relative "../plugin/card"
 require_relative "../plugin/context"
 require_relative "../guardrails/parent_policy"
+require_relative "../hook_question"
 
 module Samagotchi
   module Testing
@@ -13,11 +14,6 @@ module Samagotchi
     Steer = Data.define(:text, :hook)
     # A stop_turn or stop_generation (+kind+ :turn or :generation).
     Stop = Data.define(:kind, :reason, :hook)
-    # An ask_user question; effects: its options' tags as the bundle gave
-    # them (label => effect), nil for none.
-    Question = Data.define(:question, :options, :header, :allow_freeform, :hook, :effects) do
-      def initialize(effects: nil, **) = super
-    end
     # An ask_model request: the request Context built (SideQuestion), its
     # limits, cancel controller and the model: it named (nil: the session's;
     # the kit doesn't check it against any hosts), and +source+, the asking
@@ -107,11 +103,12 @@ module Samagotchi
       # Effects chi would refuse (a label the options don't have, an
       # unknown effect: Guardrails::ParentPolicy.option_tags) ask no one, as
       # in chi: nil, nothing recorded, no answer taken.
-      def ask_user(question:, options:, header:, allow_freeform:, hook:, effects: nil)
-        return nil if Guardrails::ParentPolicy.option_tags(options, effects) == false
+      # @param question [HookQuestion] recorded as asked (#questions; its
+      #   effects as the bundle gave them: label => effect, nil for none)
+      def ask_user(question)
+        return nil if Guardrails::ParentPolicy.option_tags(question.options, question.effects) == false
 
-        record(@questions, Question.new(question: question, options: options, header: header,
-                                        allow_freeform: allow_freeform, hook: hook, effects: effects))
+        record(@questions, question)
         answer = @mutex.synchronize { @answers.shift }
         answer.respond_to?(:call) ? answer.call(@questions.last) : answer
       end

data/lib/samagotchi/tools/delegate.rb

@@ -234,11 +234,11 @@ module Samagotchi
         DelegateWait.mark_seen(parent.id, child, state_dir: state_dir)
         delivered = SessionManager.deliver_turn(id, prompt: task, client_id: "#{ClientId::DELEGATE_PREFIX}#{parent.id[0, 8]}",
                                                     state_dir: state_dir)
-        case delivered[:status]
+        case delivered.status
         when :accepted
-          DelegateWait.mark_turn(parent.id, id, follow_up_turn(id, delivered[:ack], state_dir: state_dir), state_dir: state_dir)
+          DelegateWait.mark_turn(parent.id, id, follow_up_turn(id, delivered.enqueued_id, state_dir: state_dir), state_dir: state_dir)
           id
-        when :refused then "Error: session #{id[0, 8]} refused the message (#{delivered.dig(:ack, "error")})"
+        when :refused then "Error: session #{id[0, 8]} refused the message (#{delivered.error})"
         when :timeout then "Error: the worker of session #{id[0, 8]} did not answer in time, so the message was not sent"
         else "Error: the message to session #{id[0, 8]} could not be written"
         end
@@ -251,24 +251,24 @@ module Samagotchi
 
       # The child's turn a delivered follow-up joins, for the wait
       # (DelegateCursor#turn): the running turn's (its checkpoint mark), the
-      # follow-up merging into it; else the ack's enqueued_id, the follow-up
-      # running as a turn of its own. Only from a worker that names
-      # turn_ids; nil otherwise, or when the running turn has no id (a
-      # delegate's first turn): the wait takes the next reply.
+      # follow-up merging into it; else the delivery's +enqueued_id+, the
+      # follow-up running as a turn of its own. Only
+      # from a worker that names turn_ids; nil otherwise, or when the
+      # running turn has no id (a delegate's first turn): the wait takes the
+      # next reply.
       # A follow-up steered into a turn that ended before it merged runs as
       # its own turn, yet the wait is on the ended one (LOW, as before).
       # One the child's idle look missed being merged into a turn starting
       # then never runs as its own: ReplyWait falls back to that turn's
       # reply (merged_elsewhere?).
       # @return [String, nil]
-      def self.follow_up_turn(id, ack, state_dir:)
+      def self.follow_up_turn(id, enqueued_id, state_dir:)
         return nil unless ReplyWait.turn_ids?(Session.session_dir(id, state_dir: state_dir))
 
         child = Session.load(id, state_dir: state_dir)
         return child.interrupted_turn&.enqueued_id if child.status == Session::STATUS_RUNNING
 
-        enqueued_id = ack.is_a?(Hash) ? (ack["enqueued_id"] || ack[:enqueued_id]) : nil
-        enqueued_id.to_s.empty? ? nil : enqueued_id.to_s
+        enqueued_id
       rescue ArgumentError
         nil
       end

data/lib/samagotchi/tools/delegate_cursor.rb

@@ -4,6 +4,7 @@ require "json"
 require "fileutils"
 require_relative "../atomic_file"
 require_relative "../session"
+require_relative "../reply_wait"
 
 module Samagotchi
   module Tools
@@ -14,32 +15,54 @@ module Samagotchi
     # of the child's turn the last follow-up went to (Delegate.follow_up),
     # whose own reply a wait takes (ReplyWait's turn:); nil once that turn
     # was reported, or when unknown (a new child, an older worker).
-    #   +report_claim+: a report reserved until the parent's turn is settled.
+    #   +report_claim+: a report reserved until the parent's turn is settled
+    # (ReportClaim).
     DelegateCursor = Data.define(:reply_file, :last_turn, :question_id, :messages, :turn, :report_claim) do
       def initialize(reply_file: nil, last_turn: nil, question_id: nil, messages: nil, turn: nil, report_claim: nil) = super
 
       def self.empty = new
 
-      # @param baseline [Hash, nil] ReplyWait.baseline_of's
+      # The cursor with no report reserved: what it is once the reserving
+      # turn is settled, and how two cursors compare apart from a claim.
+      def without_claim = with(report_claim: nil)
+
+      # @param baseline [ReplyWait::Baseline, nil] ReplyWait.baseline_of's
       def with_baseline(baseline)
-        b = baseline || {}
-        with(messages: b[:messages], question_id: b[:question_id], last_turn: b[:last_turn])
+        with(messages: baseline&.messages, question_id: baseline&.question_id, last_turn: baseline&.last_turn)
       end
 
-      # @return [Hash, nil] ReplyWait's baseline:, nil when none was taken
+      # @return [ReplyWait::Baseline, nil] ReplyWait's baseline:, nil when
+      #   none was taken
       def baseline
         return nil if messages.nil?
 
-        { messages: messages, question_id: question_id, last_turn: last_turn }
+        ReplyWait::Baseline.new(messages: messages, question_id: question_id, last_turn: last_turn)
       end
 
-      def to_json_hash = to_h.transform_keys(&:to_s).compact
+      def to_json_hash = to_h.merge(report_claim: report_claim&.to_json_hash).transform_keys(&:to_s).compact
 
       def self.from_json_hash(data)
         return empty unless data.is_a?(Hash)
 
         new(reply_file: data["reply_file"], last_turn: data["last_turn"], question_id: data["question_id"],
-            messages: data["messages"], turn: data["turn"], report_claim: data["report_claim"])
+            messages: data["messages"], turn: data["turn"], report_claim: ReportClaim.from_json_hash(data["report_claim"]))
+      end
+    end
+
+    # A delegate report reserved in the parent's cursor (ChildReports) until
+    # the parent's turn that took it is kept or rolled back: +id+ the
+    # claim's id (the taking turn's Report#claim_id), +file+ the reply file
+    # reported (nil for a question), +cursor+ the DelegateCursor the report
+    # moves the parent to once kept (its own claim empty). In delegates.json
+    # it is {"id", "file", "cursor"}, the file's key kept even when nil.
+    ReportClaim = Data.define(:id, :file, :cursor) do
+      def to_json_hash = { "id" => id, "file" => file, "cursor" => cursor.to_json_hash }
+
+      # @return [ReportClaim, nil] nil for no claim (or not a Hash)
+      def self.from_json_hash(data)
+        return nil unless data.is_a?(Hash)
+
+        new(id: data["id"], file: data["file"], cursor: DelegateCursor.from_json_hash(data["cursor"]))
       end
     end
 
@@ -77,6 +100,7 @@ module Samagotchi
       end
 
       # Reserve a report only if the cursor read to build it is still current.
+      # @param claim [ReportClaim]
       # @return [DelegateCursor, nil] the reserved cursor, or nil if another path moved it
       def claim_report(parent_id, child_id, expected:, claim:, state_dir:)
         locked(parent_id, state_dir: state_dir) do

data/lib/samagotchi/tools/delegate_relay.rb

@@ -85,7 +85,7 @@ module Samagotchi
 
         fields = Relay.card(child, question, relay_id: relay_id, more: more)
         answer = relay.open_question(fields, watch: watch(child_id, qid, state_dir))
-        settle(answer, fields, client: client, desk: desk, relay_id: relay_id, qid: qid)
+        settle(answer, fields, label: label(question), client: client, desk: desk, relay_id: relay_id, qid: qid)
       ensure
         # A relay that failed before it settled closes, so the desk (which
         # prunes only settled ones) keeps none open; a settled one stays.
@@ -108,12 +108,11 @@ module Samagotchi
       end
 
       # Record the parent's answer, tell the child, and say what came of it.
-      def settle(answer, fields, client:, desk:, relay_id:, qid:)
-        what = fields[:kind] == HOOK_KIND ? hook_what(fields) : what_text(fields[:approval])
-        hook = fields[:kind] == HOOK_KIND
+      # @param label [String] the outcome line's start (#label)
+      def settle(answer, fields, label:, client:, desk:, relay_id:, qid:)
         if answer.is_a?(Hash) && answer[:error] == "cancelled"
           desk.close(relay_id)
-          return closed(answer[:reason].to_s, what, client: client, relay_id: relay_id, qid: qid, hook: hook)
+          return closed(answer[:reason].to_s, label, client: client, relay_id: relay_id, qid: qid)
         end
 
         dismissed = !answer.is_a?(QuestionAnswer)
@@ -121,18 +120,18 @@ module Samagotchi
         desk.record(relay_id, selected_indices: dismissed ? [] : answer.selected_indices,
                               freeform: dismissed ? nil : answer.freeform, dismissed: dismissed, by: by)
         response = post(client, "answered", relay_id, qid)
-        Outcome.new(line: line(what, delivered(response, answer, fields, dismissed), hook: hook), stopped: false)
+        Outcome.new(line: line(label, delivered(response, answer, fields, dismissed)), stopped: false)
       end
 
-      def closed(reason, what, client:, relay_id:, qid:, hook: false)
+      def closed(reason, label, client:, relay_id:, qid:)
         case reason
-        when "answered_on_child" then Outcome.new(line: line(what, "answered on the child", hook: hook), stopped: false)
+        when "answered_on_child" then Outcome.new(line: line(label, "answered on the child"), stopped: false)
         when "child_gone"
-          Outcome.new(line: line(what, "not delivered (the child's worker is gone)", hook: hook), stopped: false)
+          Outcome.new(line: line(label, "not delivered (the child's worker is gone)"), stopped: false)
         else
           # A Stop: the child's question stays open there.
           post(client, "closed", relay_id, qid, reason: "stopped")
-          Outcome.new(line: line(what, "still open (your turn was stopped)", hook: hook), stopped: true)
+          Outcome.new(line: line(label, "still open (your turn was stopped)"), stopped: true)
         end
       end
 
@@ -172,14 +171,30 @@ module Samagotchi
         why.empty? ? "denied" : "denied (#{why.inspect})"
       end
 
-      def line(what, outcome, hook: false)
-        "#{hook ? "hook question" : "approval"} relayed to your user: #{what} → #{outcome}"
+      # One relayed question's outcome line: #label → +outcome+.
+      def line(label, outcome) = "#{label} → #{outcome}"
+
+      # What an outcome line starts with: "hook question relayed to your
+      # user: Cost cap", "approval relayed to your user: execute: git push".
+      # @param question [PendingQuestion] the child's
+      def label(question)
+        "#{question.kind.to_s == HOOK_KIND ? "hook question" : "approval"} relayed to your user: #{what(question)}"
+      end
+
+      # What a relayed question is about, as its card has it (Relay.card): a
+      # hook's header as the asking hook gave it (kept down a chain: a relay
+      # of a relay), else its hook; an approval's call (#what_text).
+      # @param question [PendingQuestion] the child's
+      def what(question)
+        return what_text(symbolized(question.approval)) unless question.kind.to_s == HOOK_KIND
+
+        inner = symbolized(question.relay, nil)
+        header = (inner ? inner[:header] : question.header).to_s
+        header.empty? ? question.hook.to_s : header
       end
 
-      # A hook card's header as the child asked it (Cost cap), or its hook.
-      def hook_what(fields)
-        header = fields.dig(:relay, :header).to_s
-        header.empty? ? fields[:hook].to_s : header
+      def symbolized(value, none = {})
+        value.is_a?(Hash) ? Relay.deep_symbolize(value) : none
       end
 
       # execute: git push origin main

data/lib/samagotchi/tools/delegate_wait.rb

@@ -69,7 +69,7 @@ module Samagotchi
         cursor = DelegateCursors.get(peers.session_id, child_id, state_dir: sd)
         report_claim = cursor.report_claim
         if report_claim
-          cursor = DelegateCursor.from_json_hash(report_claim["cursor"]).with(report_claim: report_claim)
+          cursor = report_claim.cursor.with(report_claim: report_claim)
         end
 
         baseline = cursor.baseline
@@ -88,10 +88,10 @@ module Samagotchi
             outcomes.concat(relayed_outcomes.delete(key) || [])
             movement = advance(peers.session_id, child_id, wait, state_dir: sd)
             if movement&.already_reported
-              file = movement.cursor.report_claim&.fetch("file", nil) || wait.file
+              file = movement.cursor.report_claim&.file || wait.file
               return already_reported_result(child_id, file, state_dir: sd)
             end
-            return already_reported_result(child_id, report_claim["file"], state_dir: sd) if report_claim && wait.status == :timeout
+            return already_reported_result(child_id, report_claim.file, state_dir: sd) if report_claim && wait.status == :timeout
 
             text = with_outcomes(finish(wait, child_id, timeout: timeout, reports: reports), outcomes)
             return RefText.wrap(text, reply_path(child_id, wait, state_dir: sd))
@@ -179,7 +179,7 @@ module Samagotchi
 
         already_reported = false
         cursor = DelegateCursors.update(parent_id, child_id, state_dir: state_dir) do |current|
-          if (current.report_claim && current.report_claim["file"] == wait.file) ||
+          if (current.report_claim && current.report_claim.file == wait.file) ||
              (wait.status == :done && current.reply_file == wait.file)
             already_reported = true
             next current

data/lib/samagotchi/version.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Samagotchi
-  VERSION = "0.92.0"
+  VERSION = "0.93.0"
   # Sent as the User-Agent of every HTTP request chi makes.
   USER_AGENT = "chi/#{VERSION}"
 end

data/lib/samagotchi/web/app.rb

@@ -152,7 +152,8 @@ module Samagotchi
       private
 
       # The routes, first match wins: a handler takes the request and the
-      # path's captures (the session id, an image's name).
+      # path's captures (the session id, an image's name). A :session route
+      # runs in #session_route: an ArgumentError is its unknown session.
       ROUTES = [
         ["GET", %r{\A/(?:index\.html)?\z}, :serve_index],
         ["GET", %r{\A/api/sessions\z}, :handle_list],
@@ -163,26 +164,26 @@ module Samagotchi
         ["GET", %r{\A/api/events\z}, :handle_events],
         ["POST", %r{\A/api/render\z}, :handle_render],
         ["GET", %r{\A/api/sessions/([^/]+)/stream\z}, :handle_stream],
-        ["GET", %r{\A/api/sessions/([^/]+)/output\z}, :handle_output],
-        ["POST", %r{\A/api/sessions/([^/]+)/cancel\z}, :handle_cancel],
-        ["POST", %r{\A/api/sessions/([^/]+)/tasks/([^/]+)/stop\z}, :handle_task_stop],
-        ["POST", %r{\A/api/sessions/([^/]+)/turn/([^/]+)/dequeue\z}, :handle_dequeue_turn],
-        ["POST", %r{\A/api/sessions/([^/]+)/stop\z}, :handle_stop],
-        ["POST", %r{\A/api/sessions/([^/]+)/restart\z}, :handle_restart],
-        ["POST", %r{\A/api/sessions/([^/]+)/archive\z}, :handle_archive],
-        ["POST", %r{\A/api/sessions/([^/]+)/unarchive\z}, :handle_unarchive],
-        ["POST", %r{\A/api/sessions/([^/]+)/turn\z}, :handle_turn],
+        ["GET", %r{\A/api/sessions/([^/]+)/output\z}, :handle_output, :session],
+        ["POST", %r{\A/api/sessions/([^/]+)/cancel\z}, :handle_cancel, :session],
+        ["POST", %r{\A/api/sessions/([^/]+)/tasks/([^/]+)/stop\z}, :handle_task_stop, :session],
+        ["POST", %r{\A/api/sessions/([^/]+)/turn/([^/]+)/dequeue\z}, :handle_dequeue_turn, :session],
+        ["POST", %r{\A/api/sessions/([^/]+)/stop\z}, :handle_stop, :session],
+        ["POST", %r{\A/api/sessions/([^/]+)/restart\z}, :handle_restart, :session],
+        ["POST", %r{\A/api/sessions/([^/]+)/archive\z}, :handle_archive, :session],
+        ["POST", %r{\A/api/sessions/([^/]+)/unarchive\z}, :handle_unarchive, :session],
+        ["POST", %r{\A/api/sessions/([^/]+)/turn\z}, :handle_turn, :session],
         ["POST", %r{\A/api/sessions/([^/]+)/answer\z}, :handle_question_answer],
         ["POST", %r{\A/api/sessions/([^/]+)/question/dismiss\z}, :handle_question_dismiss],
-        ["POST", %r{\A/api/sessions/([^/]+)/command\z}, :handle_command],
+        ["POST", %r{\A/api/sessions/([^/]+)/command\z}, :handle_command, :session],
         ["POST", %r{\A/api/sessions/([^/]+)/images\z}, :handle_image_upload],
         ["GET", %r{\A/api/sessions/([^/]+)/images/([^/]+)\z}, :handle_image],
-        ["GET", %r{\A/api/sessions/([^/]+)/context\z}, :handle_context_list],
-        ["GET", %r{\A/api/sessions/([^/]+)/context/([^/]+)\z}, :handle_context_show],
-        ["POST", %r{\A/api/sessions/([^/]+)/context\z}, :handle_context_add],
-        ["DELETE", %r{\A/api/sessions/([^/]+)/context/([^/]+)\z}, :handle_context_delete],
-        ["GET", %r{\A/api/sessions/([^/]+)\z}, :handle_show],
-        ["DELETE", %r{\A/api/sessions/([^/]+)\z}, :handle_delete]
+        ["GET", %r{\A/api/sessions/([^/]+)/context\z}, :handle_context_list, :session],
+        ["GET", %r{\A/api/sessions/([^/]+)/context/([^/]+)\z}, :handle_context_show, :session],
+        ["POST", %r{\A/api/sessions/([^/]+)/context\z}, :handle_context_add, :session],
+        ["DELETE", %r{\A/api/sessions/([^/]+)/context/([^/]+)\z}, :handle_context_delete, :session],
+        ["GET", %r{\A/api/sessions/([^/]+)\z}, :handle_show, :session],
+        ["DELETE", %r{\A/api/sessions/([^/]+)\z}, :handle_delete, :session]
       ].freeze
 
       def route(env)
@@ -195,7 +196,7 @@ module Samagotchi
           return denied if denied
         end
 
-        ROUTES.each do |verb, pattern, handler|
+        ROUTES.each do |verb, pattern, handler, kind|
           next unless req.request_method == verb && (m = pattern.match(req.path_info))
           # Every /api/sessions/:id route: an id that isn't one (Session.valid_id?,
           # "..", a %2F) is an unknown session before any handler makes a path.
@@ -203,6 +204,8 @@ module Samagotchi
             return error_response(404, "not_found", "Session not found: #{m.captures.first.to_s[0, 80]}")
           end
 
+          return session_route { send(handler, req, *m.captures) } if kind == :session
+
           return send(handler, req, *m.captures)
         end
         # Anything else is a file under public_dir (/assets/*, /public/* or
@@ -213,6 +216,16 @@ module Samagotchi
         error_response(500, "internal_error", e.message)
       end
 
+      # A :session route's handler: the ArgumentError its session lookup
+      # raises (Session.load, the manager's find) is a 404 not_found with
+      # its message. Only these routes: elsewhere an ArgumentError is a bug,
+      # #route's 500. A handler's own rescues run first.
+      def session_route
+        yield
+      rescue ArgumentError => e
+        error_response(404, "not_found", e.message)
+      end
+
       # API requests at debug level (not the page and its assets): method,
       # path, status, time. Never a body or the query; only a tail=1 read
       # (the page's end-of-turn re-read) and a timing=1 one (its fallback
@@ -737,7 +750,7 @@ module Samagotchi
       rescue SessionManager::ArchiveRefused => e
         [nil, error_response(409, e.reason == :scratch ? "scratch" : "busy", e.message)]
       rescue SessionManager::OwnedByTUI
-        [nil, error_response(409, "owned_by_tui", "session #{given} is open in a chi REPL; close it there first")]
+        [nil, owned_by_repl(given)]
       rescue ModelProfile::MissingModel => e
         [nil, error_response(400, "invalid_model", e.message)]
       rescue Session::AmbiguousId => e
@@ -839,8 +852,6 @@ module Samagotchi
           last_event_id: turn_snapshot && turn_snapshot["event_id"],
           timing: timing
         })
-      rescue ArgumentError => e
-        error_response(404, "not_found", e.message)
       end
 
       # A list in the worker's turn +snapshot+ (queued prompts, commands,
@@ -948,8 +959,6 @@ module Samagotchi
           **viewer_capabilities(req),
           timing: timing
         })
-      rescue ArgumentError => e
-        error_response(404, "not_found", e.message)
       end
 
       # The folder the live tail's answer's file refs must stay under: the
@@ -1132,8 +1141,6 @@ module Samagotchi
         end
       rescue SessionManager::OwnedByTUI => e
         error_response(409, "owned_by_tui", e.message)
-      rescue ArgumentError => e
-        error_response(404, "not_found", e.message)
       end
 
       # Hand a request to the session's live Bridge (+client+, nil without
@@ -1169,6 +1176,12 @@ module Samagotchi
         not_live(id)
       end
 
+      # 409 owned_by_tui in the words a refused archive, delete or continue
+      # shows (stop, restart, a turn and a command show OwnedByTUI's own).
+      def owned_by_repl(id)
+        error_response(409, "owned_by_tui", SessionManager::OwnedByTUI.new(id).message)
+      end
+
       def not_live(id)
         error_response(503, "not_live", "no live bridge for session #{id}")
       end
@@ -1204,8 +1217,6 @@ module Samagotchi
         # Strip wire tokens server-side so the client never sees <|tool_call> etc.
         rendered = raw.map { |chunk| OutputFormatter.strip(chunk) }.reject(&:empty?)
         json_response(200, { session_id: session.id, output: rendered })
-      rescue ArgumentError => e
-        error_response(404, "not_found", e.message)
       end
 
       def handle_turn(req, id)
@@ -1231,18 +1242,16 @@ module Samagotchi
         result = SessionManager.deliver_turn(id, prompt: prompt.to_s, client_id: client_id, images: images,
                                                  delivery: delivery, state_dir: @state_dir, manager: @manager,
                                                  bridge: -> { live_bridge_client(id) })
-        case result[:status]
+        case result.status
         when :accepted
           record_history(body, prompt)
-          json_response(202, result[:ack])
-        when :refused then json_response(result[:code], result[:ack])
-        when :timeout then error_response(504, "worker_timeout", result[:ack]["detail"])
+          json_response(202, result.ack)
+        when :refused then json_response(result.code, result.ack)
+        when :timeout then error_response(504, "worker_timeout", result.detail)
         else error_response(500, "enqueue_failed", "could not write turn input")
         end
       rescue SessionManager::OwnedByTUI => e
         error_response(409, "owned_by_tui", e.message)
-      rescue ArgumentError => e
-        error_response(404, "not_found", e.message)
       end
 
       # A turn's images as [{file:, name:}] (refs to uploads already in the
@@ -1323,8 +1332,7 @@ module Samagotchi
       def handle_cancel(req, id)
         @session_class.load(id, state_dir: default_state_dir)
 
-        body = request_body(req)
-        parsed = body.nil? || body.strip.empty? ? nil : parse_json(body)
+        parsed = parse_json(request_body(req))
         reason = (parsed["reason"] if parsed.is_a?(Hash)).to_s.strip
         reason = "user" if reason.empty?
 
@@ -1337,8 +1345,6 @@ module Samagotchi
           when 409 then json_response(409, { error: "not_running", detail: "no active turn to cancel", session_id: id })
           end
         end
-      rescue ArgumentError => e
-        error_response(404, "not_found", e.message)
       end
 
       # A task id as TaskRuntime.generate_task_id makes it.
@@ -1361,8 +1367,6 @@ module Samagotchi
           when 409 then json_response(409, { error: "not_running", status: body["status"], task_id: task_id, session_id: id })
           end
         end
-      rescue ArgumentError => e
-        error_response(404, "not_found", e.message)
       end
 
       # POST /api/sessions/:id/turn/:enqueued_id/dequeue {client_id?}: the ×
@@ -1374,8 +1378,7 @@ module Samagotchi
       # 404 unknown_enqueued_id pass through; the rest as every relay.
       def handle_dequeue_turn(req, id, enqueued_id)
         @session_class.load(id, state_dir: default_state_dir)
-        body = request_body(req)
-        parsed = body.nil? || body.strip.empty? ? nil : parse_json(body)
+        parsed = parse_json(request_body(req))
         client_id = (parsed["client_id"] if parsed.is_a?(Hash))
 
         request = ->(client) { client.dequeue(enqueued_id: enqueued_id, client_id: client_id) }
@@ -1388,8 +1391,6 @@ module Samagotchi
             json_response(404, { error: "unknown_enqueued_id", enqueued_id: enqueued_id, session_id: id }) if body["error"] == "unknown_enqueued_id"
           end
         end
-      rescue ArgumentError => e
-        error_response(404, "not_found", e.message)
       end
 
       def handle_stop(_req, id)
@@ -1400,8 +1401,6 @@ module Samagotchi
         json_response(200, { status: "stopped", session_id: id })
       rescue SessionManager::OwnedByTUI => e
         error_response(409, "owned_by_tui", e.message)
-      rescue ArgumentError => e
-        error_response(404, "not_found", e.message)
       end
 
       # POST /api/sessions/:id/restart: hand the session to a new worker on
@@ -1420,8 +1419,6 @@ module Samagotchi
         json_response(409, { error: error, reason: e.reason.to_s, detail: e.message, session_id: id })
       rescue SessionManager::OwnedByTUI => e
         error_response(409, "owned_by_tui", e.message)
-      rescue ArgumentError => e
-        error_response(404, "not_found", e.message)
       end
 
       # POST /api/sessions/:id/archive: hide it (and its delegates) from the
@@ -1434,11 +1431,9 @@ module Samagotchi
         json_response(200, { status: "archived", session_id: result[:id], archived: result[:archived],
                              stopped: result[:stopped], discarded: result[:discarded] })
       rescue SessionManager::OwnedByTUI
-        error_response(409, "owned_by_tui", "session #{id} is open in a chi REPL; close it there first")
+        owned_by_repl(id)
       rescue SessionManager::ArchiveRefused => e
         error_response(409, e.reason == :scratch ? "scratch" : "busy", e.message)
-      rescue ArgumentError => e
-        error_response(404, "not_found", e.message)
       end
 
       # POST /api/sessions/:id/unarchive: back to the lists, delegates too.
@@ -1446,8 +1441,6 @@ module Samagotchi
         result = @manager.unarchive_session(id, state_dir: @state_dir)
         result[:unarchived].each { |sid| @hub&.touch(sid) }
         json_response(200, { status: "unarchived", session_id: result[:id], unarchived: result[:unarchived] })
-      rescue ArgumentError => e
-        error_response(404, "not_found", e.message)
       end
 
       # DELETE /api/sessions/:id: the session for good. A live worker is
@@ -1458,11 +1451,9 @@ module Samagotchi
         @hub&.touch(result[:id])
         json_response(200, { status: "deleted", session_id: result[:id], stopped: result[:stopped] })
       rescue SessionManager::OwnedByTUI
-        error_response(409, "owned_by_tui", "session #{id} is open in a chi REPL; close it there first")
+        owned_by_repl(id)
       rescue SessionManager::DeleteRefused => e
         error_response(409, e.reason.to_s, "#{e.message}; try again in a moment")
-      rescue ArgumentError => e
-        error_response(404, "not_found", e.message)
       end
 
       # ── Attached context (ContextSources): the session bar's chips ───────
@@ -1478,8 +1469,6 @@ module Samagotchi
         subs = own.subscriptions
         rows = attached_context(session).map { |attached| context_row(attached, own, subs) }
         json_response(200, { session_id: id, sources: rows, can_add_url: ContextProviders.any? })
-      rescue ArgumentError => e
-        error_response(404, "not_found", e.message)
       end
 
       # GET /api/sessions/:id/context/:name: one source with its text.
@@ -1488,8 +1477,6 @@ module Samagotchi
         attached = find_context(session, name) or return error_response(404, "not_found", "no source #{name[0, 40]}")
         own = ContextSources.session_location(id, state_dir: default_state_dir)
         json_response(200, context_row(attached, own, own.subscriptions).merge(text: attached.snapshot.text))
-      rescue ArgumentError => e
-        error_response(404, "not_found", e.message)
       end
 
       # POST /api/sessions/:id/context {url, why}: the source an installed
@@ -1512,8 +1499,6 @@ module Samagotchi
         error_response(422, "no_provider", e.message)
       rescue ContextSources::Invalid => e
         error_response(409, "exists", e.message)
-      rescue ArgumentError => e
-        error_response(404, "not_found", e.message)
       end
 
       def web_source(resolved, why, scope)
@@ -1535,8 +1520,6 @@ module Samagotchi
           ContextSources.session_location(id, state_dir: default_state_dir).mute(attached.name)
           json_response(200, { status: "muted", name: attached.name })
         end
-      rescue ArgumentError => e
-        error_response(404, "not_found", e.message)
       end
 
       def attached_context(session)