openclacky 1.3.4 → 1.3.6

data/lib/clacky/server/http_server.rb

@@ -15,6 +15,7 @@ require "securerandom"
 require "timeout"
 require "yaml"
 require "date"
+require "open3"
 require_relative "session_registry"
 require_relative "git_panel"
 require_relative "web_ui_controller"
@@ -368,6 +369,8 @@ module Clacky
             res.body                  = html
           elsif req.path.start_with?("/webui_ext/")
             self.send(:serve_webui_ext, req, res)
+          elsif req.path.start_with?("/builtin_ext/")
+            self.send(:serve_builtin_ext, req, res)
           elsif req.path.start_with?("/agent_ui/")
             self.send(:serve_agent_ui, req, res)
           elsif req.path.start_with?("/panel_ui/")
@@ -462,8 +465,12 @@ module Clacky
           600
         elsif path == "/api/media/audio/speech"
           120
-        elsif path.start_with?("/api/backup/download") || path == "/api/backup/run"
-          # Building a tar.gz of ~/.clacky (with session history) can take a while.
+        elsif path == "/api/media/audio/transcriptions"
+          30
+        elsif path == "/api/media/video/understand"
+          60
+        elsif path.start_with?("/api/backup/download") || path == "/api/backup/run" || path == "/api/backup/restore"
+          # Building/extracting a tar.gz of ~/.clacky can take a while.
           120
         else
           10
@@ -519,6 +526,8 @@ module Clacky
         when ["GET",    "/api/backup/status"]     then api_backup_status(res)
         when ["POST",   "/api/backup/run"]        then api_backup_run(res)
         when ["GET",    "/api/backup/download"]   then api_backup_download(res)
+        when ["POST",   "/api/backup/restore"]    then api_backup_restore(req, res)
+        when ["POST",   "/api/backup/open-folder"] then api_backup_open_folder(res)
         when ["PATCH",  "/api/backup/config"]     then api_backup_config(req, res)
         when ["POST",   "/api/telemetry"]        then api_telemetry(req, res)
         when ["POST",   "/api/onboard/complete"]  then api_onboard_complete(req, res)
@@ -549,6 +558,8 @@ module Clacky
         when ["POST",   "/api/media/image"]       then api_media_image(req, res)
         when ["POST",   "/api/media/video"]       then api_media_video(req, res)
         when ["POST",   "/api/media/audio/speech"] then api_media_audio_speech(req, res)
+        when ["POST",   "/api/media/audio/transcriptions"] then api_media_audio_transcriptions(req, res)
+        when ["POST",   "/api/media/video/understand"]     then api_media_video_understand(req, res)
         when ["GET",    "/api/media/types"]       then api_media_types(res)
         when ["GET",    "/api/version"]           then api_get_version(res)
         when ["POST",   "/api/version/upgrade"]   then api_upgrade_version(req, res)
@@ -677,7 +688,7 @@ module Clacky
           elsif method == "DELETE" && path.match?(%r{^/api/config/models/[^/]+$})
             id = path.sub("/api/config/models/", "")
             api_delete_model(id, res)
-          elsif method == "PATCH" && path.match?(%r{^/api/config/media/(image|video|audio)$})
+          elsif method == "PATCH" && path.match?(%r{^/api/config/media/(image|video|audio|stt|video_understanding)$})
             kind = path.sub("/api/config/media/", "")
             api_update_media_config(kind, req, res)
           elsif method == "POST" && path.match?(%r{^/api/cron-tasks/[^/]+/run$})
@@ -728,30 +739,28 @@ module Clacky
       # ── REST API ──────────────────────────────────────────────────────────────
 
       def api_list_sessions(req, res)
-        query   = URI.decode_www_form(req.query_string.to_s).to_h
-        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 }
+        query        = URI.decode_www_form(req.query_string.to_s).to_h
+        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 }
+        exclude_type = query["exclude_type"].to_s.strip.then { |v| v.empty? ? nil : v }
         # Backward-compat: ?source=<x> and ?profile=coding → type
         type ||= query["profile"].to_s.strip.then { |v| v.empty? ? nil : v }
         type ||= query["source"].to_s.strip.then  { |v| v.empty? ? nil : v }
 
-        # Fetch one extra NON-PINNED row to detect has_more without a separate count query.
-        # `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, q_scope: q_scope, date: date, type: type)
+        sessions = @registry.list(limit: limit + 1, before: before, q: q, q_scope: q_scope, date: date, type: type, exclude_type: exclude_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] }
         has_more = non_pinned_part.size > limit
         non_pinned_part = non_pinned_part.first(limit)
         sessions = pinned_part + non_pinned_part
 
