openclacky 0.9.35 → 0.9.37

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ff82f5ba11ed8afdfb840119c249c078f0b10024e746230eedf093169f63ae55
-  data.tar.gz: 0fe062fa3b73f168aeddde5a3a81a936a24faaa7be1b99329f8707bf52d89fbe
+  metadata.gz: 951665db04cf6c2a4f8ef9b5c0555f4df91b84af08f63d21097d97cbd64d44b2
+  data.tar.gz: 82457a522007f54ecd5fcc36fee8e79cf16a65996dd9b95d7a00fd0dcfbc2cac
 SHA512:
-  metadata.gz: 1b7f42edce36076b5d467b6eefafdd02c40f381e25b9b010f0a32074ca51baea1a20545acdcde6a59467eb7a9b9b4fd930600f15a1858dd7aa54907ed855d391
-  data.tar.gz: edf9c74ae0704914ed4012984ee8642294e097092123ef9c79521e985857068df615946d74b6b059c69dd0868683e6706db971ec393b6fca44f961bbd190b403
+  metadata.gz: 031b1031a702aca3a7cee36ea8ba23bc4982e95f8381e59d07ecb652432f6bc8a40e9a386e4a254d640f18f0088d9e18fa1f6434d92c038844f4821cef40a703
+  data.tar.gz: 5c5c36517efebb37a7a44d0531e0baadedb8600319682c39696a971771852019f2649386e15a3505d9ae32e86cf8c5818c64cf36943247220a7db6e0df24e994

data/CHANGELOG.md

