openclacky 1.2.12 → 1.2.14

data/lib/clacky/server/http_server.rb

@@ -5,6 +5,7 @@ require "websocket"
 require "socket"
 require "json"
 require "net/http"
+require "faraday"
 require "thread"
 require "fileutils"
 require "tmpdir"
@@ -39,15 +40,13 @@ module Clacky
           url  = f[:data_url] || f["data_url"]
           name = f[:name]     || f["name"]
           path = f[:path]     || f["path"]
+          type = f[:type]     || f["type"] || ""
 
           if url
             url
-          elsif path && File.exist?(path.to_s)
-            # Reconstruct data_url from the tmp file (still present on disk)
+          elsif type.to_s == "image" && path && File.exist?(path.to_s)
             Utils::FileProcessor.image_path_to_data_url(path) rescue "expired:#{name}"
           elsif name
-            # File badge for non-image disk files, or image whose tmp file is gone
-            type = f[:type] || f["type"] || ""
             type.to_s == "image" ? "expired:#{name}" : "pdf:#{name}"
           end
         end
@@ -437,7 +436,12 @@ module Clacky
         when ["PATCH",  "/api/config/settings"]  then api_update_settings(req, res)
         when ["POST",   "/api/config/models"] then api_add_model(req, res)
         when ["POST",   "/api/config/test"]   then api_test_config(req, res)
+        when ["POST",   "/api/config/media/test"] then api_test_media_config(req, res)
         when ["GET",    "/api/config/media"]  then api_get_media_config(res)
+        when ["GET",    "/api/config/ocr"]    then api_get_ocr_config(res)
+        when ["PATCH",  "/api/config/ocr"]    then api_update_ocr_config(req, res)
+        when ["POST",   "/api/config/ocr/test"] then api_test_ocr_config(req, res)
+        when ["POST",   "/api/internal/ocr-image"] then api_internal_ocr_image(req, res)
         when ["GET",    "/api/providers"]     then api_list_providers(res)
         when ["GET",    "/api/onboard/status"]    then api_onboard_status(res)
         when ["GET",    "/api/browser/status"]    then api_browser_status(res)
@@ -552,6 +556,9 @@ module Clacky
           elsif method == "PATCH" && path.match?(%r{^/api/sessions/[^/]+/working_dir$})
             session_id = path.sub("/api/sessions/", "").sub("/working_dir", "")
             api_change_session_working_dir(session_id, req, res)
+          elsif method == "POST" && path.match?(%r{^/api/sessions/[^/]+/fork$})
+            session_id = path.sub("/api/sessions/", "").sub("/fork", "")
+            api_fork_session(session_id, req, res)
           elsif method == "DELETE" && path.start_with?("/api/sessions/")
             session_id = path.sub("/api/sessions/", "")
             api_delete_session(session_id, res)
@@ -610,6 +617,7 @@ module Clacky
         limit   = [query["limit"].to_i.then { |n| n > 0 ? n : 20 }, 50].min
         before  = query["before"].to_s.strip.then  { |v| v.empty? ? nil : v }
         q       = query["q"].to_s.strip.then       { |v| v.empty? ? nil : v }
+        q_scope = query["q_scope"].to_s.strip.then { |v| %w[name content].include?(v) ? v : "name" }
         date    = query["date"].to_s.strip.then    { |v| v.empty? ? nil : v }
         type    = query["type"].to_s.strip.then    { |v| v.empty? ? nil : v }
         # Backward-compat: ?source=<x> and ?profile=coding → type
@@ -620,7 +628,7 @@ module Clacky
         # `registry.list` always returns ALL matching pinned rows first (on the
         # first page; `before` == nil), followed by non-pinned rows up to `limit+1`.
         # So has_more is determined by whether the non-pinned section overflowed.
-        sessions = @registry.list(limit: limit + 1, before: before, q: q, date: date, type: type)
+        sessions = @registry.list(limit: limit + 1, before: before, q: q, q_scope: q_scope, date: date, type: type)
 
         # Split pinned vs non-pinned to apply has_more only to the non-pinned tail.
         pinned_part, non_pinned_part = sessions.partition { |s| s[:pinned] }
@@ -935,6 +943,9 @@ module Clacky
             api_key_masked: entry ? mask_api_key(entry["api_key"]) : nil,
             provider:   state["provider"],
             available:  state["available"],