-        json_response(res, 200, { sessions: sessions, has_more: has_more, cron_count: @registry.cron_count })
+        stats = @registry.cron_stats
+        json_response(res, 200, { sessions: sessions, has_more: has_more,
+                                  cron_count: stats[:count], latest_cron_updated_at: stats[:latest_updated_at] })
       end
 
       # GET /api/sessions/:id — fetch a single session by id (memory + disk merged).
@@ -1033,6 +1042,9 @@ module Clacky
       # Absolute path to the user's WebUI extension directory.
       WEBUI_EXT_ROOT = File.expand_path("~/.clacky/webui_ext")
 
+      # Built-in extensions bundled with the gem (default_extensions/*/**.js).
+      BUILTIN_EXT_ROOT = File.expand_path("../default_extensions", __dir__)
+
       # Build the full <script> payload injected at {{EXT_SCRIPTS}}:
       #   1. global extensions   — ~/.clacky/webui_ext/**/*.js  (all agents)
       #   2. agent-scoped UI     — agents/<name>/webui/**/*.js   (data-agent)
@@ -1042,6 +1054,7 @@ module Clacky
       private def webui_ext_script_tags
         [
           panel_agents_script,
+          builtin_ext_script_tags,
           global_ext_script_tags,
           agent_webui_script_tags,
           official_panel_script_tags,
@@ -1093,6 +1106,21 @@ module Clacky
         dirs
       end
 
+      # Built-in extensions from default_extensions/*/*.js — loaded before user
+      # extensions so user ~/.clacky/webui_ext/ can override by ext id.
+      private def builtin_ext_script_tags
+        return "" unless Dir.exist?(BUILTIN_EXT_ROOT)
+
+        Dir.glob(File.join(BUILTIN_EXT_ROOT, "*", "**", "*.js")).sort.map do |abs|
+          rel    = abs.delete_prefix(BUILTIN_EXT_ROOT + "/")
+          ext_id = "builtin/" + rel.delete_suffix(".js")
+          src    = "/builtin_ext/#{rel}"
+          "<script>Clacky.ext._extBegin(#{ext_id.to_json}, #{nil.to_json}, #{nil.to_json})</script>" \
+            "<script src=#{src.to_json} data-ext-id=#{ext_id.to_json}></script>" \
+            "<script>Clacky.ext._extEnd()</script>"
+        end.join("\n")
+      end
+
       # Global extensions — visible for all agents (unchanged legacy behavior).
       private def global_ext_script_tags
         ext_script_block(WEBUI_EXT_ROOT, "/webui_ext")
@@ -1173,6 +1201,31 @@ module Clacky
         res.body             = File.read(abs)
       end
 
+      private def serve_builtin_ext(req, res)
+        rel = req.path.delete_prefix("/builtin_ext/")
+        abs = File.expand_path(File.join(BUILTIN_EXT_ROOT, rel))
+
+        unless abs.start_with?(BUILTIN_EXT_ROOT + File::SEPARATOR) && File.file?(abs)
+          res.status = 404
+          res.body   = "not found"
+          return
+        end
+
+        ext = File.extname(abs)
+        ctype = { ".js" => "application/javascript", ".css" => "text/css" }[ext]
+        unless ctype
+          res.status = 415
+          res.body   = "unsupported media type"
+          return
+        end
+
+        res.status           = 200
+        res["Content-Type"]  = ctype
+        res["Cache-Control"] = "no-store"
+        res["Pragma"]        = "no-cache"
+        res.body             = File.read(abs)
+      end
+
       # Serve agents/<name>/webui/<file> from built-in or user agent dir.
       # Path: /agent_ui/<name>/<rel>. User dir wins on name collision.
       private def serve_agent_ui(req, res)
@@ -1405,6 +1458,59 @@ module Clacky
         json_response(res, 500, { error: e.message })
       end
 
+      def api_media_audio_transcriptions(req, res)
+        body = parse_json_body(req)
+        return json_response(res, 400, { error: "Invalid JSON" }) unless body
+
+        audio_b64 = body["audio_base64"].to_s
+        if audio_b64.empty?
+          return json_response(res, 422, { error: "audio_base64 is required" })
+        end
+
+        mime_type = body["mime_type"].to_s
+        mime_type = "audio/webm" if mime_type.empty?
+
+        result = Clacky::Media::Generator.new(@agent_config).generate_transcription(
+          audio_base64: audio_b64,
+          mime_type: mime_type
+        )
+        if result["success"]
+          Clacky::Logger.info("[Media] stt generated model=#{result["model"]} provider=#{result["provider"]} cost_usd=#{result["cost_usd"].to_f}")
+        end
+        status = result["success"] ? 200 : 422
+        json_response(res, status, result)
+      rescue StandardError => e
+        json_response(res, 500, { error: e.message })
+      end
+
+      def api_media_video_understand(req, res)
+        body = parse_json_body(req)
+        return json_response(res, 400, { error: "Invalid JSON" }) unless body
+
+        video_b64 = body["video_base64"].to_s
+        if video_b64.empty?
+          return json_response(res, 422, { error: "video_base64 is required" })
+        end
+
+        mime_type = body["mime_type"].to_s
+        mime_type = "image/png" if mime_type.empty?
+
+        prompt = body["prompt"].to_s
+
+        result = Clacky::Media::Generator.new(@agent_config).understand_video(
+          video_base64: video_b64,
+          mime_type: mime_type,
+          prompt: prompt
+        )
+        if result["success"]
+          Clacky::Logger.info("[Media] video_understanding generated model=#{result["model"]} provider=#{result["provider"]} cost_usd=#{result["cost_usd"].to_f}")
+        end
+        status = result["success"] ? 200 : 422
+        json_response(res, status, result)
+      rescue StandardError => e
+        json_response(res, 500, { error: e.message })
+      end
+
       private def log_media_usage(result, prompt:)
         usage = result["usage"]
         cost  = result["cost_usd"]
@@ -1967,6 +2073,7 @@ module Clacky
             product_name:                  brand.product_name,
             homepage_url:                  brand.homepage_url,
             logo_url:                      brand.logo_url,
+            theme_color:                   brand.theme_color,
             test_mode:                     @brand_test,
             distribution_refresh_pending:  refresh_pending
           })
