pikuri-core 0.0.7 → 0.1.0

data/lib/pikuri/subprocess.rb

@@ -4,88 +4,63 @@ require 'open3'
 require 'set'
 
 module Pikuri
-  # Chokepoint for *all* subprocess spawning in pikuri. Forces a new
-  # process group for each invocation, tracks pgids so descendants of
-  # the direct child (commands backgrounded with +&+) can be cleaned
-  # up at process exit. Two front doors: {.spawn} (combined
-  # stdout+stderr through a single pipe — the shell-command shape) and
-  # {.run} (stdin fed from a String or streamed from an IO, stdout
-  # redirected to a file, stderr captured — the filter shape).
+  # Chokepoint for *all* subprocess spawning in pikuri. Forces a new process
+  # group per invocation and tracks pgids so descendants (commands
+  # backgrounded with +&+) can be cleaned up at exit. Two front doors:
+  # {.spawn} (combined stdout+stderr through one pipe — the shell-command
+  # shape) and {.run} (stdin from a String/IO, stdout to a file, stderr
+  # captured — the filter shape).
   #
   # == Seam discipline
   #
-  # All subprocess spawning in +lib/+ goes through {.spawn}. Direct
-  # +Process.spawn+ / +Open3.*+ / +system+ / backticks anywhere in
-  # +lib/+ are bugs. The convention is grep-enforceable:
-  # +grep -rnE 'Process\.spawn|Open3\.|\bsystem\(' lib/+ should
-  # only hit this file (plus the comment in
-  # +pikuri-mcp/lib/pikuri/mcp/servers.rb+ explaining the MCP
-  # exception).
+  # All subprocess spawning in +lib/+ goes through {.spawn}/{.run}; direct
+  # +Process.spawn+ / +Open3.*+ / +system+ / backticks are bugs.
+  # Grep-enforceable: +grep -rnE 'Process\.spawn|Open3\.|\bsystem\(' lib/+
+  # should hit only this file (plus the MCP-exception comment in
+  # +pikuri-mcp/lib/pikuri/mcp/servers.rb+).
   #
   # == Timeouts are the caller's job
   #
-  # {.spawn} does not implement a timeout — Ruby's +Timeout.timeout+
-  # cannot kill subprocesses cleanly. Callers that need a timeout
-  # wrap their argv with coreutils' +timeout+ binary:
+  # {.spawn} implements no timeout — Ruby's +Timeout.timeout+ can't kill
+  # subprocesses cleanly. Callers wrap their argv with coreutils' +timeout+:
   #
   #   Pikuri::Subprocess.spawn(
   #     'timeout', '--signal=TERM', '--kill-after=5s', '120s',
-  #     'bash', '-c', command,
-  #     chdir: workspace.cwd.to_s
-  #   )
+  #     'bash', '-c', command, chdir: workspace.cwd.to_s)
   #
-  # When +timeout+ and its FD-inheriting children die, the combined
-  # output pipe closes and {#wait}'s +io.read+ returns. No Ruby-side
-  # timeout machinery; the +timeout+ binary handles SIGTERM-then-
-  # SIGKILL race-free.
+  # When +timeout+ and its FD-inheriting children die, the output pipe closes
+  # and {#wait}'s +io.read+ returns — +timeout+ handles the
+  # SIGTERM-then-SIGKILL race-free, no Ruby-side machinery.
   #
   # == Backgrounded subprocesses
   #
-  # When a shell command backgrounds work with +&+, the resulting
-  # process stays in our pgroup. {#wait} returns as soon as the
-  # direct child exits, but {.active} keeps the pgid in the tracked
-  # set as long as any process in the group is alive (probed with
-  # +kill(0, -pgid)+). On pikuri exit, {.cleanup!} sends SIGTERM to
-  # every tracked group. The model can opt out via +nohup cmd &+ or
-  # +setsid cmd &+ — both detach from our group.
+  # A command that backgrounds work with +&+ leaves a process in our pgroup.
+  # {#wait} returns when the direct child exits, but {.active} keeps the pgid
+  # tracked while any group member is alive (+kill(0, -pgid)+); {.cleanup!}
+  # SIGTERMs every tracked group at exit. The model opts out with +nohup+ /
+  # +setsid+ (both detach from our group).
   #
   # == State is process-global
   #