@@ -7,6 +7,31 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.9.37] - 2026-04-24
+
+### Fixed
+- **Critical: pinned sessions could silently disappear from the sidebar** ("the pinned one isn't showing, and refreshing sometimes fixes it"). Root cause: the backend `list` endpoint only sorted by `created_at` and applied `limit` blindly, so a pinned session older than the first page's rows was cut off entirely — the frontend's `byPinnedAndTime` sort never saw it. "Refreshing sometimes worked" only if the pinned session happened to be recent enough to land in the first 20 rows. Fix: `SessionRegistry#list` now partitions results and **always returns ALL matching pinned sessions on the first page regardless of `limit`**, followed by up to `limit` non-pinned sessions. The `before` cursor applies only to the non-pinned section, so "load more" pages never re-send or duplicate pinned rows. `/api/sessions`'s `has_more` is now computed from non-pinned overflow only. Frontend `loadMore` cursor also excludes pinned rows so pagination jumps correctly. Regression specs cover: (a) an old pinned session still appears when `limit=3`, (b) multiple pinned sessions all fit on page one with `limit=1`, (c) pinned sessions never duplicate into `before`-cursor pages.
+- **Critical: saving one model in Web UI Settings silently wiped other models' API keys.** The 0.9.36 index→id refactor (commit `b61e22e`) rebuilt each model hash from scratch on save (`"api_key" => api_key.to_s`), dropping the old `existing["api_key"] = api_key if api_key` guard. Combined with `/api/config` returning only `api_key_masked` (never `api_key`), every non-edited row in the POST body arrived with `api_key: undefined` — the backend then rewrote those rows' keys to `""`. Now `api_save_config` has three explicit cases for resolving `api_key`: (1) masked placeholder → keep stored key, (2) **missing/blank on an existing row → keep stored key (this fix)**, (3) otherwise use incoming value. Brand-new models (no `id`) still create with an empty key as before.
+- **Critical: in-app upgrade no longer falsely reports failure.** The 0.9.36 upgrade flow shared a PTY helper (`run_shell`) with the new unified Terminal tool, which — by design — returns early with a `session_id` when command output stays quiet for 3 seconds. Long-running `gem install` operations routinely hit this during dependency resolution, causing the Web UI to show `✗ Upgrade failed.` even when the gem installed successfully. `run_shell` now delegates to a new `Terminal.run_sync` Ruby API that polls until the command truly completes, and `finish_upgrade` additionally re-checks the installed gem version as a defensive fallback.
+- **Critical: "历史记录获取失败 (500: source sequence is illegal/malformed utf-8)" when opening a session.** When `file_reader` / `edit` / `grep` / `glob` encountered a file with non-UTF-8 bytes (e.g. GBK-encoded text or a Chinese Windows-exported CSV), the dirty bytes flowed through tool results into the agent history and session chunks on disk. Later, when `GET /api/sessions/:id/messages` replayed that history, `JSON.generate` would blow up on the invalid byte sequence and return 500. Now every IO source point scrubs invalid bytes to U+FFFD (`�`) at read time: `file_reader` (both content and directory entry names), `edit`, `grep` (`File.foreach` + context `readlines`), `glob` (`Dir.glob` path strings), `session_serializer` (chunk md replay), and `tool_executor` (diff preview). A defense-in-depth layer in `MessageHistory#append` / `#replace_all` recursively sanitizes every string that enters the message tree — so even a future tool that forgets to scrub cannot poison the session.
+
+### Added
+- **New `Terminal.run_sync` internal API** for Ruby callers that need synchronous command capture (drop-in replacement for `Open3.capture2e`, but using the same PTY + login-shell + Security pipeline as the AI-facing tool).
+- **DeepSeek V4 provider preset.** New `deepseekv4` entry in `Clacky::Providers` (positioned right after `openrouter`) with default model `deepseek-v4-pro` and models list `deepseek-v4-flash`, `deepseek-v4-pro`, plus the deprecated-aliases `deepseek-chat` / `deepseek-reasoner` (to be removed on 2026-07-24). Uses the OpenAI-compatible endpoint `https://api.deepseek.com`; for Anthropic-format usage, point `base_url` at `https://api.deepseek.com/anthropic` and switch `api` to `anthropic-messages`.
+- **DeepSeek V4 pricing.** Added `deepseek-v4-flash` ($0.14 in / $0.28 out / $0.028 cache-hit per MTok) and `deepseek-v4-pro` ($1.74 in / $3.48 out / $0.145 cache-hit per MTok) to `Clacky::ModelPricing::PRICING_TABLE`. Legacy aliases `deepseek-chat` and `deepseek-reasoner` normalize to `deepseek-v4-flash`. DeepSeek has no separate cache-write charge, so cache writes are billed at the cache-miss (input) rate. Prices sourced from the official pricing page (USD per 1M tokens).
+
+## [0.9.36] - 2026-04-24
+
+### Fixed
+- **Session deletion now works correctly**: fixed disk-based session deletion that was failing with proper error handling in the Web UI (C-9d1ea93)
+- **Model switching improved**: better model ID validation and normalization when switching models in Web UI — handles various ID formats correctly (C-b61e22e)
+- **Terminal tool word wrapping**: fixed terminal output word wrapping issues that could break long command outputs (C-5989d02)
+- **Heartbeat mechanism stability**: improved async heartbeat logic in server mode for more reliable connection status tracking (C-5989d02)
+
+### Improved
+- **UI polish**: removed session topbar clutter and added empty state messages for better first-time user experience (C-003d613)
+- **Cleaner logging**: reduced noisy debug logs in skill manager for quieter operation (C-c27bbec)
+
 ## [0.9.35] - 2026-04-23
 
 ### Added

data/lib/clacky/agent/session_serializer.rb

@@ -243,7 +243,12 @@ module Clacky
         end
         visited = visited.dup.add(canonical)
 
-        raw = File.read(resolved)
+        # Scrub invalid UTF-8 bytes defensively — chunk files written before
+        # the 0.9.37 fix may contain poisoned bytes from file_reader results.
+        raw = File.read(resolved).then do |s|
+          s.encoding == Encoding::UTF_8 && s.valid_encoding? ? s :
+            s.encode("UTF-8", invalid: :replace, undef: :replace, replace: "\u{FFFD}")
+        end
 
         # Parse YAML front matter to get archived_at for synthetic timestamps
         archived_at = nil