@@ -2038,7 +2145,8 @@ module Clacky
             ok:            true,
             product_name:  result[:product_name] || brand.product_name,
             user_id:       result[:user_id] || brand.license_user_id,
-            user_licensed: brand.user_licensed?
+            user_licensed: brand.user_licensed?,
+            theme_color:   brand.theme_color
           })
         else
           json_response(res, 422, { ok: false, error: result[:message] })
@@ -4769,6 +4877,68 @@ module Clacky
         })
       end
 
+      # POST /api/backup/restore — accept a tar.gz upload, extract over ~/.clacky, hot-restart
+      def api_backup_restore(req, res)
+        body = req.body.to_s
+        return json_response(res, 400, { error: "Empty body" }) if body.empty?
+
+        clacky_dir = File.expand_path("~/.clacky")
+        stamp      = Time.now.strftime("%Y%m%d-%H%M%S")
+        tmp_archive = File.join(Dir.tmpdir, "clacky-restore-#{stamp}.tar.gz")
+        tmp_backup  = File.join(Dir.tmpdir, "clacky-pre-restore-#{stamp}")
+
+        File.binwrite(tmp_archive, body)
+
+        FileUtils.cp_r(clacky_dir, tmp_backup)
+
+        result = system("tar", "-xzf", tmp_archive, "-C", clacky_dir)
+        unless result
+          FileUtils.rm_rf(clacky_dir)
+          FileUtils.cp_r(tmp_backup, clacky_dir)
+          return json_response(res, 500, { error: "Failed to extract archive" })
+        end
+
+        json_response(res, 200, { ok: true })
+
+        Thread.new do
+          sleep 0.5
+          if @master_pid
+            begin
+              Process.kill("USR1", @master_pid)
+            rescue Errno::ESRCH
+              standalone_exec_restart
+            end
+          else
+            standalone_exec_restart
+          end
+        end
+      rescue => e
+        json_response(res, 500, { ok: false, error: e.message })
+      ensure
+        FileUtils.rm_f(tmp_archive) if tmp_archive
+        FileUtils.rm_rf(tmp_backup) if tmp_backup && Dir.exist?(tmp_backup)
+      end
+
+      # POST /api/backup/open-folder — open the backup destination in Finder/Explorer
+      def api_backup_open_folder(res)
+        dest = BackupManager.status["dest_dir"]
+        FileUtils.mkdir_p(dest)
+        host_os = RbConfig::CONFIG["host_os"]
+        if host_os =~ /darwin/
+          system("open", dest)
+        elsif host_os =~ /linux/
+          if File.exist?("/proc/version") && File.read("/proc/version").downcase.include?("microsoft")
+            windows_path, = Open3.capture2("wslpath", "-w", dest)
+            system("explorer.exe", windows_path.strip) unless windows_path.strip.empty?
+          else
+            system("xdg-open", dest)
+          end
+        end
+        json_response(res, 200, { ok: true, dest_dir: dest })
+      rescue => e
+        json_response(res, 500, { ok: false, error: e.message })
+      end
+
       # Resolve the AgentConfig for a given session, falling back to nil when
       # the session isn't live so callers can use the global config instead.
       def config_for_session(session_id)