-  # One +@active+ Set for the whole process, swept once at exit via
-  # {Pikuri::Finalizers} (see the registration at the bottom of this
-  # file). A +Mutex+ guards register/prune/cleanup; v1 is
-  # single-threaded, so this is more for the exit-sweep/register race
-  # than for current callers.
-  #
-  # == Why +Pikuri::Subprocess+, not top-level
-  #
-  # First class actually under the +Pikuri::+ namespace. Domain
-  # classes (+Tool+, +Agent+, +URLCache+) are top-level as a legacy
-  # convention — they predate the namespacing decision and an
-  # eventual refactor moves them too. For now: library-level
-  # infrastructure under +Pikuri::+; domain objects flat. See
-  # +CLAUDE.md+ for the convention.
+  # One +@active+ Set for the process, swept once at exit via
+  # {Pikuri::Finalizers}. A +Mutex+ guards register/prune/cleanup.
   class Subprocess
     # Combined output + exit status, returned from {#wait}.
     Result = Data.define(:output, :status)
 
-    # Spawn +argv+ in a new process group, redirecting stderr onto
-    # stdout. Tracked for cleanup.
+    # Spawn +argv+ in a new process group with stderr on stdout. Tracked for
+    # cleanup.
     #
-    # @param argv [Array<String>] command and arguments. Caller does
-    #   any shell wrapping (e.g. +'bash', '-c', cmd+) when shell
-    #   interpretation is wanted; +argv+ is passed to +exec+
-    #   directly, so no implicit shell expansion happens here.
+    # @param argv [Array<String>] command + arguments, passed to +exec+
+    #   directly — no implicit shell (caller wraps in +'bash', '-c', cmd+ when
+    #   shell interpretation is wanted).
     # @param chdir [String, Pathname] working directory
-    # @param env [Hash{String=>String}] extra environment variables to
-    #   set in the child process. The child otherwise inherits the
-    #   parent's full environment; entries in +env+ override or add to
-    #   it. Default +{}+ (pure inheritance). Used by {Code::Bash} to
-    #   thread {Pikuri::Workspace::Filesystem#env} (host git identity,
-    #   etc.) into a bash subprocess whose sandbox would otherwise
-    #   strip the host's config files.
-    # @return [Subprocess] handle — call {#wait} to block for the
-    #   direct child to exit and read the captured output
+    # @param env [Hash{String=>(String,nil)}] extra env vars for the child; it
+    #   otherwise inherits the parent's full environment (default +{}+, pure
+    #   inheritance). A +nil+ value *unsets* that variable, which is how
+    #   {Pikuri::BundlerEnv} hands back the environment pikuri's own boot
+    #   rewrote.
+    # @return [Subprocess] handle — call {#wait} to block and read output.
     def self.spawn(*argv, chdir:, env: {})
       stdin, io, wait_thr = Open3.popen2e(env, *argv, chdir: chdir.to_s, pgroup: true)
       stdin.close
@@ -93,43 +68,32 @@ module Pikuri
       new(io: io, wait_thr: wait_thr)
     end
 