+            aliases:    state["aliases"] || {},
+            stale:      state["stale"] || false,
+            requested_model: state["requested_model"],
             configured: state["configured"]
           }
         end
@@ -952,7 +963,8 @@ module Clacky
           defaults[t] = {
             provider:  provider_id,
             model:     provider_id ? Clacky::Providers.default_media_model(provider_id, t) : nil,
-            available: provider_id ? Clacky::Providers.media_models(provider_id, t) : []
+            available: provider_id ? Clacky::Providers.media_models(provider_id, t) : [],
+            aliases:   provider_id ? Clacky::Providers.media_model_aliases(provider_id, t) : {}
           }
         end
 
@@ -965,6 +977,85 @@ module Clacky
       # off / auto — remove any custom entry; "auto" lets the virtual
       # derivation in AgentConfig#find_model_by_type take over.
       # custom — replace any existing custom entry with the supplied fields.
+      # POST /api/config/media/test
+      # Body: { kind, source, model, base_url, api_key }
+      # Lightweight preflight: GET <base_url>/models to verify connectivity,
+      # auth, and that the requested model is exposed by the endpoint.
+      # No image is generated — zero cost, sub-second.
+      def api_test_media_config(req, res)
+        body = parse_json_body(req) || {}
+        kind = body["kind"].to_s
+        return json_response(res, 422, { error: "invalid kind" }) unless %w[image video audio].include?(kind)
+        return json_response(res, 422, { error: "only image kind supported" }) unless kind == "image"
+
+        api_key = body["api_key"].to_s
+        if api_key.empty? || api_key.include?("****")
+          existing = @agent_config.find_model_by_type(kind) || {}
+          api_key = existing["api_key"].to_s
+        end
+
+        model    = body["model"].to_s.strip
+        base_url = body["base_url"].to_s.strip
+
+        if model.empty? || base_url.empty? || api_key.empty?
+          return json_response(res, 200, { ok: false, message: "model, base_url, api_key are required" })
+        end
+
+        result = preflight_media_endpoint(base_url: base_url, api_key: api_key, model: model)
+        json_response(res, 200, result)
+      rescue => e
+        json_response(res, 200, { ok: false, message: e.message })
+      end
+
+      private def preflight_media_endpoint(base_url:, api_key:, model:)
+        url = "#{base_url.chomp("/")}/models"
+        conn = Faraday.new(url: url) do |f|
+          f.options.timeout      = 10
+          f.options.open_timeout = 5
+        end
+
+        response =
+          begin
+            conn.get do |req|
+              req.headers["Authorization"] = "Bearer #{api_key}"
+              req.headers["Accept"]        = "application/json"
+            end
+          rescue Faraday::Error => e
+            return { ok: false, message: "Network error: #{e.message}" }
+          end
+
+        case response.status
+        when 401, 403
+          return { ok: false, message: "Authentication failed (HTTP #{response.status}). Check API key." }
+        when 404
+          return { ok: false, message: "Endpoint not found at #{url}. Check Base URL." }
+        end
+
+        unless response.success?
+          return { ok: false, message: "HTTP #{response.status}: #{response.body.to_s[0, 200]}" }
+        end
+
+        body = JSON.parse(response.body) rescue nil
+        ids =
+          if body.is_a?(Hash) && body["data"].is_a?(Array)
+            body["data"].map { |m| m["id"].to_s }
+          elsif body.is_a?(Array)
+            body.map { |m| m["id"].to_s }
+          else
+            []
+          end
+
+        if ids.empty?
+          return { ok: true, message: "Connected (model list unavailable; cannot verify model id)" }
+        end
+
+        if ids.include?(model)
+          { ok: true, message: "Connected. Model '#{model}' is available." }
+        else
+          { ok: false, message: "Connected, but model '#{model}' not found on this endpoint." }
+        end
+      end
+
       def api_update_media_config(kind, req, res)
         body = parse_json_body(req) || {}
         source = body["source"].to_s
@@ -974,7 +1065,23 @@ module Clacky
 
         @agent_config.models.reject! { |m| m["type"] == kind }
 