@@ -5615,12 +5785,12 @@ module Clacky
           interrupt_session(session_id)
 
         when "list_sessions"
-          # Initial load: newest 20 sessions regardless of source/profile.
-          # Single unified query — frontend shows all in one time-sorted list.
-          page = @registry.list(limit: 21)
+          stats = @registry.cron_stats
+          page = @registry.list(limit: 21, exclude_type: "cron")
           has_more = page.size > 20
           all_sessions = page.first(20)
-          conn.send_json(type: "session_list", sessions: all_sessions, has_more: has_more, cron_count: @registry.cron_count)
+          conn.send_json(type: "session_list", sessions: all_sessions, has_more: has_more,
+                         cron_count: stats[:count], latest_cron_updated_at: stats[:latest_updated_at])
 
         when "run_task"
           # Client sends this after subscribing to guarantee it's ready to receive
@@ -5715,109 +5885,43 @@ module Clacky
 
       # Interrupt a running agent session.
       #
-      # Thread#raise alone is not reliable enough in practice — it's
-      # best-effort against blocked syscalls (socket writes, OpenSSL read,
-      # ConditionVariable#wait with a held mutex) and we've seen sessions
-      # that stay "running" forever even after multiple interrupt attempts.
-      #
-      # Strategy: three-tier escalation in a background watchdog Thread so
-      # the HTTP handler returns immediately.
-      #
-      #   Tier 1 (t=0): Thread#raise(AgentInterrupted).
-      #                 Unblocks most pure-Ruby waits and Faraday reads.
-      #                 Handles the common case.
-      #   Tier 2 (t=3): force-close this session's WebSocket connections
-      #                 so any send_raw stuck on socket write wakes up.
-      #                 Try Thread#raise again (idempotent).
-      #   Tier 3 (t=8): Thread#kill — last resort. Leaks any held
-      #                 resources but frees the session so the user can
-      #                 move on.
+      # Thread#raise is best-effort: it unblocks most pure-Ruby waits and
+      # Faraday reads, but can't reach a thread stuck in a C-extension syscall
+      # until that syscall returns. We raise once and return immediately.
       #
-      # Each transition is logged so that when users report "stuck
-      # sessions" we can see in the log whether tier 2/3 ever had to
-      # fire — that's our signal to dig deeper on the underlying block.
+      # Correctness of the *takeover* does not depend on the old thread dying
+      # promptly: each new task claims a fresh epoch (see run_agent_task), and
+      # any status write or UI broadcast from a superseded thread is fenced off
+      # by that epoch. A stale thread that lingers in a syscall is harmless — it
+      # self-terminates at the next check_stale! checkpoint, or when the syscall
+      # returns; either way it can no longer touch the live session.
       def interrupt_session(session_id)
-        thread = nil
         @registry.with_session(session_id) do |s|
           s[:idle_timer]&.cancel
           thread = s[:thread]
-
           next unless thread&.alive?
 
-          Clacky::Logger.info("[interrupt] session=#{session_id} tier=1 raise")
+          Clacky::Logger.info("[interrupt] session=#{session_id} raise")
           begin
             thread.raise(Clacky::AgentInterrupted, "Interrupted by user")
           rescue ThreadError => e
-            Clacky::Logger.warn("[interrupt] tier=1 raise failed: #{e.message}")
+            Clacky::Logger.warn("[interrupt] raise failed: #{e.message}")
           end
         end
+      end      # Run a task in a session immediately in the background, without waiting
+      # for the client to subscribe. The user bubble is persisted via
+      # display_text (Agent#run → history → replay_history), so the frontend
+      # only needs to navigate over and load history — no realtime broadcast,
+      # no subscribe-timing race. This is the stable entry point for
+      # programmatic "create session + run now" flows (spawn, extensions).
+      def run_session_task(session_id, prompt, display_message: nil)
+        return unless @registry.exist?(session_id)
 