-    # Run +argv+ as a one-shot *filter*: feed it +stdin_data+, redirect
-    # its stdout straight to +stdout+ (an open +File+), capture stderr
-    # through a pipe, and block until it exits. Built for the
-    # stdin→markdown document converters (pikuri-extractors), where
-    # {.spawn}'s shape is wrong twice over: it closes the child's stdin
-    # immediately, and it merges stderr onto stdout — fatal when stdout
-    # *is* the payload and a converter's warnings would corrupt it.
-    #
-    # Redirecting stdout to a file (not a pipe) is also what makes the
-    # I/O deadlock-free with one writer thread: the child never blocks
-    # writing output, so it keeps draining stdin, while the parent
-    # drains the (low-volume) stderr pipe. The returned
-    # {Result#output} is the captured *stderr* — the diagnostics — not
-    # the payload; the payload is in +stdout+, whose file offset is
-    # shared with the child, so rewind before reading it back.
+    # Run +argv+ as a one-shot *filter*: feed it +stdin_data+, redirect stdout
+    # to +stdout+ (an open +File+), capture stderr through a pipe, block until
+    # it exits. Built for the stdin→markdown converters (pikuri-extractors),
+    # where {.spawn}'s shape is wrong twice: it closes stdin immediately and
+    # merges stderr onto stdout — fatal when stdout *is* the payload.
     #
-    # Same discipline as {.spawn}: new process group, registered for
-    # the exit sweep, no built-in timeout (wrap +argv+ with coreutils'
-    # +timeout+ — see the class docs).
+    # Redirecting stdout to a file (not a pipe) is what makes the I/O
+    # deadlock-free with one writer thread: the child never blocks on output,
+    # so it keeps draining stdin while the parent drains the low-volume stderr
+    # pipe. {Result#output} is the captured *stderr*, not the payload — the
+    # payload is in +stdout+, whose file offset is shared with the child, so
+    # rewind before reading it back. Same discipline as {.spawn} (new group,
+    # exit-sweep tracked, no built-in timeout).
     #
-    # @param argv [Array<String>] command and arguments, passed to
-    #   +exec+ directly — no implicit shell.
-    # @param stdin_data [String, IO, StringIO] the child's stdin: a
-    #   String is written as-is, an IO is streamed through
-    #   +IO.copy_stream+ (so a large source file never materialises in
-    #   the Ruby heap) and read from its current position. Either way
-    #   stdin is closed (EOF) afterwards. May be empty.
-    # @param stdout [File] open writable file the child's stdout is
-    #   redirected to.
+    # @param argv [Array<String>] command + arguments; no implicit shell.
+    # @param stdin_data [String, IO, StringIO] the child's stdin: a String is
+    #   written as-is, an IO is streamed via +IO.copy_stream+ from its current
+    #   position (so a large file never hits the Ruby heap). Closed (EOF)
+    #   after. May be empty.
+    # @param stdout [File] open writable file stdout is redirected to.
     # @param chdir [String, Pathname] working directory.
-    # @param env [Hash{String=>String}] extra environment variables,
-    #   as for {.spawn}.
-    # @return [Result] +output+ is the captured stderr; +status+ the
-    #   child's exit status.
-    # @raise [SystemCallError] whatever an IO +stdin_data+ raises
-    #   mid-stream (disk error, closed handle) — re-raised here after
-    #   the child has been reaped.
+    # @param env [Hash{String=>String}] extra env vars, as for {.spawn}.
+    # @return [Result] +output+ is the captured stderr; +status+ the exit
+    #   status.
+    # @raise [SystemCallError] whatever an IO +stdin_data+ raises mid-stream,
+    #   re-raised after the child is reaped.
     def self.run(*argv, stdin_data:, stdout:, chdir:, env: {})
       in_r, in_w = IO.pipe
       err_r, err_w = IO.pipe
@@ -169,9 +133,8 @@ module Pikuri
     #   child was spawned with +pgroup: true+ (it's the group leader).
     attr_reader :pgid
 
-    # @return [IO] read end of the combined stdout+stderr pipe.
-    #   Exposed for future live-streaming consumers; v1 callers go
-    #   straight to {#wait}, which drains it.
+    # @return [IO] read end of the combined stdout+stderr pipe. Callers
+    #   normally go straight to {#wait}, which drains it.
     attr_reader :io
 
     # @api private — call {.spawn}, not the constructor.
@@ -182,10 +145,9 @@ module Pikuri
       @pgid     = wait_thr.pid # pgroup:true → pgid == pid
     end
 
