openclacky 1.5.11 → 1.5.13

data/lib/clacky/openai_responses_stream_aggregator.rb

@@ -0,0 +1,294 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Clacky
+  # Reassembles an OpenAI Responses API event stream into the non-streaming
+  # response shape that MessageFormat::OpenAIResponses.parse_response consumes,
+  # while invoking on_chunk(input_tokens:, output_tokens:) for progress updates.
+  #
+  # The Responses API uses typed SSE events rather than the Chat Completions
+  # delta-based format. Key event types:
+  #
+  #   response.created                  -> response object created
+  #   response.output_item.added        -> new output item (message or function_call)
+  #   response.output_text.delta        -> text content delta
+  #   response.output_text.done         -> text content complete
+  #   response.reasoning_text.delta     -> reasoning content delta (OpenAI official / DeepSeek)
+  #   response.function_call_arguments.delta -> tool call argument delta
+  #   response.output_item.done         -> output item complete
+  #   response.completed                -> final event with full response + usage
+  #   response.done                     -> terminal event (OpenAI official API)
+  #   response.incomplete               -> response ended prematurely
+  #
+  # Unlike Chat Completions, there is no "[DONE]" sentinel; the stream ends
+  # with a "response.completed" / "response.done" (or "response.incomplete") event.
+  class OpenAIResponsesStreamAggregator
+    def initialize(on_chunk: nil)
+      @on_chunk = on_chunk
+      @text = +""
+      @reasoning_text = +""
+      @function_calls = {}   # call_id -> { name:, arguments: }
+      @call_id_by_item_id = {} # item_id -> call_id (for delta routing)
+      @usage = nil
+      @status = nil
+      @incomplete_details = nil
+      @last_input_tokens = 0
+      @last_output_tokens = 0
+      @parse_failures = 0
+      @frames_seen = 0
+      @bytes_seen = 0
+    end
+
+    attr_reader :parse_failures, :frames_seen, :bytes_seen
+
+    def saw_done?
+      !@status.nil?
+    end
+
+    def handle(data_str)
+      @bytes_seen += data_str.bytesize
+      @frames_seen += 1
+      data = parse_or_nil(data_str)
+      return unless data
+
+      event_type = data["type"]
+
+      case event_type
+      when "response.output_text.delta"
+        @text << data["delta"].to_s
+        emit_estimate_progress
+      # OpenAI's official API emits response.reasoning_text.delta; keep
+      # response.reasoning.delta as a tolerant alias for providers that
+      # rename it.
+      when "response.reasoning_text.delta", "response.reasoning.delta"
+        @reasoning_text << data["delta"].to_s
+      when "response.output_item.added"
+        handle_item_added(data)
+      when "response.function_call_arguments.delta"
+        handle_function_call_delta(data)
+      when "response.output_item.done"
+        handle_item_done(data)
+      when "response.completed", "response.done"
+        # OpenAI's official API sends response.completed followed by
+        # response.done as the terminal event; DeepSeek sends only
+        # response.completed. Either one marks a successful end.
+        @status = "completed"
+        response = data["response"]
+        @usage ||= response["usage"] if response && response["usage"]
+        # Also sync output items from the final response if our incremental
+        # tracking missed anything (e.g. provider sent complete items only).
+        sync_from_final_output(response["output"]) if response && response["output"]
+        emit_usage_progress(@usage) if @usage
+      when "response.incomplete"
+        @status = "incomplete"
+        # Preserve incomplete_details (e.g. reason: "max_output_tokens" vs
+        # "content_filter") so finish_reason mapping can distinguish a token
+        # limit from a safety-filtered response.
+        response = data["response"]
+        @incomplete_details = response["incomplete_details"] if response.is_a?(Hash) && response["incomplete_details"]
+      when "response.created", "response.in_progress"
+        # Informational events, no action needed
+      end
+    end
+
+    # Render into the non-streaming Responses API response shape
+    # so MessageFormat::OpenAIResponses.parse_response works unchanged.
+    def to_h
+      output = []
+
+      # Message item with text content
+      unless @text.empty?
+        output << {
+          "type"    => "message",
+          "role"    => "assistant",
+          "content" => [{ "type" => "output_text", "text" => @text.to_s }]
+        }
+      end
+
+      # Reasoning item. Both providers stream reasoning via
+      # response.reasoning(_text).delta; emit it as a top-level "reasoning"
+      # item (DeepSeek shape) so MessageFormat::OpenAIResponses#extract_reasoning
+      # can consume it. Without this the streaming path silently drops
+      # reasoning content while the non-streaming path keeps it.
+      unless @reasoning_text.empty?
+        output << {
+          "type" => "reasoning",
+          "content" => [{ "type" => "reasoning_text", "text" => @reasoning_text.to_s }]
+        }
+      end
+
+      # Function call items
+      @function_calls.each_value do |fc|
+        output << {
+          "type"      => "function_call",
+          "call_id"   => fc[:call_id],
+          "name"      => fc[:name],
+          "arguments" => fc[:arguments].to_s
+        }
+      end
+
+      result = {
+        "output" => output,
+        "status" => @status || "completed",
+        "usage"  => @usage || {}
+      }
+      result["incomplete_details"] = @incomplete_details if @incomplete_details
+      result
+    end
+
+    private def handle_item_added(data)
+      item = data["item"]
+      return unless item
+
+      if item["type"] == "function_call"
+        call_id = item["call_id"]
+        item_id = item["id"]
+        @call_id_by_item_id[item_id] = call_id if item_id
+        @function_calls[call_id] = {
+          call_id:    call_id,
+          name:       item["name"],
+          arguments:  +""
+        }
+      end
+    end
+
+    private def handle_function_call_delta(data)
+      # The delta event carries item_id to identify which function call
+      # the arguments belong to. Map it to the call_id we registered in
+      # handle_item_added. Fall back to the most recent call if mapping fails.
+      item_id = data["item_id"]
+      call_id = @call_id_by_item_id[item_id] || @function_calls.keys.last
+
+      return unless call_id && @function_calls[call_id]
+
+      @function_calls[call_id][:arguments] << data["delta"].to_s
+    end
+
+    private def handle_item_done(data)
+      item = data["item"]
+      return unless item
+
+      if item["type"] == "function_call"
+        call_id = item["call_id"]
+        fc = @function_calls[call_id]
+        # Use the complete arguments from the done event if available -
+        # more reliable than accumulated deltas.
+        if fc && item["arguments"]
+          fc[:arguments] = item["arguments"]
+        end
+      end
+    end
+
+    private def sync_from_final_output(output)
+      return unless output.is_a?(Array)
+
+      # Sync per-item: only backfill what incremental tracking missed.
+      # A provider may send complete message items but only deltas for
+      # function calls (or vice versa), so don't require both to be empty.
+      output.each do |item|
+        case item["type"]
+        when "message"
+          content = item["content"]
+          next unless content.is_a?(Array)
+
+          content.each do |block|
+            case block["type"]
+            when "output_text"
+              @text << block["text"].to_s if @text.empty?
+            when "reasoning"
+              backfill_reasoning(block["content"], block["summary"])
+            end
+          end
+        when "reasoning"
+          backfill_reasoning(item["content"], item["summary"])
+        when "function_call"
+          next if @function_calls.key?(item["call_id"])
+          @function_calls[item["call_id"]] = {
+            call_id:    item["call_id"],
+            name:       item["name"],
+            arguments:  item["arguments"].to_s
+          }
+        end
+      end
+    end
+
+    # Backfill @reasoning_text from the final response snapshot when no
+    # reasoning delta was seen. Handles both item shapes: OpenAI's official
+    # reasoning block inside the message item, and DeepSeek's top-level
+    # reasoning item. Prefers full reasoning text; falls back to the summary
+    # (mirrors MessageFormat::OpenAIResponses#extract_reasoning).
+    private def backfill_reasoning(content_blocks, summary_blocks = nil)
+      return unless @reasoning_text.empty?
+
+      return if append_typed_blocks(content_blocks, "reasoning_text")
+
+      append_typed_blocks(content_blocks, "summary_text") || append_typed_blocks(summary_blocks, "summary_text")
+    end
+
+    # Append every block of the given type to @reasoning_text.
+    # Returns true when at least one block matched.
+    private def append_typed_blocks(blocks, type)
+      return false unless blocks.is_a?(Array)
+
+      found = false
+      blocks.each do |block|
+        next unless block.is_a?(Hash) && block["type"] == type
+
+        @reasoning_text << block["text"].to_s if block["text"]
+        found = true
+      end
+      found
+    end
+
+    private def parse_or_nil(s)
+      # Some providers / proxies append a "[DONE]" sentinel (inherited from
+      # Chat Completions SSE) even for the Responses API.  Silently ignore it
+      # instead of logging a parse failure.
+      return nil if s.to_s.strip == "[DONE]"
+
+      JSON.parse(s)
+    rescue JSON::ParserError => e
+      @parse_failures += 1
+      if @parse_failures == 1
+        Clacky::Logger.warn("stream.parse_failure",
+          provider: "openai-responses",
+          error: "#{e.class}: #{e.message}",
+          frame_head: s.to_s[0, 200],
+          frame_bytes: s.to_s.bytesize
+        )
+      end
+      nil
+    end
+
+    private def emit_estimate_progress
+      return unless @on_chunk
+      output = approximate_output_tokens
+      return if output == @last_output_tokens
+      @last_output_tokens = output
+      @on_chunk.call(input_tokens: @last_input_tokens, output_tokens: output)
+    rescue => e
+      Clacky::Logger.warn("[OpenAIResponsesStreamAggregator] on_chunk: #{e.class}: #{e.message}")
+    end
+
+    # Rough char/4 estimate; replaced by the real count when the upstream
+    # emits the response.completed event with usage data.
+    private def approximate_output_tokens
+      total_chars = @text.bytesize + @reasoning_text.bytesize +
+        @function_calls.values.sum { |tc| tc[:arguments].to_s.bytesize }
+      (total_chars / 4.0).ceil
+    end
+
+    private def emit_usage_progress(u)
+      return unless @on_chunk
+      total_prompt = u["input_tokens"].to_i
+      output       = u["output_tokens"].to_i
+      return if total_prompt == @last_input_tokens && output == @last_output_tokens
+      @last_input_tokens = total_prompt
+      @last_output_tokens = output
+      @on_chunk.call(input_tokens: total_prompt, output_tokens: output)
+    rescue => e
+      Clacky::Logger.warn("[OpenAIResponsesStreamAggregator] on_chunk: #{e.class}: #{e.message}")
+    end
+  end
+end