-        return unless thread&.alive?
-
-        start_interrupt_watchdog(session_id, thread)
-      end
-
-      # Background watchdog: escalates from WebSocket force-close (tier 2)
-      # to Thread#kill (tier 3) if the agent thread refuses to die.
-      private def start_interrupt_watchdog(session_id, thread)
-        Thread.new do
-          Thread.current.name = "interrupt-watchdog[#{session_id}]" rescue nil
-
-          # Give the first Thread#raise a few seconds to unwind.
-          sleep 3
-          next unless thread.alive?
-
-          Clacky::Logger.warn(
-            "[interrupt] session=#{session_id} tier=2 raise failed after 3s, " \
-            "force-closing session resources"
-          )
-          force_close_session_sockets(session_id)
-          # Re-raise — sometimes the first raise was swallowed deep in a
-          # C-extension syscall; after we force-close the socket the
-          # syscall returns and the next raise sticks.
-          begin
-            thread.raise(Clacky::AgentInterrupted, "Interrupted by user (escalated)")
-          rescue ThreadError
-            # already dead between checks — fine
-          end
-
-          sleep 5
-          next unless thread.alive?
-
-          Clacky::Logger.error(
-            "[interrupt] session=#{session_id} tier=3 still alive after 8s, Thread#kill"
-          )
-          begin
-            thread.kill
-          rescue StandardError => e
-            Clacky::Logger.error("[interrupt] Thread#kill raised: #{e.class}: #{e.message}")
-          end
-
-          # Record the forced-kill so the UI can show a warning and operators
-          # can correlate with any backtrace dumps. The session is left in
-          # :idle state by run_agent_task's rescue clause; if the kill
-          # happened before the rescue could run, patch the state directly.
-          begin
-            @registry.update(session_id, status: :idle, error: "Force-killed (interrupt watchdog)")
-            broadcast_session_update(session_id)
-          rescue StandardError
-            # best effort
-          end
-        end
-      end
+        agent = nil
+        @registry.with_session(session_id) { |s| agent = s[:agent] }
+        return unless agent
 
-      # Close every WebSocket connection bound to the given session. Used by
-      # the interrupt watchdog to unblock agent threads stuck in a WS write.
-      private def force_close_session_sockets(session_id)
-        conns = @ws_mutex.synchronize { (@ws_clients[session_id] || []).dup }
-        conns.each do |conn|
-          Clacky::Logger.warn(
-            "[interrupt] session=#{session_id} force-closing WS conn"
-          )
-          conn.force_close!
-        end
-      rescue StandardError => e
-        Clacky::Logger.error("[interrupt] force_close_session_sockets error: #{e.class}: #{e.message}")
+        run_agent_task(session_id, agent) { agent.run(prompt, display_text: display_message) }
       end
 
       # Start the pending task for a session.
@@ -5827,18 +5931,29 @@ module Clacky
         return unless @registry.exist?(session_id)
 
         session = @registry.get(session_id)
-        prompt      = session[:pending_task]
-        working_dir = session[:pending_working_dir]
+        prompt          = session[:pending_task]
+        working_dir     = session[:pending_working_dir]
+        display_message = session[:pending_display_message]
         return unless prompt  # nothing pending
 
         # Clear the pending fields so a re-connect doesn't re-run
-        @registry.update(session_id, pending_task: nil, pending_working_dir: nil)
+        @registry.update(session_id, pending_task: nil, pending_working_dir: nil, pending_display_message: nil)
 
         agent = nil
         @registry.with_session(session_id) { |s| agent = s[:agent] }
         return unless agent
 
-        run_agent_task(session_id, agent) { agent.run(prompt) }
+        # Surface a user message on screen before the agent starts thinking, so
+        # programmatically-submitted tasks (e.g. meeting summarization) don't
+        # appear as a thinking spinner with no preceding message. When a short
+        # display_message is provided we show that instead of the full prompt.
+        if display_message
+          web_ui = nil
+          @registry.with_session(session_id) { |s| web_ui = s[:ui] }
+          web_ui&.show_user_message(display_message, source: :web)
+        end
+
+        run_agent_task(session_id, agent) { agent.run(prompt, display_text: display_message) }
       end
 
       # Interrupt every running agent thread and persist its session state.