-    # Block until the direct child exits, read whatever remains on
-    # the combined-output pipe, return a {Result}. The pgid stays
-    # tracked if the group still has live members (backgrounded
-    # children); pruned if everything's gone.
+    # Block until the direct child exits, drain the combined-output pipe,
+    # return a {Result}. The pgid stays tracked if the group still has live
+    # members (backgrounded children); pruned if everything's gone.
     #
     # @return [Result]
     def wait
@@ -196,13 +158,11 @@ module Pikuri
       self.class.send(:prune, @pgid)
     end
 
-    # SIGTERM the whole process group without blocking for output —
-    # the stop button for a *daemon* child (one the caller never
-    # {#wait}s on, e.g. {Pikuri::Memory::Mem0Server}'s socat relay).
-    # Best-effort and idempotent: an already-dead group is a no-op.
-    # The group stays in the exit-sweep set until it actually dies,
-    # so a child that ignores SIGTERM is still re-signalled by
-    # {.cleanup!} at process exit.
+    # SIGTERM the whole process group without blocking for output — the stop
+    # button for a *daemon* child (one the caller never {#wait}s on, e.g.
+    # {Pikuri::Memory::Mem0Server}'s socat relay). Best-effort and idempotent;
+    # the group stays in the exit-sweep set until it dies, so a child ignoring
+    # SIGTERM is re-signalled by {.cleanup!} at exit.
     #
     # @return [void]
     def terminate
@@ -214,9 +174,8 @@ module Pikuri
     end
 
     class << self
-      # Currently-tracked process groups, with dead ones pruned as a
-      # side effect. Useful for a future +/bg+ REPL command or a
-      # between-turn status line.
+      # Currently-tracked process groups, with dead ones pruned as a side
+      # effect.
       #
       # @return [Array<Integer>]
       def active
@@ -227,8 +186,7 @@ module Pikuri
       end
 
       # SIGTERM every tracked process group. Run at process exit via
-      # {Pikuri::Finalizers} (production) and from +after+ blocks
-      # (specs). Best-effort — ignores errors from already-dead groups.
+      # {Pikuri::Finalizers}, and from specs' +after+ blocks. Best-effort.
       #
       # @return [void]
       def cleanup!
@@ -261,10 +219,8 @@ module Pikuri
   end
 end
 
-# Registered at load (boot) — before any agent or server registers at
-# construction time — so in {Pikuri::Finalizers}' LIFO sweep this runs
-# LAST: graceful +#close+ on agents and servers first, then SIGTERM
-# whatever child groups are still alive. The reaper, not a peer. (Was a
-# standalone +at_exit+; routed through Finalizers so the order relative
-# to every other teardown is controlled, not left to file load order.)
+# Registered at load (boot) — before any agent/server registers at
+# construction — so in {Pikuri::Finalizers}' LIFO sweep this runs LAST:
+# graceful +#close+ on agents and servers first, then SIGTERM whatever child
+# groups remain. The reaper, not a peer.
 Pikuri::Finalizers.register { Pikuri::Subprocess.cleanup! }

data/lib/pikuri/testing.rb