data/lib/clacky/agent/skill_manager.rb

@@ -68,15 +68,27 @@ module Clacky
         all_skills = all_skills.reject(&:invalid?)
         auto_invocable = all_skills.select(&:model_invocation_allowed?)
 
-        # Enforce system prompt injection limit to control token usage
+        # Enforce system prompt injection limit to control token usage.
+        # Warn only when the set of dropped skills *changes* — this message
+        # is otherwise emitted once per agent turn (build_skill_context is
+        # called during every system prompt assembly) and floods the log.
         if auto_invocable.size > MAX_CONTEXT_SKILLS
-          dropped = auto_invocable.size - MAX_CONTEXT_SKILLS
-          Clacky::Logger.warn(
-            "Skill context limit: #{auto_invocable.size} auto-invocable skills found, " \
-            "only injecting first #{MAX_CONTEXT_SKILLS} (#{dropped} dropped). " \
-            "Remove unused skills to restore full visibility."
-          )
-          auto_invocable = auto_invocable.first(MAX_CONTEXT_SKILLS)
+          kept    = auto_invocable.first(MAX_CONTEXT_SKILLS)
+          dropped = auto_invocable.drop(MAX_CONTEXT_SKILLS)
+          dropped_names = dropped.map(&:identifier)
+          signature = dropped_names.sort.join(",")
+
+          if @skill_limit_warned_signature != signature
+            @skill_limit_warned_signature = signature
+            Clacky::Logger.warn(
+              "Skill context limit: #{auto_invocable.size} auto-invocable skills found, " \
+              "only injecting first #{MAX_CONTEXT_SKILLS} " \
+              "(#{dropped.size} dropped — will NOT be auto-discovered by the agent: " \
+              "#{dropped_names.join(", ")}). " \
+              "Remove unused skills to restore full visibility."
+            )
+          end
+          auto_invocable = kept
         end
 
         return "" if auto_invocable.empty?

data/lib/clacky/agent/tool_executor.rb

@@ -358,6 +358,7 @@ module Clacky
           @ui&.show_diff("", new_content, max_lines: 50)
         else
           old_content = File.read(expanded_path)
+          old_content = old_content.encode("UTF-8", invalid: :replace, undef: :replace, replace: "\u{FFFD}") unless old_content.encoding == Encoding::UTF_8 && old_content.valid_encoding?
           @ui&.show_diff(old_content, new_content, max_lines: 50)
         end
         nil

data/lib/clacky/agent.rb

@@ -131,14 +131,21 @@ module Clacky
       @hooks.add(event, &block)
     end
 
-    # Switch to a different model by index
-    # @param index [Integer] Model index (0-based)
+    # Switch this session to a different model, identified by its stable
+    # runtime id. Ids survive list reorders, additions, and field edits,
+    # which is why we no longer expose an index-based API.
+    # @param id [String] Model id (see AgentConfig#parse_models)
     # @return [Boolean] true if switched successfully, false otherwise
-    def switch_model(index)
-      # Switch config to the model by index
-      return false unless @config.switch_model(index)
-      
-      # Re-create client for new model
+    def switch_model_by_id(id)
+      return false unless @config.switch_model_by_id(id)
+
+      rebuild_client_for_current_model!
+      true
+    end
+
+    # Rebuild the underlying Client (and dependent components) to pick up
+    # credentials/model name from the currently-selected model in @config.
+    private def rebuild_client_for_current_model!
       @client = Clacky::Client.new(
         @config.api_key,
         base_url: @config.base_url,
@@ -147,11 +154,9 @@ module Clacky
       )
       # Update message compressor with new client and model
       @message_compressor = MessageCompressor.new(@client, model: current_model)