data/lib/clacky/plain_ui_controller.rb

@@ -16,7 +16,7 @@ module Clacky
 
     # === Output display ===
 
-    def show_assistant_message(content, files:, interim: false)
+    def show_assistant_message(content, files:, interim: false, created_at: nil)
       puts_line(content) unless content.nil? || content.strip.empty?
       files.each { |f| puts_line("📄 File: #{f[:path]}") }
     end
@@ -87,7 +87,7 @@ module Clacky
       puts_line("[shell] #{command}")
     end
 
-    def show_complete(iterations:, cost:, duration: nil, cache_stats: nil, awaiting_user_feedback: false, cost_source: nil)
+    def show_complete(iterations:, cost:, duration: nil, cache_stats: nil, awaiting_user_feedback: false, cost_source: nil, task_id: nil)
       parts = ["[done] iterations=#{iterations}", "cost=$#{cost.round(4)}"]
       parts << "duration=#{duration.round(1)}s" if duration
       puts_line(parts.join(" "))
@@ -121,11 +121,21 @@ module Clacky
     def emit(type, **data)
       return unless type == "ext.advisor.recommendations"
 
-      content = (data[:content] || data["content"]).to_s.strip
-      return if content.empty?
+      options = data[:options] || data["options"]
+      return unless options.is_a?(Array)
+
+      lines = options.map do |opt|
+        action = (opt[:action] || opt["action"]).to_s.strip
+        next if action.empty?
+
+        reason = (opt[:reason] || opt["reason"]).to_s.strip
+        reason.empty? ? "- #{action}" : "- #{action} (#{reason})"
+      end.compact
+      return if lines.empty?
 
       puts_line("")