-        if source == "custom"
+        case source
+        when "off"
+          @agent_config.models << {
+            "id"       => SecureRandom.uuid,
+            "type"     => kind,
+            "disabled" => true
+          }
+        when "auto"
+          override = body["model"].to_s.strip
+          unless override.empty?
+            @agent_config.models << {
+              "id"    => SecureRandom.uuid,
+              "type"  => kind,
+              "model" => override
+            }
+          end
+        when "custom"
           model    = body["model"].to_s.strip
           base_url = body["base_url"].to_s.strip
           api_key  = body["api_key"].to_s
@@ -998,6 +1105,179 @@ module Clacky
         json_response(res, 422, { error: e.message })
       end
 
+      # GET /api/config/ocr
+      # Returns the OCR sidecar state for the Settings UI. Mirrors media_state
+      # in shape so the UI can render OCR with the same row component.
+      def api_get_ocr_config(res)
+        state = @agent_config.ocr_state
+        entry = @agent_config.find_model_by_type("ocr")
+
+        out = {
+          source:         state["source"],
+          model:          state["model"],
+          base_url:       state["base_url"],
+          api_key_masked: entry ? mask_api_key(entry["api_key"]) : nil,
+          provider:       state["provider"],
+          available:      state["available"],
+          stale:          state["stale"] || false,
+          requested_model: state["requested_model"],
+          configured:     state["configured"],
+          primary:        state["primary"] || false
+        }
+
+        # Auto-mode preview: surface what the OCR sidecar *would* be if the
+        # user flipped to "auto" — derived from the same provider as the
+        # current default model.
+        default = @agent_config.find_model_by_type("default")
+        provider_id = default && Clacky::Providers.resolve_provider(
+          base_url: default["base_url"],
+          api_key:  default["api_key"]
+        )
+        default_preview = {
+          provider:  provider_id,
+          model:     provider_id ? Clacky::Providers.default_ocr_model(provider_id) : nil,
+          available: provider_id ? Clacky::Providers.ocr_models(provider_id) : []
+        }
+
+        json_response(res, 200, { ocr: out, default_provider: default_preview })
+      end
+
+      # PATCH /api/config/ocr
+      # Body: { source: "off"|"auto"|"custom", model?, base_url?, api_key?,
+      #         anthropic_format? }
+      # Mirrors api_update_media_config but for the single "ocr" type.
+      def api_update_ocr_config(req, res)
+        body = parse_json_body(req) || {}
+        source = body["source"].to_s
+        unless %w[off auto custom].include?(source)
+          return json_response(res, 422, { error: "invalid source" })
+        end
+
+        @agent_config.models.reject! { |m| m["type"] == "ocr" }
+
+        case source
+        when "off"
+          @agent_config.models << {
+            "id"       => SecureRandom.uuid,
+            "type"     => "ocr",
+            "disabled" => true
+          }
+        when "auto"
+          override = body["model"].to_s.strip
+          unless override.empty?
+            @agent_config.models << {
+              "id"    => SecureRandom.uuid,
+              "type"  => "ocr",
+              "model" => override
+            }
+          end
+        when "custom"
+          model    = body["model"].to_s.strip
+          base_url = body["base_url"].to_s.strip
+          api_key  = body["api_key"].to_s
+          if api_key.include?("****")
+            existing = @agent_config.models.find { |m| m["type"] == "ocr" && m["api_key"] }
+            api_key = existing ? existing["api_key"].to_s : ""
+          end
+          if model.empty? || base_url.empty? || api_key.empty?
+            return json_response(res, 422, { error: "model, base_url, api_key are required" })
+          end
+
+          @agent_config.models << {
+            "id"               => SecureRandom.uuid,
+            "model"            => model,
+            "base_url"         => base_url,
+            "api_key"          => api_key,
+            "anthropic_format" => body["anthropic_format"] || false,
+            "type"             => "ocr"
+          }
+        end
+
+        @agent_config.save
+        json_response(res, 200, { ok: true, state: @agent_config.ocr_state })
+      rescue => e
+        json_response(res, 422, { error: e.message })
+      end
+
+      # POST /api/config/ocr/test
+      # Reuses the media preflight (GET /models) — same connectivity check.
+      def api_test_ocr_config(req, res)
+        body = parse_json_body(req) || {}
+        api_key = body["api_key"].to_s
+        if api_key.empty? || api_key.include?("****")
+          existing = @agent_config.find_model_by_type("ocr") || {}
+          api_key = existing["api_key"].to_s
+        end
+
+        model    = body["model"].to_s.strip
+        base_url = body["base_url"].to_s.strip
+
+        if model.empty? || base_url.empty? || api_key.empty?
+          return json_response(res, 200, { ok: false, message: "model, base_url, api_key are required" })
+        end
+
+        result = preflight_media_endpoint(base_url: base_url, api_key: api_key, model: model)
+        json_response(res, 200, result)
+      rescue => e
+        json_response(res, 200, { ok: false, message: e.message })
+      end
+
+      # POST /api/internal/ocr-image
+      # Internal endpoint used by parser scripts (e.g. pdf_parser_vlm.py) to
+      # transcribe a single image via the configured OCR sidecar. Localhost-
+      # only by virtue of the standard auth path: when the server binds to
+      # 127.0.0.1 (@localhost_only), check_access_key returns true without
+      # requiring a token, so parsers running on the same host can call this
+      # endpoint with no extra wiring.
+      #
+      # Request:  multipart/form-data with field "image" (binary), optional "prompt"
+      #           OR JSON body { "data_url": "data:image/png;base64,...", "prompt": "..." }
+      # Response: { ok: true, text: "..." } or { ok: false, message: "..." }
+      def api_internal_ocr_image(req, res)
+        entry = @agent_config.find_model_by_type("ocr")
+        unless entry
+          return json_response(res, 503, { ok: false, message: "OCR sidecar not configured" })
+        end
+
+        prompt   = nil
+        data_url = nil
+        bytes    = nil
+        mime     = "image/png"
+
+        ctype = req.content_type.to_s
+        if ctype.start_with?("multipart/form-data")
+          parts = req.query
+          if (img = parts["image"])
+            bytes = img.respond_to?(:read) ? img.read : img.to_s
+            mime  = (img.respond_to?(:[]) ? img["content-type"].to_s : nil)
+            mime  = "image/png" if mime.nil? || mime.empty?
+          end
+          prompt = parts["prompt"].to_s if parts["prompt"]
+        else
+          body = parse_json_body(req) || {}
+          data_url = body["data_url"].to_s
+          prompt   = body["prompt"].to_s if body["prompt"]
+        end
+
+        image =
+          if bytes && !bytes.empty?
+            { bytes: bytes, mime_type: mime }
+          elsif data_url && !data_url.empty?
+            { data_url: data_url }
+          else
+            return json_response(res, 400, { ok: false, message: "image or data_url required" })
+          end
+
+        text = Clacky::Vision::Resolver.new(entry).describe(image, prompt: prompt)
+        if text && !text.strip.empty?
+          json_response(res, 200, { ok: true, text: text })
+        else
+          json_response(res, 200, { ok: false, message: "OCR returned empty result" })
+        end
+      rescue => e
+        json_response(res, 500, { ok: false, message: e.message })
+      end
+
       # POST /api/onboard/complete
       # Called after key setup is done (soul_setup is optional/skipped).
       # Creates the default session if none exists yet, returns it.
