bitfab 0.51.1 → 0.51.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3dd6fa16ae3ff5f26d94f6b86f9fa702129cfb502e3f94b293e383d107d1c0de
-  data.tar.gz: 220cdb686e1a5522fdcd9579e897f60b0896360583b49615006f0489723c6d21
+  metadata.gz: 571e505294f7f5abe3b1d4c8521c4427cf30c105e03eb87509e70dd929559f43
+  data.tar.gz: 2a39fa504e22027f19a845efb156fb6a7c38d4a1187b7df64dad1623b5cccb4b
 SHA512:
-  metadata.gz: cf75d4072ac82e17312f40f86c1a0e54c3a60a019818695507a5d53cfc1bfb15db6e705ad6a971c6e77abd67b4b752e180457d483b5f42becc52167323784dd9
-  data.tar.gz: 8857e35745377b128479948ec4622ef2223f3876015f03e161ac80e43f61ec1c1556cb4d4839dd174c35afba9b3e1fbfcbd0c4da69766b80cd593cd8caf96c07
+  metadata.gz: e4146889a3a1f02b3bca7a104810067d59ec1e138cd099dc4822d241bcf34a6cb1514535d0bb902628e18a990bb31b5b1c79074cb946bdae7416bad3121a877c
+  data.tar.gz: ab9ab7427fb6065d4a6c1748b780a60d12b70302971b474927741653da400f60deb8a739addb5eb60ef79e7e9c791922538c86cbe53f163a1eb69c4dd175b87b

data/README.md