-      
+
       # Inject a new session context to notify the AI of the model switch
       inject_session_context
-      
-      true
     end
 
     # Change the working directory for this session
@@ -987,16 +992,16 @@ module Clacky
         if model == "lite"
           # Special keyword: use lite model if available, otherwise fall back to default
           lite_model = subagent_config.lite_model
-          if lite_model
-            model_index = subagent_config.models.index(lite_model)
-            subagent_config.switch_model(model_index) if model_index
+          if lite_model && lite_model["id"]
+            subagent_config.switch_model_by_id(lite_model["id"])
           end
           # If no lite model, just use current (default) model
         else
-          # Regular model name lookup
-          model_index = subagent_config.model_names.index(model)
-          if model_index
-            subagent_config.switch_model(model_index)
+          # Regular model name lookup — find the first model with a matching
+          # name and switch by its stable id.
+          target = subagent_config.models.find { |m| m["model"] == model }
+          if target && target["id"]
+            subagent_config.switch_model_by_id(target["id"])
           else
             raise AgentError, "Model '#{model}' not found in config. Available models: #{subagent_config.model_names.join(', ')}"
           end

data/lib/clacky/agent_config.rb

@@ -2,6 +2,7 @@
 
 require "yaml"
 require "fileutils"
+require "securerandom"
 
 module Clacky
   # ClaudeCode environment variable compatibility layer
@@ -152,7 +153,7 @@ module Clacky
 
     attr_accessor :permission_mode, :max_tokens, :verbose,
                   :enable_compression, :enable_prompt_caching,
-                  :models, :current_model_index,
+                  :models, :current_model_index, :current_model_id,
                   :memory_update_enabled, :skill_evolution
 
     def initialize(options = {})
@@ -165,7 +166,22 @@ module Clacky
 
       # Models configuration
       @models = options[:models] || []
+      # Ensure every model has a stable runtime id — this is the single
+      # invariant the rest of the system relies on. Regardless of how the
+      # config was built (load from yml, direct .new in tests, add_model,
+      # api_save_config), every model in @models will have an id.
+      @models.each { |m| m["id"] ||= SecureRandom.uuid }
+
       @current_model_index = options[:current_model_index] || 0
+      # Stable runtime id for the currently-selected model. Preferred over
+      # @current_model_index because ids are immune to list reordering,
+      # additions, and edits to model fields. Ids are injected at load time
+      # and never persisted to config.yml (backward compatible with old files).
+      # If caller didn't specify current_model_id, prefer the model marked
+      # as `type: default` (the documented convention), falling back to
+      # models[current_model_index] only if no default marker exists.
+      @current_model_id = options[:current_model_id] ||
+                          (@models.find { |m| m["type"] == "default" } || @models[@current_model_index])&.dig("id")
 
       # Memory and skill evolution configuration
       @memory_update_enabled = options[:memory_update_enabled].nil? ? true : options[:memory_update_enabled]
@@ -238,11 +254,17 @@ module Clacky
       # The injected lite model is runtime-only (not persisted to config.yml)
       inject_provider_lite_model(models)
 
+      # Ensure every model has a stable runtime id — covers env-injected
+      # models (CLACKY_XXX, CLAUDE_XXX) that don't go through parse_models.
+      # Ids are NOT persisted to config.yml (see to_yaml).
+      models.each { |m| m["id"] ||= SecureRandom.uuid }
+
       # Find the index of the model marked as "default" (type: default)
       # Fall back to 0 if no model has type: default
       default_index = models.find_index { |m| m["type"] == "default" } || 0
+      default_id = models[default_index] && models[default_index]["id"]
 
-      new(models: models, current_model_index: default_index)
+      new(models: models, current_model_index: default_index, current_model_id: default_id)
     end
 
     # Auto-inject a lite model entry if the default model's provider supports one
@@ -270,19 +292,35 @@ module Clacky
         "model"            => lite_model_name,
         "anthropic_format" => default_model["anthropic_format"] || false,
         "type"             => "lite",