@@ -4201,6 +4481,15 @@ module Clacky
         json_response(res, 500, { error: e.message })
       end
 
+      def api_fork_session(session_id, req, res)
+        fork_data = @session_manager.fork(session_id)
+        return json_response(res, 404, { error: "Session not found" }) unless fork_data
+
+        fork_id = fork_data[:session_id]
+        broadcast_session_update(fork_id)
+        json_response(res, 201, { session: @registry.snapshot(fork_id) })
+      end
+
       def api_delete_session(session_id, res)
         # A session exists if it's either in the runtime registry OR on disk.
         # Old sessions that were never restored into memory this server run

data/lib/clacky/server/session_registry.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "set"
+
 module Clacky
   module Server
     # SessionRegistry is the single authoritative source for session state.
@@ -158,7 +160,7 @@ module Clacky
       #   [ ...all_pinned_matching (newest-first), ...non_pinned (newest-first, limited) ]
       #
       # source and profile are orthogonal — either can be nil independently.
-      def list(limit: nil, before: nil, q: nil, date: nil, type: nil, include_pinned: true)
+      def list(limit: nil, before: nil, q: nil, q_scope: "name", date: nil, type: nil, include_pinned: true)
         return [] unless @session_manager
 
         live = @mutex.synchronize do
@@ -195,13 +197,25 @@ module Clacky
         # ── date filter (YYYY-MM-DD, matches created_at prefix) ──────────────
         all = all.select { |s| s[:created_at].to_s.start_with?(date) } if date
 