@@ -5874,11 +5989,19 @@ module Clacky
         # Cancel any pending idle compression before starting a new task
         idle_timer&.cancel
 
-        # Mark running BEFORE evict_excess_idle! — otherwise this session
+        # Claim a fresh epoch and mark running atomically-ish. The epoch
+        # fences this task against an interrupted-but-not-yet-dead predecessor:
+        # the old thread compares its epoch before writing status or
+        # broadcasting and silently drops anything once superseded. Without
+        # this a slow old thread could overwrite :running back to :idle (or
+        # close the new task's sockets), leaving the UI stuck "running".
+        #
+        # Marked running BEFORE evict_excess_idle! — otherwise this session
         # (still :idle here) can be evicted from the registry along with
         # other idle agents, breaking subsequent status updates and any
         # follow-up handle_user_message (which would early-return on
         # @registry.exist? == false).
+        epoch = @registry.claim_epoch(session_id)
         @registry.update(session_id, status: :running)
 
         # evict_excess_idle! serializes + writes 1 file per evicted session
@@ -5894,8 +6017,9 @@ module Clacky
         locale = Thread.current[:lang]
         thread = Thread.new do
           Thread.current[:lang] = locale
+          Thread.current[:task_epoch] = epoch
           task.call
-          @registry.update(session_id, status: :idle, error: nil)
+          next unless @registry.update_if_epoch(session_id, epoch, status: :idle, error: nil)
           broadcast_session_update(session_id)
           # Transient global signal for the optional task-complete sound. Sent to
           # all clients (broadcast_all) so a browser viewing another session — or
@@ -5906,7 +6030,9 @@ module Clacky
           # Start idle compression timer now that the agent is idle
           idle_timer&.start
         rescue Clacky::AgentInterrupted
-          @registry.update(session_id, status: :idle)
+          # A superseding task already owns the session — do not touch status
+          # or push UI events, they belong to the new epoch now.
+          next unless @registry.update_if_epoch(session_id, epoch, status: :idle)
           broadcast_session_update(session_id)
           broadcast(session_id, { type: "interrupted", session_id: session_id })
           @session_manager.save(agent.to_session_data(status: :interrupted))
@@ -5921,12 +6047,15 @@ module Clacky
             top_up_url = preset && preset["website_url"]
           end
           user_message = e.respond_to?(:display_message) && e.display_message ? e.display_message : e.message
-          @registry.update(session_id, status: :error, error: user_message, error_code: code, top_up_url: top_up_url)
+          raw_message  = e.respond_to?(:raw_message) ? e.raw_message : nil
+          next unless @registry.update_if_epoch(session_id, epoch, status: :error, error: user_message, error_code: code, top_up_url: top_up_url, raw_message: raw_message)
           broadcast_session_update(session_id)
-          web_ui&.show_error(user_message, code: code, top_up_url: top_up_url)
-          @session_manager.save(agent.to_session_data(status: :error, error_message: user_message))
+          web_ui&.show_error(user_message, code: code, top_up_url: top_up_url, raw_message: raw_message)
+          @session_manager.save(agent.to_session_data(status: :error, error_message: user_message, raw_message: raw_message))
         end
-        @registry.with_session(session_id) { |s| s[:thread] = thread }
+        # Register the thread only if we still own the epoch; a faster
+        # superseding task may have already replaced it.
+        @registry.with_session(session_id) { |s| s[:thread] = thread if s[:epoch].to_i == epoch.to_i }
       end
 
       # ── WebSocket subscription management ─────────────────────────────────────
@@ -5956,6 +6085,15 @@ module Clacky
       # removed automatically. Connections already marked closed are skipped
       # upfront so one sluggish client can't delay delivery to healthy ones.
       def broadcast(session_id, event)
+        # Drop events emitted by a superseded agent thread. A thread carrying a
+        # :task_epoch only gets through while it still owns the session; an
+        # interrupted-but-unwinding old thread (e.g. a late show_progress
+        # "done" from an ensure block) is silently dropped so it can't disturb
+        # the new task's UI. Threads without :task_epoch (HTTP handlers, the
+        # task supervisor itself) are never affected.
+        my_epoch = Thread.current[:task_epoch]
+        return if my_epoch && @registry.current_epoch(session_id) != my_epoch
+
         clients = @ws_mutex.synchronize { (@ws_clients[session_id] || []).dup }
         dead = []
         clients.each do |conn|