-        "auto_injected"    => true  # Mark as auto-injected (not saved to file)
+        "auto_injected"    => true,  # Mark as auto-injected (not saved to file)
+        "id"               => SecureRandom.uuid  # Runtime id for stable session references
       }
     end
 
-    # Save configuration to file
-    # Deep copy — models array contains mutable Hashes, so a shallow dup would
-    # let the copy share the same Hash objects with the original, causing
-    # Settings changes to silently mutate already-running session configs.
-    # JSON round-trip is the cleanest approach since @models is pure JSON-able data.
+    # Create a per-session copy of this config.
+    #
+    # Plan B (shared models): we deliberately share the SAME @models array
+    # reference with all sessions (no deep clone). This is the key design
+    # decision that keeps session and global views in sync:
+    #   - User adds a model in Settings → every live session sees it instantly.
+    #   - User edits api_key/base_url → every live session's next API call
+    #     picks up the new credentials (via current_model lookup).
+    #   - Model ids are stable across edits, so each session's
+    #     @current_model_id continues to resolve correctly.
+    #
+    # Per-session state that MUST stay isolated (permission_mode,
+    # @current_model_id, @current_model_index, fallback state) are scalar
+    # copies via `dup` and don't leak between sessions.
+    #
+    # Before Plan B, sessions held deep-copied @models — which silently
+    # diverged from the global list any time the user added/edited a model
+    # in Settings, producing bugs like "Failed to switch model" for newly
+    # added models on Windows and Linux. See http_server.rb#api_switch_session_model
+    # and http_server.rb#api_save_config for the companion logic.
     def deep_copy
-      copy = dup
-      copy.instance_variable_set(:@models, JSON.parse(JSON.generate(@models)))
-      copy
+      # dup gives us a new AgentConfig with independent scalar ivars but
+      # the same @models reference — exactly what we want.
+      dup
     end
 
     def save(config_file = CONFIG_FILE)
@@ -295,8 +333,14 @@ module Clacky
     # Convert to YAML format (top-level array)
     # Auto-injected lite models (auto_injected: true) are excluded from persistence —
     # they are regenerated at load time from the provider preset.
+    # Runtime-only fields (id, auto_injected) are stripped before writing so
+    # config.yml remains backward compatible with users on older versions.
+    RUNTIME_ONLY_FIELDS = %w[id auto_injected].freeze
+
     def to_yaml
-      persistable = @models.reject { |m| m["auto_injected"] }
+      persistable = @models.reject { |m| m["auto_injected"] }.map do |m|
+        m.reject { |k, _| RUNTIME_ONLY_FIELDS.include?(k) }
+      end
       YAML.dump(persistable)
     end
 
@@ -305,32 +349,80 @@ module Clacky
       !@models.empty? && !current_model.nil?
     end
 
-    # Get current model configuration
-    def current_model
-      return nil if @models.empty?
-      @models[@current_model_index]
-    end
+    # NOTE: current_model is defined below (near the id-aware lookup path)
+    # — the earlier duplicate definition was removed. Ruby silently picks the
+    # last definition, but keeping only one avoids confusion.
 
     # Get model by index
     def get_model(index)
       @models[index]
     end
 