-        # ── name / id search ─────────────────────────────────────────────────
+        # ── name / id / content search ───────────────────────────────────────
+        content_snippets = nil
         if q && !q.empty?
-          q_down = q.downcase
-          all = all.select { |s|
-            (s[:name] || "").downcase.include?(q_down) ||
-              (s[:session_id] || "").downcase.include?(q_down)
-          }
+          if q_scope == "content"
+            content_snippets = @session_manager.search_content(q)
+            if content_snippets.empty?
+              all = []
+            else
+              prefix_set = content_snippets.keys.to_set
+              all = all.select { |s| prefix_set.include?((s[:session_id] || "")[0, 8]) }
+            end
+          else
+            q_down = q.downcase
+            id_match_eligible = q_down.match?(/\A[0-9a-f]{6,}\z/)
+            all = all.select { |s|
+              (s[:name] || "").downcase.include?(q_down) ||
+                (id_match_eligible && (s[:session_id] || "").downcase.include?(q_down))
+            }
+          end
         end
 
         # ── Split pinned vs non-pinned BEFORE applying `before`/`limit`.
@@ -223,7 +237,15 @@ module Clacky
 
         ordered = pinned_section + non_pinned
 
-        ordered.map { |s| build_enriched_row(s, live[s[:session_id]]) }
+        ordered.map do |s|
+          row = build_enriched_row(s, live[s[:session_id]])
+          if content_snippets
+            short = (s[:session_id] || "")[0, 8]
+            snip = content_snippets[short]
+            row[:search_snippet] = snip if snip
+          end
+          row
+        end
       end
 
       # Return the same enriched hash that a `list` row would produce, for a

data/lib/clacky/server/web_ui_controller.rb

@@ -171,7 +171,6 @@ module Clacky
 
       def show_diff(old_content, new_content, max_lines: 50)
         emit("diff", old_size: old_content.bytesize, new_size: new_content.bytesize)
-        # Diffs are too verbose for IM — intentionally not forwarded
       end
 
       def show_token_usage(token_data)
@@ -210,6 +209,27 @@ module Clacky
         forward_to_subscribers { |sub| sub.show_warning(message) }
       end
 
+      # === Phase grouping ===
+
+      def phase_start(kind:, label: nil)
+        pid = SecureRandom.uuid
+        Thread.current[:clacky_phase_id] = pid
+        # Emit without auto-injection (the start event itself defines the phase)
+        event = { type: "phase_start", session_id: @session_id, phase_id: pid, kind: kind.to_s }
+        event[:label] = label if label
+        @broadcaster.call(@session_id, event)
+        pid
+      end
+
+      def phase_end(phase_id, summary: nil)
+        # Clear thread-local before emitting end so the end event itself
+        # doesn't get tagged with the phase_id it's closing.
+        Thread.current[:clacky_phase_id] = nil if Thread.current[:clacky_phase_id] == phase_id
+        event = { type: "phase_end", session_id: @session_id, phase_id: phase_id }
+        event[:summary] = summary if summary
+        @broadcaster.call(@session_id, event)
+      end
+
       def show_error(message, code: nil, top_up_url: nil)
         payload = { message: message }
         payload[:code] = code if code
@@ -414,6 +434,9 @@ module Clacky
 
       def emit(type, **data)
         event = { type: type, session_id: @session_id }.merge(data)
+        if (pid = Thread.current[:clacky_phase_id]) && !data.key?(:phase_id)
+          event[:phase_id] = pid
+        end
         @broadcaster.call(@session_id, event)
       end
 

data/lib/clacky/session_manager.rb

@@ -3,6 +3,7 @@
 require "json"
 require "fileutils"
 require "securerandom"
+require "open3"
 
 module Clacky
   class SessionManager
@@ -51,6 +52,27 @@ module Clacky
       all_sessions.find { |s| s[:session_id].to_s.start_with?(session_id.to_s) }
     end
 