@@ -215,6 +215,51 @@ end
 #       └─ check_fraud (grandchild)
 ```
 
+### Experimental Subtree Tracing
+
+Use `bitfab_trace` to record a root method and every first-party Ruby method it calls without wrapping each descendant:
+
+```ruby
+class OrderPipeline
+  include Bitfab::Traceable
+  bitfab_function "order-pipeline"
+
+  bitfab_trace :process, type: "agent"
+  def process(order_id)
+    validate(order_id)
+  end
+
+  def validate(order_id)
+    { order_id:, valid: true }
+  end
+end
+```
+
+Capture uses `TracePoint` only during the root call. It skips Ruby/runtime code, dependency gems, Bitfab SDK internals, blocks, lambdas, and forwarding wrappers. When the root belongs to an installed application gem, that gem is the first-party boundary; neighboring dependency gems remain excluded. It follows recursion, modules, inheritance, `define_method`, and same-thread child Fibers; aliases are recorded and excluded by the name that was invoked. Child Fibers created during capture inherit node policies, trace identity, parenting, and depth limits while retaining separate call stacks. Pre-existing Fibers, `Fiber.new(storage: nil)`, and child threads do not inherit subtree context. When an inner capture ends, child Fibers retain any still-active outer capture; inherited context expires once all enclosing captures end. While a root remains active, hitting `max_spans` stops new capture but allows already-open spans in every Fiber to finish. `max_depth:`, `max_spans:`, `exclude:`, and `include_wrappers:` control the subtree. Automatically captured calls are not replay mock targets. Declare a call with `bitfab_span` when replay must substitute it: its explicit span records once, and automatic descendants continue beneath it.
+
+When capture ends, already-open automatic calls in suspended Fibers are emitted once with a nil output and `Subtree capture ended before the call returned` as the error, unless a real error was already observed. Their inputs and parenting are retained. The SDK does not resume Fibers, and later resumption cannot add spans to the ended capture. If hot reload moves the root to an unresolved source, the last valid first-party boundary and its exclusions remain in use.
+
+Returning an `Enumerator` keeps capture pending until iteration finishes or raises, including calls already paused in child Fibers. Capture is inactive between the initial return and consumption. Automatic spans record lazy return values as placeholders without iterating them; the traced root records the yielded values.
+
+A nested `bitfab_trace` with a different key starts an independent trace while the outer trace continues recording the overlapping subtree. Both traces have distinct trace and span IDs, including during replay, and the complete structure each root would record alone, so two active roots double span volume in their shared region. A recursive call or nested annotation using the same key stays in the active trace instead of creating another root.
+
+Configure a discovered method with `bitfab_node`. A node never creates a span or trace by itself; the active `bitfab_trace` owns its key, limits, parent, and lifecycle:
+
+```ruby
+bitfab_node :summarize,
+  name: "Model call",
+  type: "llm",
+  mock_on_replay: true,
+  finalize: ->(response) { {text: response.text} }
+def summarize(order)
+  model.generate(order)
+end
+```
+
+Nodes support `name:`, `type:`, `capture:`, `test_run_id:`, `mock_on_replay:`, and `finalize:`. `capture: false` omits the method while attaching captured descendants to its nearest visible parent. `finalize:` changes only the recorded output, never the return value. A finalizer failure is recorded on the node without crashing the caller. The before-`def`, inline, and after-`def` forms all preserve method visibility. For external code, use `Bitfab.client.node(MyClass, :method)`.
+
+`bitfab_trace` prepares its project boundary and exclusions when the method is declared, refreshes the boundary if the root definition moves during hot reload, caches canonical source paths, and shares one `TracePoint` dispatcher across active roots on the calling thread. After `max_spans` is exhausted, it stops collecting metadata and values immediately, then stops processing events for that session once its captured calls finish. Each active root still captures and serializes its own copy of every overlapping call, so this remains a discovery tool rather than the production default. Prefer explicit `bitfab_span` declarations on hot paths. Run `mise exec -- ruby -Ilib benchmark/subtree.rb` from this package to measure the no-network caller path on your Ruby build.
+
 ### Input/Output Capture
 
 Positional and keyword arguments are automatically captured:
@@ -399,6 +444,8 @@ batch is never re-encoded to measure its size. If Bitfab accepts only part of a
 the standard OTLP `partialSuccess` response and the SDK warns with the rejected-span count and
 reason.
 
+Every root trace also records the commit its code ran at as `commit_ref`. Deploy platforms such as Vercel, GitHub Actions, Railway, Render, Heroku, Cloudflare Pages, GitLab CI, Azure Pipelines, and CircleCI supply it through their build variables, a plain checkout resolves it from `git` once per process in the background, and a container built without either should set `BITFAB_COMMIT_SHA` at build time. Set `BITFAB_DISABLE_COMMIT_REF` to send no `commit_ref` at all.
+
 Before finalizing a replay, the SDK flushes OTel and polls Bitfab's replay-status API until every
 expected trace completion and span count is persisted.
 
@@ -425,6 +472,10 @@ See [bitfab-ruby-example/](../bitfab-ruby-example/) for complete working example
 
 - [test_span.rb](../bitfab-ruby-example/scripts/test_span.rb) - Basic span creation
 - [test_nested_spans.rb](../bitfab-ruby-example/scripts/test_nested_spans.rb) - Nested span hierarchies
+- [test_subtree.rb](../bitfab-ruby-example/scripts/test_subtree.rb) - Whole-subtree capture with independent overlapping roots
+- [test_subtree_comprehensive.rb](../bitfab-ruby-example/scripts/test_subtree_comprehensive.rb) - Self-checking subtree and node behavior examples, including child-Fiber context and installed application gems
+- [test_subtree_replay.rb](../bitfab-ruby-example/scripts/test_subtree_replay.rb) - Live subtree record and replay
+- [subtree coverage map](../bitfab-ruby-example/subtree_examples/README.md) - Every subtree spec behavior mapped to its runnable example
 - [test_wrap.rb](../bitfab-ruby-example/scripts/test_wrap.rb) - Wrapping external code
 - [test_enabled.rb](../bitfab-ruby-example/scripts/test_enabled.rb) - Using the enabled flag
 - [test_metadata.rb](../bitfab-ruby-example/scripts/test_metadata.rb) - Custom metadata

data/lib/bitfab/client.rb

@@ -7,6 +7,7 @@ require_relative "constants"
 require_relative "http_client"
 require_relative "replay"
 require_relative "span_context"
+require_relative "subtree"
 require_relative "serialize"
 require_relative "timestamp"
 require_relative "warn_once"
@@ -51,6 +52,7 @@ module Bitfab
       # replay on this client (after any per-call mock_override). Instance
       # state, no global; clear_mock_overrides resets it.
       @mock_overrides = []
+      CommitRef.start_resolution
     end
 
     # The configured API key (a proc is resolved on read). Reflects what was
@@ -302,6 +304,23 @@ module Bitfab
       BitfabFunction.new(self, trace_function_key)
     end
 
+    # Configure an existing method only when it is discovered beneath a
+    # bitfab_trace root owned by this client.
+    def node(klass, method_name, name: nil, type: "custom", capture: true,
+      test_run_id: nil, mock_on_replay: false, finalize: nil)
+      Bitfab::Traceable.node(
+        klass,
+        method_name,
+        name:,
+        type:,
+        capture:,
+        test_run_id:,
+        mock_on_replay:,
+        finalize:,
+        client: self
+      )
+    end
+
     # Fetch one persisted span without loading the full trace.
     # Exactly one of id or name is required. Name lookups return the last
     # matching span by default; occurrence also accepts "first" or a zero-based
@@ -326,7 +345,8 @@ module Bitfab
     # Execute a block inside a span context, sending trace data on completion.
     # Called by Traceable, not intended for direct use.
     def execute_span(trace_function_key:, span_name:, span_type:, function_name:, args:, kwargs:,
-      capture_when: "always", mock_on_replay: false)
+      capture_when: "always", mock_on_replay: false, independent_root: false,
+      explicit_span_receiver: nil, explicit_span_method_name: nil, test_run_id: nil, finalize: nil)
       # Decide at CALL time, not construction. The key may be set after the
       # client is built (env loaded later), so re-checking per call lets a
       # late-resolved key take effect.
@@ -358,13 +378,24 @@ module Bitfab
       resolved_input_source_span_id = nil
       begin
         replay_ctx = ReplayContext.current
-        parent = SpanContext.current || ReplayContext.current_span
-        trace_id = parent ? parent[:trace_id] : (replay_ctx&.dig(:trace_id) || SecureRandom.uuid)
+        # A subtree annotation declares a trace-function root, even when it is
+        # invoked inside another span. Outer subtree sessions keep observing it
+        # through TracePoint instead of owning this root span.
+        ambient_parent = SpanContext.current || ReplayContext.current_span
+        parent = independent_root ? nil : ambient_parent
+        if parent && (subtree_parent_span_id = Subtree.current_parent_span_id(parent[:trace_id]))
+          parent = parent.merge(span_id: subtree_parent_span_id)
+        end
+        trace_id = if independent_root && ambient_parent
+          SecureRandom.uuid
+        else
+          parent&.dig(:trace_id) || replay_ctx&.dig(:trace_id) || SecureRandom.uuid
+        end
         span_id = SecureRandom.uuid
         parent_span_id = parent&.dig(:span_id)
         is_root_span = parent_span_id.nil?
         started_at = Bitfab.now_iso_timestamp
-        resolved_test_run_id = replay_ctx&.dig(:test_run_id)
+        resolved_test_run_id = replay_ctx ? replay_ctx[:test_run_id] : test_run_id
         resolved_input_source_span_id = replay_ctx&.dig(:input_source_span_id)
         resolved_input_source_trace_id = replay_ctx&.dig(:input_source_trace_id)
 
@@ -438,18 +469,28 @@ module Bitfab
       error = nil
       span_contexts = nil
       span_prompt = nil
-      finalized = false
+      completed = false
 
-      finalize = lambda do |final_result, final_error|
+      complete = lambda do |final_result, final_error|
         # Never crash the host app due to span building/sending. Idempotent:
         # only the first call sends the span. Subsequent calls (e.g. from the
         # enumerator wrapper after iteration completes) are no-ops.
-        next if finalized
+        next if completed
 
-        finalized = true
+        completed = true
 
         begin
           ended_at = Bitfab.now_iso_timestamp
+          recorded_result = final_result
+          recorded_error = final_error
+          if finalize && final_error.nil?
+            begin
+              recorded_result = finalize.call(final_result)
+            rescue => e
+              recorded_result = nil
+              recorded_error = "finalize failed: #{e.message}"
+            end
+          end
 
           send_span(
             trace_function_key:,
@@ -463,8 +504,8 @@ module Bitfab
             prompt: span_prompt,
             args:,
             kwargs:,
-            result: final_result,
-            error: final_error,
+            result: recorded_result,
+            error: recorded_error,
             started_at:,
             ended_at:,
             test_run_id: resolved_test_run_id,
@@ -513,8 +554,22 @@ module Bitfab
 
       begin
         ReplayContext.with_span(trace_id:, span_id:) do
-          SpanContext.with_span(trace_id:, span_id:) do
-            result = yield
+          SpanContext.with_span(
+            trace_id:,
+            span_id:,
+            explicit_span_receiver:,
+            explicit_span_method_name: explicit_span_method_name&.to_sym
+          ) do
+            result = if explicit_span_receiver
+              Subtree.with_borrowed_span(
+                trace_id:,
+                span_id:,
+                receiver: explicit_span_receiver,
+                method_name: explicit_span_method_name
+              ) { yield }
+            else
+              yield
+            end
           ensure
             # Capture contexts before the span context is popped
             span_contexts = SpanContext.current&.dig(:contexts)
@@ -523,7 +578,7 @@ module Bitfab
         end
       rescue => e
         error = e.message
-        finalize.call(result, error)
+        complete.call(result, error)
         raise
       end
 
@@ -541,10 +596,17 @@ module Bitfab
       # once iteration completes (or errors).
       #
       if result.is_a?(Enumerator)
-        return wrap_enumerator(result, trace_id:, span_id:, finalize:)
+        return wrap_enumerator(
+          result,
+          trace_id:,
+          span_id:,
+          complete:,
+          explicit_span_receiver:,
+          explicit_span_method_name:
+        )
       end
 
-      finalize.call(result, error)
+      complete.call(result, error)
       result
     end
 
@@ -605,8 +667,13 @@ module Bitfab
     # callbacks nest under the parent span. Yielded values are collected as the
     # span output. The span is sent exactly once: when iteration finishes,
     # raises, or the wrapper is `.close`d.
-    def wrap_enumerator(source, trace_id:, span_id:, finalize:)
+    def wrap_enumerator(source, trace_id:, span_id:, complete:, explicit_span_receiver: nil,
+      explicit_span_method_name: nil)
       span_entry = {trace_id:, span_id:}
+      if explicit_span_receiver
+        span_entry[:explicit_span_receiver] = explicit_span_receiver
+        span_entry[:explicit_span_method_name] = explicit_span_method_name&.to_sym
+      end
       yielded = []
 
       Enumerator.new do |yielder|
@@ -618,13 +685,26 @@ module Bitfab
           SpanContext.with_fiber_bridge(trace_id:, span_id:) do
             SpanContext.stack.push(span_entry)
             begin
-              source.each do |value|
-                yielded << value
-                yielder << value
+              iterate = lambda do
+                source.each do |value|
+                  yielded << value
+                  yielder << value
+                end
+              end
+              if explicit_span_receiver
+                Subtree.with_borrowed_span(
+                  trace_id:,
+                  span_id:,
+                  receiver: explicit_span_receiver,
+                  method_name: explicit_span_method_name,
+                  &iterate
+                )
+              else
+                iterate.call
               end
-              finalize.call(yielded, nil)
+              complete.call(yielded, nil)
             rescue => e
-              finalize.call(yielded, e.message)
+              complete.call(yielded, e.message)
               raise
             ensure
               SpanContext.stack.pop
@@ -673,6 +753,8 @@ module Bitfab
       if trace_state&.dig(:db_snapshot_ref)
         raw_trace["db_snapshot_ref"] = trace_state[:db_snapshot_ref]
       end
+      commit_ref = CommitRef.current
+      raw_trace["commit_ref"] = commit_ref if commit_ref
       if db_snapshot_usage
         usage = {"neon_branch_id" => db_snapshot_usage[:neon_branch_id]}
         if db_snapshot_usage[:snapshot_timestamp]
@@ -1006,5 +1088,22 @@ module Bitfab
         client: @client
       )
     end
+
+    # Experimentally trace an existing method and its first-party call subtree.
+    def trace(klass, method_name, name: nil, type: "custom",
+      max_depth: Subtree::DEFAULT_MAX_DEPTH, max_spans: Subtree::DEFAULT_MAX_SPANS,
+      exclude: [], include_wrappers: false)
+      Bitfab::Traceable.trace(
+        klass, method_name,
+        trace_function_key: @trace_function_key,
+        name:,
+        type:,
+        max_depth:,
+        max_spans:,
+        exclude:,
+        include_wrappers:,
+        client: @client
+      )
+    end
   end
 end

data/lib/bitfab/commit_ref.rb

@@ -0,0 +1,184 @@
+# frozen_string_literal: true
+
+require "uri"
+require_relative "git_command"
+
+module Bitfab
+  module CommitRef
+    EXPLICIT_SHA_ENV = "BITFAB_COMMIT_SHA"
+    DISABLE_ENV = "BITFAB_DISABLE_COMMIT_REF"
+    GIT_TIMEOUT_SECONDS = 2
+
+    VERCEL_PROVIDER_HOSTS = {
+      "github" => "github.com",
+      "gitlab" => "gitlab.com",
+      "bitbucket" => "bitbucket.org"
+    }.freeze
+
+    PLATFORM_ENVS = [
+      ["VERCEL_GIT_COMMIT_SHA", "VERCEL_GIT_COMMIT_REF", :vercel],
+      ["GITHUB_SHA", "GITHUB_REF_NAME", ["GITHUB_SERVER_URL", "GITHUB_REPOSITORY"]],
+      ["RAILWAY_GIT_COMMIT_SHA", "RAILWAY_GIT_BRANCH", nil],
+      ["RENDER_GIT_COMMIT", "RENDER_GIT_BRANCH", nil],
+      ["SOURCE_VERSION", nil, nil],
+      ["CF_PAGES_COMMIT_SHA", "CF_PAGES_BRANCH", nil],
+      ["CI_COMMIT_SHA", "CI_COMMIT_REF_NAME", ["CI_REPOSITORY_URL"]],
+      ["BUILD_SOURCEVERSION", "BUILD_SOURCEBRANCHNAME", ["BUILD_REPOSITORY_URI"]],
+      ["CIRCLE_SHA1", "CIRCLE_BRANCH", ["CIRCLE_REPOSITORY_URL"]]
+    ].freeze
+
+    REMOTE_ENVS = %w[
+      GITHUB_SERVER_URL GITHUB_REPOSITORY CI_REPOSITORY_URL BUILD_REPOSITORY_URI
+      CIRCLE_REPOSITORY_URL VERCEL_GIT_PROVIDER VERCEL_GIT_REPO_OWNER VERCEL_GIT_REPO_SLUG
+    ].freeze
+
+    ENV_NAMES = ([EXPLICIT_SHA_ENV, DISABLE_ENV] + PLATFORM_ENVS.flat_map { |sha, branch, _| [sha, branch].compact } + REMOTE_ENVS).freeze
+
+    @lock = Mutex.new
+    @resolved = false
+    @ref = nil
+    @git_thread = nil
+
+    module_function
+
+    def read(env, name)
+      return nil if name.nil?
+
+      value = env[name].to_s.strip
+      value.empty? ? nil : value
+    end
+
+    def remote_from_env(env, spec)
+      case spec
+      when :vercel
+        host = VERCEL_PROVIDER_HOSTS[read(env, "VERCEL_GIT_PROVIDER").to_s.downcase]
+        owner = read(env, "VERCEL_GIT_REPO_OWNER")
+        slug = read(env, "VERCEL_GIT_REPO_SLUG")
+        (host && owner && slug) ? "#{host}/#{owner}/#{slug}" : nil
+      when Array
+        parts = spec.map { |name| read(env, name) }
+        parts.all? ? normalize_remote(parts.join("/")) : nil
+      end
+    end
+
+    def normalize_remote(raw)
+      value = raw.to_s.strip
+      return nil if value.empty?
+
+      if value.include?("://")
+        parsed = begin
+          URI.parse(value)
+        rescue URI::InvalidURIError
+          return nil
+        end
+        host = parsed.host.to_s.downcase
+        path = parsed.path.to_s
+      else
+        head, separator, tail = value.partition(":")
+        host = separator.empty? ? "" : head.rpartition("@").last
+        path = separator.empty? ? value : tail
+      end
+      path = path.gsub(%r{\A/+|/+\z}, "")
+      path = path.delete_suffix(".git").sub(%r{/+\z}, "") if path.end_with?(".git")
+      return (path.empty? ? nil : path) if host.empty?
+
+      path.empty? ? host : "#{host}/#{path}"
+    end
+
+    def resolve_from_env(env)
+      explicit = read(env, EXPLICIT_SHA_ENV)
+      platform = PLATFORM_ENVS.find { |sha_env, _, _| read(env, sha_env) }
+      if platform.nil?
+        return nil if explicit.nil?
+
+        return {"sha" => explicit, "branch" => nil, "dirty" => nil, "remote" => nil, "root_sha" => nil}
+      end
+
+      sha_env, branch_env, remote_spec = platform
+      {
+        "sha" => explicit || read(env, sha_env),
+        "branch" => read(env, branch_env),
+        "dirty" => nil,
+        "remote" => remote_from_env(env, remote_spec),
+        "root_sha" => nil
+      }
+    end
+
+    def git(cwd, *args)
+      GitCommand.run(cwd, args, timeout: GIT_TIMEOUT_SECONDS)&.strip
+    end
+
+    def resolve_from_git(cwd)
+      sha = git(cwd, "rev-parse", "HEAD")
+      return nil if sha.nil? || sha.empty?
+
+      branch = git(cwd, "symbolic-ref", "--short", "-q", "HEAD")
+      status = git(cwd, "status", "--porcelain")
+      roots = git(cwd, "rev-list", "--max-parents=0", "HEAD")
+      {
+        "sha" => sha,
+        "branch" => (branch.nil? || branch.empty?) ? nil : branch,
+        "dirty" => status.nil? ? nil : !status.empty?,
+        "remote" => normalize_remote(git(cwd, "remote", "get-url", "origin")),
+        "root_sha" => (roots.nil? || roots.empty?) ? nil : roots.split.min
+      }
+    end
+
+    def start_resolution
+      @lock.synchronize do
+        return if @resolved || @git_thread
+
+        if read(ENV, DISABLE_ENV)
+          @resolved = true
+          return
+        end
+
+        from_env = resolve_from_env(ENV)
+        if from_env
+          @ref = from_env
+          @resolved = true
+          return
+        end
+
+        cwd = begin
+          Dir.pwd
+        rescue SystemCallError
+          @resolved = true
+          return
+        end
+        @git_thread = Thread.new { resolve_git_in_background(cwd) }
+      end
+    end
+
+    def resolve_git_in_background(cwd)
+      ref = resolve_from_git(cwd)
+      @lock.synchronize do
+        unless @resolved
+          @ref = ref
+          @resolved = true
+        end
+      end
+    rescue
+      @lock.synchronize { @resolved = true }
+    end
+
+    def current
+      start_resolution
+      @lock.synchronize { @ref }
+    end
+
+    def settle(timeout = 5)
+      thread = @lock.synchronize { @git_thread }
+      thread&.join(timeout)
+      nil
+    end
+
+    def reset!
+      @lock.synchronize do
+        @ref = nil
+        @resolved = false
+        @git_thread = nil
+      end
+    end
+  end
+end

data/lib/bitfab/git_command.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require "open3"
+
+module Bitfab
+  module GitCommand
+    KILL_GRACE_SECONDS = 1
+
+    module_function
+
+    def run(cwd, args, timeout:)
+      Open3.popen3("git", *args, chdir: cwd, **spawn_options) do |stdin, stdout, stderr, wait_thread|
+        stdin.close
+        out = +""
+        reader = Thread.new { out = read_all(stdout) }
+        drain = Thread.new { read_all(stderr) }
+        finished = wait_thread.join(timeout)
+        stop(wait_thread) unless finished
+        settle(reader, stdout)
+        settle(drain, stderr)
+        (finished && wait_thread.value.success?) ? out.force_encoding("UTF-8").scrub : nil
+      end
+    rescue
+      nil
+    end
+
+    def spawn_options
+      Gem.win_platform? ? {} : {pgroup: true}
+    end
+
+    def kill_target(wait_thread)
+      Gem.win_platform? ? wait_thread.pid : -wait_thread.pid
+    end
+
+    def read_all(io)
+      io.read.to_s
+    rescue
+      ""
+    end
+
+    def settle(thread, io)
+      return if thread.join(KILL_GRACE_SECONDS)
+
+      io.close
+      thread.join
+    end
+
+    def stop(wait_thread)
+      target = kill_target(wait_thread)
+      if Gem.win_platform?
+        signal("KILL", target)
+      else
+        signal("TERM", target)
+        signal("KILL", target) unless wait_thread.join(KILL_GRACE_SECONDS)
+      end
+      wait_thread.join
+    end
+
+    def signal(name, target)
+      Process.kill(name, target)
+    rescue
+      nil
+    end
+  end
+end

data/lib/bitfab/replay.rb

@@ -6,6 +6,7 @@ require "open3"
 require "timeout"
 
 require_relative "constants"
+require_relative "git_command"
 require_relative "mock_override"
 require_relative "serialize"
 require_relative "traceable"
@@ -560,20 +561,7 @@ module Bitfab
     end
 
     def git(cwd, args)
-      # capture3 so git's stderr (e.g. "not a git repository") is swallowed, not
-      # leaked to the host process's console.
-      out, _err, status = Timeout.timeout(30) do
-        Open3.capture3("git", *args, chdir: cwd)
-      end
-      return nil unless status.success?
-
-      # Tag as UTF-8 and scrub invalid bytes so blob contents compare cleanly
-      # against the UTF-8 working-file reads and never break JSON.generate later
-      # (a non-UTF-8 file that slips past the null-byte check would otherwise
-      # abort the whole start-replay request).
-      out.force_encoding("UTF-8").scrub
-    rescue
-      nil
+      GitCommand.run(cwd, args, timeout: 30)
     end
 
     def cc_ref_exists?(root, ref)

data/lib/bitfab/span_context.rb

@@ -133,7 +133,7 @@ module Bitfab
     end
 
     def current
-      stack.last || fiber_bridge_stack.last
+      stack.last || Subtree.fiber_context&.inherited_span || fiber_bridge_stack.last
     end
 
     # Enumerator.new and enum_for run their source body in another Fiber on
@@ -149,8 +149,12 @@ module Bitfab
 
     # Execute a block with a new span pushed onto the stack.
     # The span is automatically popped when the block completes.
-    def with_span(trace_id:, span_id:)
+    def with_span(trace_id:, span_id:, explicit_span_receiver: nil, explicit_span_method_name: nil)
       entry = {trace_id:, span_id:}
+      if explicit_span_receiver
+        entry[:explicit_span_receiver] = explicit_span_receiver
+        entry[:explicit_span_method_name] = explicit_span_method_name
+      end
       stack.push(entry)
       yield
     ensure