@@ -0,0 +1,296 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'faraday'
+
+module Pikuri
+  # Test support: run the **real** {Pikuri::Agent} (real +run_loop+, real
+  # listeners, real tools/extensions, real +Event+ stream, real ruby_llm loop)
+  # against a **scripted HTTP backend** — no server, no network, no mock agent.
+  #
+  # Not loaded by default: +require 'pikuri/testing'+ from a spec. It lives off
+  # the production load path (the core Zeitwerk loader ignores it).
+  #
+  # == How it works
+  #
+  # {.fake_transport} returns an ordinary {Agent::ChatTransport} whose
+  # +faraday_adapter+ is an anonymous +Faraday::Adapter+ serving the responses
+  # you scripted. Because {Agent#build_context} installs that adapter on the
+  # agent's *per-chat* +RubyLLM::Context+ (never the global +RubyLLM.config+),
+  # ruby_llm's own loop runs for real — it parses tool calls, invokes your real
+  # registered tools, appends observations, and re-requests — and each scripted
+  # entry is the model's next turn. No hand-rolled agent loop, nothing to drift
+  # against a ruby_llm upgrade.
+  #
+  #   require 'pikuri/testing'
+  #
+  #   transport = Pikuri::Testing.fake_transport do |llm|
+  #     llm.tool_call('calculator', expression: '2 + 2') # turn 1: call a real tool
+  #     llm.reply('The answer is 4.')                     # turn 2: final answer
+  #   end
+  #
+  #   agent = Pikuri::Agent.new(transport:, system_prompt: 'test') do |c|
+  #     c.add_listener capture
+  #     c.add_tool Pikuri::Tool::CALCULATOR
+  #   end
+  #   agent.run_loop(user_message: 'What is 2 + 2?')
+  #   # the real loop ran the real calculator; capture saw ToolCall/ToolResult/Assistant
+  #
+  # == Limitations
+  #
+  # A fake transport feeds **one ordered response list**. Propagation to
+  # sub-agents / the synthesizer works (they derive their transport via
+  # +parent.transport.with(...)+, and +Data#with+ preserves the adapter), but
+  # they *share* that one list — fine for a single linear script, not for
+  # targeting a specific sub-agent's replies. Per-sub-agent scripting is a
+  # future upgrade (dispatch by model id / distinct fake +api_base+).
+  # Tool-call *streaming* (fragmented +tool_calls+ deltas) is not modelled;
+  # {Script#stream} streams text only.
+  module Testing
+    # Build a fake transport from a scripted conversation. Pass a block that
+    # calls {Script} verbs in the order the model should "reply"; each verb
+    # queues one HTTP response.
+    #
+    # @example a two-turn tool loop
+    #   Pikuri::Testing.fake_transport do |llm|
+    #     llm.tool_call('calculator', expression: '2 + 2')
+    #     llm.reply('The answer is 4.')
+    #   end
+    #
+    # @param model [String] model id the fake reports (any string; the fake
+    #   server "knows" it)
+    # @param context_window [Integer] baked onto the transport so
+    #   {Agent#detect_and_emit_context_cap!} skips the real +/props+ HTTP probe
+    # @param api_base [String] the transport's base URL. Never dialed (the
+    #   adapter answers), but a host may key display/config off it — pass the
+    #   base of the connection this fake impersonates so a UI resolves its name.
+    # @param gate [Gate, nil] a latch to hold turns open mid-flight. When
+    #   engaged ({Gate#block!}), the adapter parks before serving each response
+    #   until {Gate#release!} — so a test can observe spinner / queued-injection
+    #   / Ctrl+C paths through the real turn lifecycle. Default +nil+ (no gating).
+    # @yieldparam script [Script] the conversation builder
+    # @return [Agent::ChatTransport] carrying the scripted adapter; pass it as
+    #   +Agent.new(transport:)+
+    def self.fake_transport(model: 'fake-model', context_window: 8192,
+                            api_base: 'http://fake.invalid/v1', gate: nil)
+      script = Script.new
+      yield script if block_given?
+      Agent::ChatTransport.new(
+        model: model,
+        provider: :openai,
+        assume_model_exists: true,
+        # An api_base forces the connection-override path (Context#chat), the
+        # only branch that honours faraday_adapter; the host is never dialed.
+        api_base: api_base,
+        api_key: 'not-needed',
+        context_window: context_window,
+        faraday_adapter: build_adapter(script.responses, gate)
+      )
+    end
+
+    # An anonymous +Faraday::Adapter+ subclass that serves +responses+ in order,
+    # one per HTTP request. Closes over the (mutable) list, so the queue drains
+    # across the several requests of one conversation regardless of how Faraday
+    # reuses adapter instances.
+    #
+    # @param responses [Array<Hash>] entries shaped +{json: Hash}+ (non-stream)
+    #   or +{sse: Array<String>}+ (stream), as {Script} produces
+    # @param gate [Gate, nil] awaited before each response when non-nil
+    # @return [Class] a +Faraday::Adapter+ subclass
+    def self.build_adapter(responses, gate = nil)
+      queue = responses # captured by reference; #call shifts from it
+      Class.new(Faraday::Adapter) do
+        # +define_method+ (not +def+) so the body closes over +queue+/+gate+;
+        # +super+ must be explicit here (implicit super is illegal in a
+        # define_method).
+        define_method(:call) do |env|
+          super(env) # base builds env.response; skipping it → "finish for nil"
+          gate&.await # park here while the test holds the turn open
+          entry = queue.shift or raise "Pikuri::Testing: no scripted response left for #{env.url}"
+
+          if env.request.stream_response? # ruby_llm set req.options.on_data
+            # v2 on_data routes to the chunk handler only at status 200; set it
+            # before feeding, mirroring how a real adapter reads the status line
+            # ahead of the body.
+            env.status = 200
+            on_data = env.request.on_data
+            size = 0
+            entry.fetch(:sse).each do |chunk|
+              size += chunk.bytesize
+              on_data.call(chunk, size, env)
+            end
+            save_response(env, 200, '', { 'Content-Type' => 'text/event-stream' }, nil)
+          else
+            save_response(env, 200, JSON.generate(entry.fetch(:json)),
+                          { 'Content-Type' => 'application/json' }, nil)
+          end
+          @app.call(env)
+        end
+      end
+    end
+
+    # Collects the scripted conversation: each verb appends one OpenAI-wire
+    # response body to {#responses}, in call order. You don't build these
+    # directly — {Testing.fake_transport} yields one to your block.
+    #
+    #   fake_transport do |llm|
+    #     llm.reply('hi')                                  # plain answer
+    #     llm.tool_call('calculator', expression: '2+2')   # a tool turn
+    #     llm.stream('The ', 'answer ', 'is ', '4.')       # a streamed answer
+    #   end
+    class Script
+      # @return [Array<Hash>] queued response entries in call order
+      attr_reader :responses
+
+      def initialize
+        @responses = []
+        @tool_call_seq = 0
+      end
+
+      # Queue a plain assistant-text turn (the model's final answer for that
+      # step).
+      #
+      # @param text [String] the assistant message content
+      # @return [self]
+      def reply(text)
+        @responses << { json: assistant_body(content: text) }
+        self
+      end
+
+      # Queue an assistant turn that calls one tool. The real ruby_llm loop
+      # parses it, runs the real registered tool, appends the observation, and
+      # re-requests — so the *next* queued entry is the model's follow-up.
+      #
+      # @example
+      #   llm.tool_call('calculator', expression: '2 + 2')
+      #
+      # @param name [String] registered tool name (e.g. +"calculator"+)
+      # @param arguments [Hash{Symbol => Object}] tool arguments, JSON-encoded
+      #   into the wire call
+      # @return [self]
+      def tool_call(name, **arguments)
+        tool_batch([name, arguments])
+      end
+
+      # Queue an assistant turn that calls several tools at once — one
+      # +tool_calls+ array, the shape a provider sends when the model batches.
+      # ruby_llm runs them in order, each answered by its own +:tool+ message.
+      #
+      #   llm.tool_batch(['calculator', { expression: '1 + 1' }],
+      #                  ['calculator', { expression: '2 + 2' }])
+      #
+      # What a spec needs to exercise anything treating a batch as a unit — the
+      # interloper's drain boundary, or which call a mid-batch unwind blames.
+      #
+      # @param calls [Array<Array(String, Hash)>] +[name, arguments]+ pairs, in
+      #   the order the model asked for them
+      # @return [self]
+      def tool_batch(*calls)
+        wire = calls.map do |name, arguments|
+          @tool_call_seq += 1
+          { 'id' => "call_#{@tool_call_seq}", 'type' => 'function',
+            'function' => { 'name' => name, 'arguments' => JSON.generate(arguments || {}) } }
+        end
+        @responses << { json: assistant_body(content: nil, tool_calls: wire) }
+        self
+      end
+
+      # Queue a *streamed* assistant-text turn: each +delta+ becomes one SSE
+      # chunk, so a +streaming: true+ agent emits a matching sequence of
+      # {Agent::Event::AssistantDelta}s and a final assembled
+      # {Agent::Event::Assistant}. Text only — tool-call streaming is not
+      # modelled.
+      #
+      # @example
+      #   llm.stream('The ', 'answer ', 'is ', '4.')
+      #
+      # @param deltas [Array<String>] content fragments, streamed in order
+      # @return [self]
+      def stream(*deltas)
+        chunks = deltas.map do |d|
+          "data: #{JSON.generate('model' => 'fake', 'choices' => [{ 'delta' => { 'content' => d } }])}\n\n"
+        end
+        chunks << "data: #{JSON.generate('model' => 'fake', 'choices' => [{ 'delta' => {} }],
+                                          'usage' => usage)}\n\n"
+        chunks << "data: [DONE]\n\n"
+        @responses << { sse: chunks }
+        self
+      end
+
+      private
+
+      # One OpenAI chat-completion body: an assistant message, optionally with
+      # +tool_calls+.
+      #
+      # @param content [String, nil]
+      # @param tool_calls [Array<Hash>, nil]
+      # @return [Hash]
+      def assistant_body(content:, tool_calls: nil)
+        message = { 'role' => 'assistant', 'content' => content }
+        message['tool_calls'] = tool_calls if tool_calls
+        { 'model' => 'fake', 'choices' => [{ 'message' => message }], 'usage' => usage }
+      end
+
+      # Nominal token counts so a {Agent::Event::Tokens} still fires.
+      #
+      # @return [Hash{String => Integer}]
+      def usage
+        { 'prompt_tokens' => 10, 'completion_tokens' => 5, 'total_tokens' => 15 }
+      end
+    end
+
+    # A latch that holds a fake turn open mid-flight. Pass one to
+    # {Testing.fake_transport}; the adapter parks (inside the HTTP call, on the
+    # agent's worker thread) at every response while the gate is engaged, so a
+    # test can observe the turn-in-progress state — spinner, queued injections,
+    # a Ctrl+C landing mid-turn — then let it finish.
+    #
+    #   gate = Pikuri::Testing::Gate.new
+    #   transport = Pikuri::Testing.fake_transport(gate:) { |llm| llm.stream('done') }
+    #   gate.block!
+    #   session.submit('work')          # the real turn parks in the adapter
+    #   # ... assert spinner / press Ctrl+C ...
+    #   gate.release!                    # the turn proceeds and completes
+    #
+    # A test that engages the gate is responsible for releasing it —
+    # {#await} blocks with no timeout, mirroring the old stubs' +Queue#pop+.
+    #
+    # Thread-safe.
+    class Gate
+      def initialize
+        @mutex = Mutex.new
+        @cv = ConditionVariable.new
+        @blocked = false
+      end
+
+      # Engage the latch: the *next* (and every subsequent) response parks in
+      # {#await} until {#release!}.
+      #
+      # @return [void]
+      def block!
+        @mutex.synchronize { @blocked = true }
+        nil
+      end
+
+      # Disengage the latch and wake every parked response.
+      #
+      # @return [void]
+      def release!
+        @mutex.synchronize do
+          @blocked = false
+          @cv.broadcast
+        end
+        nil
+      end
+
+      # Block the calling thread while the latch is engaged. Called by the
+      # adapter before serving each response; a no-op when not blocked.
+      #
+      # @return [void]
+      def await
+        @mutex.synchronize { @cv.wait(@mutex) while @blocked }
+        nil
+      end
+    end
+  end
+end