-    # Switch to model by index
-    # Updates the type: default to the selected model
-    # Returns true if switched, false if index out of range
-    def switch_model(index)
-      return false if index < 0 || index >= @models.length
-      
-      # Remove type: default from all models
-      @models.each { |m| m.delete("type") if m["type"] == "default" }
-      
-      # Set type: default on the selected model
-      @models[index]["type"] = "default"
-      
-      # Update current_model_index for backward compatibility
+    # Switch the current session to a specific model, identified by its
+    # stable runtime id.
+    #
+    # This is a **per-session** operation:
+    #   - Updates this AgentConfig's `@current_model_id` (primary truth)
+    #   - Updates `@current_model_index` for back-compat observers
+    #   - Does NOT mutate the shared `@models` array's `type: "default"`
+    #     marker. The "default model" is a global setting (initial model
+    #     for new sessions) and is only changed via the Settings UI
+    #     "save config" flow (`api_save_config`).
+    #
+    # @param id [String] the model's runtime id (see parse_models)
+    # @return [Boolean] true if switched, false if id not found
+    def switch_model_by_id(id)
+      return false if id.nil? || id.to_s.empty?
+
+      index = @models.find_index { |m| m["id"] == id }
+      return false if index.nil?
+
+      @current_model_id = id
       @current_model_index = index
-      
+
+      true
+    end
+
+    # Set the **global** default model marker (`type: "default"`).
+    #
+    # This is separate from `switch_model_by_id`:
+    #   - `switch_model_by_id` only changes this session's current model.
+    #   - `set_default_model_by_id` mutates the shared `@models` array by
+    #     moving the `type: "default"` marker to the given model.
+    #
+    # Use cases:
+    #   - CLI (single-session): when the user picks a model, we both switch
+    #     this session AND update the global default so future CLI launches
+    #     use the same model. Caller must `save` to persist.
+    #   - Web UI Settings save flow: also uses this (via payload).
+    #
+    # Do NOT call from per-session model switching in multi-session contexts
+    # (Web UI session-level switch), since it would leak into other sessions
+    # and change what new sessions start with.
+    #
+    # Only one model may carry `type: "default"` at a time — this method
+    # clears the marker on any other model that had it.
+    #
+    # Note: if the target model currently has `type: "lite"`, this method
+    # will overwrite it with `"default"`. That matches the existing
+    # single-slot `type` field semantics in the codebase.
+    #
+    # @param id [String] the model's runtime id
+    # @return [Boolean] true if marker was moved, false if id not found
+    def set_default_model_by_id(id)
+      return false if id.nil? || id.to_s.empty?
+
+      target = @models.find { |m| m["id"] == id }
+      return false if target.nil?
+
+      # Clear existing default marker(s) — there should only be one, but
+      # be defensive in case of corrupted config.
+      @models.each do |m|
+        next if m["id"] == id
+        m.delete("type") if m["type"] == "default"
+      end
+
+      target["type"] = "default"
       true
     end
 
@@ -385,6 +477,7 @@ module Clacky
     # Add a new model configuration
     def add_model(model:, api_key:, base_url:, anthropic_format: false, type: nil)
       @models << {
+        "id" => SecureRandom.uuid,
         "api_key" => api_key,
         "base_url" => base_url,
         "model" => model,
@@ -486,15 +579,35 @@ module Clacky
       end
     end
 
-    # Get current model configuration
-    # Looks for type: default first, falls back to current_model_index
+    # Get current model configuration.
+    #
+    # Resolution order:
+    #   1. @current_model_id (primary source of truth — stable across list edits)
+    #   2. type: default (for config.yml that sets a default explicitly)
+    #   3. @current_model_index (back-compat for very old code paths)
     def current_model
       return nil if @models.empty?
+
+      if @current_model_id
+        m = @models.find { |mm| mm["id"] == @current_model_id }
+        return m if m
+        # id no longer exists (model was deleted). Fall through to other
+        # resolution strategies below, and clear the stale id.
+        @current_model_id = nil
+      end
+
       default_model = find_model_by_type("default")
-      return default_model if default_model
-      
+      if default_model
+        # Opportunistically re-anchor to this default's id so subsequent
+        # lookups are O(1) and survive list reordering.
+        @current_model_id = default_model["id"]
+        return default_model
+      end
+
       # Fallback to index-based for backward compatibility
-      @models[@current_model_index]
+      m = @models[@current_model_index]
+      @current_model_id = m["id"] if m
+      m
     end
 
     # Set a model's type (default or lite)
@@ -528,14 +641,20 @@ module Clacky
       # Don't allow removing the last model
       return false if @models.length <= 1
       return false if index < 0 || index >= @models.length
-      
-      @models.delete_at(index)
-      
+
+      removed = @models.delete_at(index)
+
       # Adjust current_model_index if necessary
       if @current_model_index >= @models.length
         @current_model_index = @models.length - 1
       end
-      
+
+      # If the removed model was the current one, clear @current_model_id.
+      # current_model will then fall back to type: default / current_model_index.
+      if removed && @current_model_id == removed["id"]
+        @current_model_id = nil
+      end
+
       true
     end
 
@@ -615,6 +734,13 @@ module Clacky
         }
       end
 