+    # Fork a session: create a copy with new id, "(copy)" name suffix, and reset stats.
+    # Returns the forked session data hash, or nil if the original is not found.
+    def fork(session_id)
+      original = load(session_id)
+      return nil unless original
+
+      forked = original.dup
+      forked[:session_id]  = self.class.generate_id
+      forked[:created_at]  = Time.now.iso8601
+      forked[:updated_at]  = Time.now.iso8601
+      forked[:pinned]      = false
+      forked[:name]        = "#{original[:name] || "Unnamed session"} (copy)"
+      forked[:stats] = (original[:stats] || {}).merge(
+        total_tasks: 0, total_iterations: 0, total_cost_usd: 0.0,
+        last_status: nil, last_error: nil
+      )
+
+      save(forked)
+      forked
+    end
+
     # Soft-delete: move session JSON + chunks to the session trash directory.
     # Returns true if found and moved, false if not found.
     def delete(session_id)
@@ -158,6 +180,104 @@ module Clacky
       limit ? sessions.first(limit) : sessions
     end
 
+    # Full-text grep over session JSON + chunk MD files.
+    # Case-sensitive: BSD grep -i is ~30x slower; Chinese has no case.
+    # Returns Hash<short_id String => snippet String> (snippet around the first match).
+    def search_content(query, timeout: 5)
+      q = query.to_s
+      return {} if q.strip.length < 2
+
+      files = Dir.glob(File.join(@sessions_dir, "*.json")) +
+              Dir.glob(File.join(@sessions_dir, "*-chunk-*.md"))
+      return {} if files.empty?
+
+      result = {}
+      deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout
+      each_grep_batch(files) do |batch|
+        remaining = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        break if remaining <= 0
+        out = run_with_timeout({ "LC_ALL" => "C" },
+                               "grep", "-H", "-F", "-m", "1", "--",
+                               q, *batch,
+                               timeout: remaining)
+        next unless out
+        out.each_line do |line|
+          path, _, rest = line.chomp.partition(":")
+          next if path.empty? || rest.empty?
+          sid = extract_short_id(File.basename(path))
+          next unless sid
+          next if result.key?(sid)
+          result[sid] = build_snippet(rest, q)
+        end
+      end
+      result
+    end
+
+    # Yield file batches whose joined argv length stays well under ARG_MAX.
+    # macOS ARG_MAX is ~256 KiB; we cap at 96 KiB to leave room for env.
+    private def each_grep_batch(files, max_bytes: 96 * 1024)
+      batch = []
+      size  = 0
+      files.each do |f|
+        len = f.bytesize + 1
+        if size + len > max_bytes && !batch.empty?
+          yield batch
+          batch = []
+          size  = 0
+        end
+        batch << f
+        size  += len
+      end
+      yield batch unless batch.empty?
+    end
+
+    private def build_snippet(line, query, radius: 80)
+      bytes = line.b
+      q = query.b
+      idx = bytes.index(q)
+      if idx.nil?
+        head = bytes.byteslice(0, radius * 2).to_s
+        return head.force_encoding("UTF-8").scrub("?").gsub(/\s+/, " ").strip
+      end
+
+      start_byte = [idx - radius, 0].max
+      stop_byte  = [idx + q.bytesize + radius, bytes.bytesize].min
+      snippet = bytes.byteslice(start_byte, stop_byte - start_byte).to_s
+      snippet = snippet.force_encoding("UTF-8").scrub("?")
+      snippet = "…" + snippet if start_byte > 0
+      snippet = snippet + "…" if stop_byte < bytes.bytesize
+      snippet.gsub(/\s+/, " ").strip
+    end
+
+    private def run_with_timeout(env, *cmd, timeout:)
+      Open3.popen3(env, *cmd) do |stdin, stdout, stderr, wait_thr|
+        stdin.close
+        out = +""
+        reader = Thread.new { out << stdout.read }
+        drain  = Thread.new { stderr.read }
+        deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout
+        loop do
+          remaining = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          break if remaining <= 0
+          break if wait_thr.join(remaining)
+        end
+        if wait_thr.alive?
+          Process.kill("TERM", wait_thr.pid) rescue nil
+          wait_thr.join(0.5)
+          Process.kill("KILL", wait_thr.pid) rescue nil if wait_thr.alive?
+          reader.kill; drain.kill
+          return nil
+        end
+        reader.join; drain.join
+        out
+      end
+    end
+
+    private def extract_short_id(basename)
+      m = basename.match(/-([0-9a-f]{8})(?:-chunk-\d+)?\.(?:json|md)\z/)
+      m && m[1]
+    end
+
     # Return the most recent session for a given working directory, or nil.
     def latest_for_directory(working_dir)
       all_sessions(current_dir: working_dir).first