-      puts_line("💡 #{content}")
+      puts_line("💡")
+      lines.each { |line| puts_line(line) }
     end
 
     def log(message, level: :info)

data/lib/clacky/providers.rb

@@ -31,6 +31,7 @@ module Clacky
         "api" => "bedrock",
         "default_model" => "abs-claude-sonnet-5",
         "models" => [
+          "abs-claude-fable-5-1",
           "abs-claude-fable-5",
           "abs-claude-opus-5",
           "abs-claude-opus-4-8",
@@ -44,6 +45,8 @@ module Clacky
           "dsk-deepseek-v4-flash",
           "dsk-deepseek-v4-flash-vision-exp",
           "or-gemini-3-1-pro",
+          "or-gemini-3-8-flash",
+          "or-gemini-3-7-flash",
           "or-gemini-3-6-flash",
           "or-gemini-3-5-flash"
         ],
@@ -96,34 +99,42 @@ module Clacky
         # routes them to Vertex AI Gemini (generateContent with inline
         # audio parts). The gateway returns transcription text.
         "stt_models" => [
+          "or-stt-gemini-3-8-flash",
+          "or-stt-gemini-3-7-flash",
           "or-stt-gemini-3-6-flash",
           "or-stt-gemini-3-5-flash",
           "or-stt-gemini-1-5-pro"
         ],
         "stt_model_aliases" => {
+          "or-stt-gemini-3-8-flash" => "Gemini 3.8 Flash STT",
+          "or-stt-gemini-3-7-flash" => "Gemini 3.7 Flash STT",
           "or-stt-gemini-3-6-flash" => "Gemini 3.6 Flash STT",
           "or-stt-gemini-3-5-flash" => "Gemini 3.5 Flash STT",
           "or-stt-gemini-1-5-pro"   => "Gemini 1.5 Pro STT"
         },