+      # Inject a runtime-only stable id for each model. Ids are NOT written
+      # back to config.yml (see `to_yaml`) so this is fully backward
+      # compatible — old yml files without ids just get fresh ids on load.
+      # The id is the source of truth for session→model identity and is
+      # immune to list reordering, additions, and field edits (api_key, etc).
+      models.each { |m| m["id"] ||= SecureRandom.uuid }
+
       models
     end
   end

data/lib/clacky/cli.rb

@@ -271,26 +271,45 @@ module Clacky
         end
 
         if brand.heartbeat_due?
-          Clacky::Logger.info("[Brand] check_brand_license_cli: heartbeat due, sending...")
-          result = brand.heartbeat!
-          if result[:success]
-            Clacky::Logger.info("[Brand] check_brand_license_cli: heartbeat OK")
-          else
-            Clacky::Logger.warn("[Brand] check_brand_license_cli: heartbeat failed — #{result[:message]} grace_exceeded=#{brand.grace_period_exceeded?}")
-            unless result[:success]
-              if brand.grace_period_exceeded?
-                say ""
-                say "WARNING: Could not reach the #{brand.product_name} license server.", :yellow
-                say "License has been offline for more than 3 days. Please check your connection.", :yellow
-                say ""
+          # Fire-and-forget heartbeat in a background thread.
+          #
+          # Rationale: a slow/unreachable license server would otherwise block
+          # CLI startup for up to ~92s (2 hosts × 2 attempts × 23s timeout)
+          # before the user sees the prompt. Heartbeat is "best-effort" by
+          # design — its only job is to refresh `last_heartbeat` / `expires_at`
+          # on disk for the next run's grace-period calculation. Missing a
+          # single heartbeat is harmless; the next launch will try again.
+          #
+          # Consequence: if this run was going to trigger the
+          # grace_period_exceeded warning, the user will see it on the *next*
+          # launch instead of this one. Acceptable trade-off.
+          Clacky::Logger.info("[Brand] check_brand_license_cli: heartbeat due, dispatching async...")
+          Thread.new do
+            begin
+              result = brand.heartbeat!
+              if result[:success]
+                Clacky::Logger.info("[Brand] async heartbeat OK")
               else
-                say "(License heartbeat failed - will retry tomorrow.)", :cyan
+                Clacky::Logger.warn("[Brand] async heartbeat failed — #{result[:message]}")
               end
+            rescue StandardError => e
+              Clacky::Logger.warn("[Brand] async heartbeat raised: #{e.class}: #{e.message}")
             end
           end
         else
           Clacky::Logger.debug("[Brand] check_brand_license_cli: heartbeat not due yet")
         end
+
+        # Surface the grace-period warning based on *already-persisted* state
+        # (computed from last_heartbeat on disk). This works whether the
+        # previous run's heartbeat succeeded, failed, or was interrupted —
+        # grace_period_exceeded? reads last_heartbeat, not this run's result.
+        if brand.grace_period_exceeded?
+          say ""
+          say "WARNING: Could not reach the #{brand.product_name} license server.", :yellow
+          say "License has been offline for more than 3 days. Please check your connection.", :yellow
+          say ""
+        end
       end
 
       # Interactive license key prompt using tty-prompt.

data/lib/clacky/message_history.rb

@@ -34,7 +34,7 @@ module Clacky
       if message[:role] == "user"
         drop_dangling_tool_calls!
       end
-      @messages << message
+      @messages << deep_sanitize_utf8(message)
       self
     end
 
@@ -53,7 +53,7 @@ module Clacky
 
     # Replace the entire message list (used by compression rebuild).
     def replace_all(new_messages)
-      @messages = new_messages.dup
+      @messages = new_messages.map { |m| deep_sanitize_utf8(m) }
       self
     end
 
@@ -229,5 +229,46 @@ module Clacky
     private def strip_internal_fields(message)
       message.reject { |k, _| INTERNAL_FIELDS.include?(k) }
     end
+
+    # Defense-in-depth: recursively scrub invalid UTF-8 bytes from every String
+    # stored in the message tree. Even if a tool forgets to scrub its output,
+    # nothing poisoned will ever reach session persistence or JSON.generate.
+    #
+    # Fast path: if the tree contains only valid UTF-8 strings, the original
+    # object is returned unchanged — preserving object identity for callers
+    # that rely on `equal?` (e.g. rollback_before).
+    # Slow path: any invalid byte triggers a rebuild with scrubbed strings
+    # (invalid bytes → U+FFFD).
+    private def deep_sanitize_utf8(obj)
+      case obj
+      when String
+        return obj if obj.encoding == Encoding::UTF_8 && obj.valid_encoding?
+        obj.encode("UTF-8", invalid: :replace, undef: :replace, replace: "\u{FFFD}")
+      when Hash
+        return obj unless contains_dirty_utf8?(obj)
+        obj.transform_values { |v| deep_sanitize_utf8(v) }
+      when Array
+        return obj unless contains_dirty_utf8?(obj)
+        obj.map { |v| deep_sanitize_utf8(v) }
+      else
+        obj
+      end
+    end
+
+    # Cheap recursive check: does this subtree contain any invalid-UTF-8 string?
+    # Short-circuits on first offender. Keeps the common case (all valid UTF-8)
+    # allocation-free.
+    private def contains_dirty_utf8?(obj)
+      case obj
+      when String
+        !(obj.encoding == Encoding::UTF_8 && obj.valid_encoding?)
+      when Hash
+        obj.any? { |_, v| contains_dirty_utf8?(v) }
+      when Array
+        obj.any? { |v| contains_dirty_utf8?(v) }
+      else
+        false
+      end
+    end
   end
 end

data/lib/clacky/providers.rb

@@ -41,6 +41,27 @@ module Clacky
         "website_url" => "https://openrouter.ai/keys"
       }.freeze,
 
+      "deepseekv4" => {
+        "name" => "DeepSeek V4",
+        # DeepSeek API is compatible with both OpenAI and Anthropic formats.
+        # We use the OpenAI-compatible endpoint here (matches kimi/minimax/glm style).
+        # For Anthropic-format usage, point base_url at https://api.deepseek.com/anthropic
+        # and change "api" to "anthropic-messages".
+        "base_url" => "https://api.deepseek.com",
+        "api" => "openai-completions",
+        "default_model" => "deepseek-v4-pro",
+        # Note: deepseek-chat and deepseek-reasoner are legacy aliases being
+        # deprecated on 2026-07-24; they map to deepseek-v4-flash's non-thinking
+        # and thinking modes respectively. Prefer deepseek-v4-flash / deepseek-v4-pro.
+        "models" => [
+          "deepseek-v4-flash",
+          "deepseek-v4-pro",
+          "deepseek-chat",
+          "deepseek-reasoner"
+        ],
+        "website_url" => "https://platform.deepseek.com/api_keys"
+      }.freeze,
+
       "minimax" => {
         "name" => "Minimax",
         "base_url" => "https://api.minimaxi.com/v1",