-        "default_stt_model" => "or-stt-gemini-3-6-flash",
+        "default_stt_model" => "or-stt-gemini-3-8-flash",
         # Video understanding models served by the openclacky gateway, which
         # routes video frames to Gemini (generateContent with inline image
         # parts). The gateway returns analysis text.
         "video_understanding_models" => [
+          "or-gemini-3-8-flash",
+          "or-gemini-3-7-flash",
           "or-gemini-3-6-flash",
           "or-gemini-3-5-flash",
           "or-gemini-3-1-pro"
         ],
         "video_understanding_model_aliases" => {
+          "or-gemini-3-8-flash" => "Gemini 3.8 Flash",
+          "or-gemini-3-7-flash" => "Gemini 3.7 Flash",
           "or-gemini-3-6-flash" => "Gemini 3.6 Flash",
           "or-gemini-3-5-flash" => "Gemini 3.5 Flash",
           "or-gemini-3-1-pro"   => "Gemini 3.1 Pro"
         },
-        "default_video_understanding_model" => "or-gemini-3-6-flash",
+        "default_video_understanding_model" => "or-gemini-3-8-flash",
         # Default OCR sidecar — used when the primary model is text-only.
         # Candidates are derived from the provider's vision-capable models;
         # this just picks the cheap+fast default to surface in "auto" mode.
-        "default_ocr_model" => "or-gemini-3-6-flash",
+        "default_ocr_model" => "dsk-deepseek-v4-flash-vision-exp",
         # Provider-level default: the Claude family served here is vision-capable.
         "capabilities" => { "vision" => true }.freeze,
         # Model-level overrides: DeepSeek models routed through this provider
@@ -143,6 +154,7 @@ module Clacky
         # themselves, so they're intentionally not listed here as keys —
         # no injection happens when the default model is already lite-class.
         "lite_models" => {
+          "abs-claude-fable-5-1"  => "abs-claude-haiku-4-5",
           "abs-claude-fable-5"    => "abs-claude-haiku-4-5",
           "abs-claude-opus-5"     => "abs-claude-haiku-4-5",
           "abs-claude-opus-4-8"   => "abs-claude-haiku-4-5",
@@ -157,6 +169,7 @@ module Clacky
         # Fallback chain: if a model is unavailable, try the next one in order.
         # Keys are primary model names; values are the fallback model to use instead.
         "fallback_models" => {
+          "abs-claude-fable-5-1"  => "abs-claude-fable-5",
           "abs-claude-fable-5"    => "abs-claude-opus-5",
           "abs-claude-opus-5"     => "abs-claude-opus-4-8",
           "abs-claude-sonnet-5"   => "abs-claude-sonnet-4-6",
@@ -271,7 +284,7 @@ module Clacky
         "base_url" => "https://open.bigmodel.cn/api/paas/v4",
         "api" => "openai-completions",
         "default_model" => "glm-5.3",
-        "models" => ["glm-5.3", "glm-5.2", "glm-5.1", "glm-5", "glm-5-turbo", "glm-5v-turbo", "glm-4.7"],
+        "models" => ["glm-5.3", "glm-5.3-flash", "glm-5.2", "glm-5.1", "glm-5", "glm-5-turbo", "glm-5v-turbo", "glm-4.7"],
         # Zhipu / Z.ai expose four functionally-equivalent endpoints:
         # two regional sites (mainland open.bigmodel.cn + international api.z.ai)
         # each with a general-billing and a Coding-Plan subpath. They share the
@@ -287,10 +300,12 @@ module Clacky
           { "label" => "International · Pay-as-you-go", "label_key" => "settings.models.baseurl.variant.international_payg",  "base_url" => "https://api.z.ai/api/paas/v4",                "region" => "intl" }.freeze,
           { "label" => "International · Coding Plan",   "label_key" => "settings.models.baseurl.variant.international_coding","base_url" => "https://api.z.ai/api/coding/paas/v4",         "region" => "intl" }.freeze
         ].freeze,
-        # GLM models are text-only except glm-5v-turbo which is vision-capable ("v" = visual).
+        # GLM models are text-only except the vision-capable SKUs: glm-5v-turbo
+        # ("v" = visual) and glm-5.3-flash (GLM-5's first natively-multimodal model).
         "capabilities" => { "vision" => false }.freeze,
         "model_capabilities" => {
-          "glm-5v-turbo" => { "vision" => true }.freeze
+          "glm-5v-turbo" => { "vision" => true }.freeze,
+          "glm-5.3-flash" => { "vision" => true }.freeze
         }.freeze,
         "default_ocr_model" => "glm-5v-turbo",
         "website_url" => "https://open.bigmodel.cn/console/overview"
@@ -441,8 +456,9 @@ module Clacky
         "name" => "Qwen (Alibaba)",
         "base_url" => "https://dashscope.aliyuncs.com/compatible-mode/v1",
         "api" => "openai-completions",
-        "default_model" => "qwen3.7-max",
+        "default_model" => "qwen3.8-max",
         "models" => [
+          "qwen3.8-max",
           "qwen3.7-max",
           "qwen3.6-plus",
           "qwen3.6-max",
@@ -461,6 +477,7 @@ module Clacky
         }.freeze,
         "default_ocr_model" => "qwen3.6-flash",
         "lite_models" => {
+          "qwen3.8-max"      => "qwen3.6-flash",
           "qwen3.7-max"      => "qwen3.6-flash",
           "qwen3.6-plus"     => "qwen3.6-flash",
           "qwen3.6-max"      => "qwen3.6-flash",

data/lib/clacky/rich_ui/rich_ui_controller.rb

@@ -201,7 +201,7 @@ module Clacky
       end
     end
 
-    def show_assistant_message(content, files:, interim: false)
+    def show_assistant_message(content, files:, interim: false, created_at: nil)
       thinking_text, clean_text = extract_thinking_and_content(content)
       unless thinking_text.to_s.strip.empty?
         # Show live thinking with spinner + timer in fixed area
@@ -312,7 +312,7 @@ module Clacky
       @shell.sidebar.update_context(token_data) if @shell.sidebar
     end
 
-    def show_complete(iterations:, cost:, duration: nil, cache_stats: nil, awaiting_user_feedback: false, cost_source: nil)
+    def show_complete(iterations:, cost:, duration: nil, cache_stats: nil, awaiting_user_feedback: false, cost_source: nil, task_id: nil)
       set_idle_status
       return if awaiting_user_feedback || iterations <= 5
 

data/lib/clacky/server/channel/channel_manager.rb

@@ -26,16 +26,20 @@ module Clacky
       # @param session_builder    [Proc] (name:, working_dir:) => session_id — from HttpServer
       # @param run_agent_task     [Proc] (session_id, agent, &task) — from HttpServer
       # @param interrupt_session  [Proc] (session_id) — from HttpServer
+      # @param persist_session    [Proc] (agent) — from HttpServer; flushes the agent to
+      #   its session file. Needed because clearing a stale channel_info must survive a
+      #   restart, and ChannelManager has no direct access to the session store.
       # @param channel_config     [Clacky::ChannelConfig]
       # @param binding_mode       [:chat | :chat_user | :user] how to map IM identities to sessions.
       #   :chat (default)      — one session per chat (all users in a chat share it).
       #   :chat_user           — one session per (chat, user) pair.
       #   :user                — one session per user (merges all chats).
-      def initialize(session_registry:, session_builder:, run_agent_task:, interrupt_session:, channel_config:, binding_mode: :chat)
+      def initialize(session_registry:, session_builder:, run_agent_task:, interrupt_session:, channel_config:, persist_session: nil, binding_mode: :chat)
         @registry          = session_registry
         @session_builder   = session_builder
         @run_agent_task    = run_agent_task
         @interrupt_session = interrupt_session
+        @persist_session   = persist_session
         @channel_config    = channel_config
         @binding_mode      = binding_mode
         @adapters          = []
@@ -391,32 +395,49 @@ module Clacky
           end
 
           # Detach channel_ui from the old session's web_ui, reattach to the new one.
-          # Also clear the old session's persisted agent.channel_info if it still
-          # matches this key — keeping channel_keys and channel_info strictly in sync
-          # so resolve_session never sees two sessions claim the same key via different
-          # sources (see comment in resolve_session).
+          # Stale channel_info for this key is then cleared from every other session
+          # (including ones evicted from memory) so resolve_session and
+          # restore_channel_bindings never see two sessions claim the same key.
           old_session_id = resolve_session(event)
           channel_ui = old_session_id ? channel_ui_for_session(old_session_id) : nil
+          cleared_agent = nil
 
           if channel_ui
             @registry.with_session(old_session_id) do |s|
               s[:ui]&.unsubscribe_channel(channel_ui)
               s.delete(:channel_ui)
-              if s[:agent]&.respond_to?(:channel_info=) && s[:agent].respond_to?(:channel_info) &&
-                 s[:agent].channel_info && channel_key_from_info(s[:agent].channel_info) == key
-                s[:agent].channel_info = nil
+              agent = s[:agent]
+              if agent&.channel_info && channel_key_from_info(agent.channel_info) == key
+                agent.channel_info = nil
+                cleared_agent = agent
               end
             end
           else
             channel_ui = ChannelUIController.new(event, -> { adapter_for(event[:platform]) }, -> { @channel_config.status_messages_enabled? }, -> { @channel_config.process_messages_enabled? })
           end
 
+          @persist_session&.call(cleared_agent) if cleared_agent
+          clear_channel_info_for_key(key, keep_session_id: session_id)
+
           bind_key_to_session(key, session_id)
+          bound_agent = nil
           @registry.with_session(session_id) do |s|
             s[:ui]&.subscribe_channel(channel_ui)
             s[:channel_ui] = channel_ui
+
+            # Stamp channel_info now instead of waiting for the next inbound message
+            # (see route_message): a restart in between would otherwise find no session
+            # carrying this key and drop the binding.
+            agent = s[:agent]
+            if agent
+              agent.channel_info = extract_channel_info(event)
+              bound_agent = agent
+            end
           end
 
+          # Flush outside with_session: the registry mutex must not be held across file IO.
+          @persist_session&.call(bound_agent) if bound_agent
+
           Clacky::Logger.info("[ChannelManager] Bound #{key} -> session #{session_id[0, 8]}")
           adapter.send_text(chat_id, "Bound to session `#{session_id[0, 8]}`.")
 
@@ -431,21 +452,43 @@ module Clacky
 
         when "/unbind"
           unbound = false
+          cleared_agents = []
           @registry.list.each do |summary|
             @registry.with_session(summary[:id]) do |s|
-              if s[:channel_keys]&.delete(key)
-                unbound = true
-                # Keep agent.channel_info in sync with channel_keys (see resolve_session).
-                # Without this, after process restart + eviction, the fallback path would
-                # silently re-bind this key back to the unbinded session via stale
-                # channel_info, defeating /unbind.
-                if s[:agent]&.respond_to?(:channel_info=) && s[:agent].respond_to?(:channel_info) &&
-                   s[:agent].channel_info && channel_key_from_info(s[:agent].channel_info) == key
-                  s[:agent].channel_info = nil
-                end
+              # Set#delete always returns self — use delete? so an unknown key
+              # reports "No binding found." instead of a false "Unbound.".
+              next unless s[:channel_keys]&.delete?(key)
+
+              unbound = true
+
+              agent = s[:agent]
+              if agent&.channel_info && channel_key_from_info(agent.channel_info) == key
+                # Clear in memory here rather than relying on clear_channel_info_for_key:
+                # that scan reads the on-disk summary, which misses a channel_info that
+                # was stamped on this live agent but not persisted yet.
+                agent.channel_info = nil
+                cleared_agents << agent
+              end
+
+              # Detach channel_ui once the last key is gone, otherwise outbound
+              # broadcasts keep reaching the IM chat through web_ui's subscriber
+              # list even though inbound messages no longer resolve this session.
+              # Keys are a Set: a session may still be reachable via another key.
+              if s[:channel_keys].empty?
+                s[:ui]&.unsubscribe_channel(s[:channel_ui]) if s[:channel_ui]
+                s.delete(:channel_ui)
               end
             end
           end
+
+          if unbound
+            cleared_agents.each { |agent| @persist_session&.call(agent) }
+            # Drop channel_info everywhere else too: restore_channel_bindings would
+            # otherwise hand the key to an older session that still carries a stale
+            # copy on disk, silently re-binding it after a restart.
+            clear_channel_info_for_key(key)
+          end
+
           adapter.send_text(chat_id, unbound ? "Unbound." : "No binding found.")
 
         when "/status"
@@ -750,6 +793,38 @@ module Clacky
         result
       end
 
+      # Clear a stale agent.channel_info for `key` across every session except
+      # `keep_session_id`. Every inbound message stamps channel_info onto the
+      # bound agent (see route_message), so switching bindings leaves the field
+      # behind on older sessions. Those leftovers are what restore_channel_bindings
+      # reads at startup, letting an abandoned session silently reclaim the key.
+      # The on-disk summary is authoritative here, so sessions evicted from
+      # memory are cleaned too — which is exactly the case /bind used to miss.
+      def clear_channel_info_for_key(key, keep_session_id: nil)
+        @registry.list(limit: nil).each do |summary|
+          next if summary[:id] == keep_session_id
+
+          info = summary[:channel_info]
+          next unless info.is_a?(Hash) && info[:platform] && info[:user_id] && info[:chat_id]
+          next unless channel_key_from_info(info) == key
+          next unless @registry.ensure(summary[:id])
+
+          cleared = nil
+          @registry.with_session(summary[:id]) do |s|
+            agent = s[:agent]
+            next unless agent&.channel_info && channel_key_from_info(agent.channel_info) == key
+
+            agent.channel_info = nil
+            cleared = agent
+          end
+          next unless cleared
+
+          # Flush outside with_session: the registry mutex must not be held across file IO.
+          @persist_session&.call(cleared)
+          Clacky::Logger.info("[ChannelManager] Cleared stale channel_info #{key} from session #{summary[:id][0, 8]}")
+        end
+      end
+
       def bind_key_to_session(key, session_id)
         @registry.list.each do |summary|
           @registry.with_session(summary[:id]) { |s| s[:channel_keys]&.delete(key) }