openclacky 0.8.3 → 0.8.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 473dceae1c35bc7eeb4095df2f35ea1403f6013168a3daf3318a709df4ce40ec
-  data.tar.gz: 9b7b97d917e13bf43ffff8fe50fda4f1eade74cd530e45959af46d9dbd313043
+  metadata.gz: e9d125c88f92f71da5a1e3699c8c466886ef7077e8578b7abbf2a6e3c9c966c2
+  data.tar.gz: 852e04561b92ceaa5af0359996533bbfaf63a14559e528e7f58b48af6b85206d
 SHA512:
-  metadata.gz: 6717eccea955e82d4dfa4381cb99707785d6ac36c3875ac622d51e854007d2997b16155af3e48d2b644aae3635d3989152a03e6f069bf525d8a8630049b6dfb0
-  data.tar.gz: 58cd3940c885363ae315e0430a318bb181713cdd0e5d1d4f7308343ce357f44075fd06cb8c4882f75824f857211c85c231b3d8b0cb2babe71ef6c76b5f21371c
+  metadata.gz: bfe068e23d38dd526ef634b940b6f4b4cb02297266b371d64294acd82ca40fac428fef16fec80e726907e1e4170f7d02b3515f723ac5da07ad888b32f621604d
+  data.tar.gz: 8ebdf651e254793b5e18f933167ee80abce8fea3405fe969e789adf85f3689c819eebe691f5783263c9581bf82dbaddeea514e5959d079370b28d843e2e022ab

data/CHANGELOG.md

@@ -7,6 +7,27 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.8.4] - 2026-03-10
+
+### Added
+- **License verify & download skills**: brand distribution can now push skills to clients via license heartbeat — skills are downloaded and installed automatically on activation and heartbeat
+- **Web UI theme system**: dark/light mode toggle with full CSS variable theming, persistent across sessions; all UI components (sessions, tasks, settings) updated to use theme variables
+
+### Improved
+- **Skill loader default agent**: `SkillLoader` now applies a sensible default agent value, simplifying skill configuration for common cases
+- **Web UI modernized**: redesigned session and task lists with active indicators, improved hover effects, and inline SVG icons (removed Lucide CDN dependency)
+
+### Fixed
+- **UTF-8 input handling**: invalid UTF-8 bytes in terminal UI input and output are now scrubbed cleanly instead of raising encoding errors
+- **UI thread deadlock**: progress and fullscreen threads now stop gracefully on shutdown, preventing rare deadlocks
+- **IME composition input**: slash `/` command button is now disabled during IME composition (e.g. Chinese input), preventing double-submit on Enter
+- **CLI `clear` command**: fixed a regression that broke the `clacky clear` command
+
+### More
+- Refactor: rename `set_skill_loader` to `set_agent` in `UiController` for clarity
+- Chore: update onboard skill default AI identity wording
+- Fix: append user shim after skill injection for Claude API compatibility
+
 ## [0.8.3] - 2026-03-09
 
 ### Added

data/lib/clacky/agent/skill_manager.rb

@@ -158,7 +158,18 @@ module Clacky
         # Expand skill content (substitutes $ARGUMENTS if present)
         expanded_content = skill.process_content(arguments, template_context: build_template_context)
 
-        # Inject as a synthetic assistant message so the LLM treats it as already read
+        # Inject as a synthetic assistant message so the LLM treats it as already read.
+        #
+        # Then immediately append a synthetic user message to keep the conversation
+        # sequence valid for strict providers like Claude (Anthropic API), which require
+        # alternating user/assistant turns. Without this extra user message the next
+        # real LLM call would find an assistant message at the tail of the history,
+        # causing a 400 "invalid message order" error.
+        #
+        # Final message order:
+        #   user:      "/skill-name [args]"          ← real user input
+        #   assistant: "[expanded skill content]"    ← system_injected (skill instructions)
+        #   user:      "[SYSTEM] Please proceed..."  ← system_injected (Claude compat shim)
         @messages << {
           role: "assistant",
           content: expanded_content,
@@ -166,6 +177,13 @@ module Clacky
           system_injected: true
         }
 
+        @messages << {
+          role: "user",
+          content: "[SYSTEM] The skill instructions above have been loaded. Please proceed to execute the task now.",
+          task_id: task_id,
+          system_injected: true
+        }
+
         @ui&.log("Injected skill content for /#{skill.identifier}", level: :info)
       end
 

data/lib/clacky/agent.rb

@@ -76,7 +76,7 @@ module Clacky
       @brand_config = Clacky::BrandConfig.load
 
       # Skill loader for skill management (brand_config enables encrypted skill loading)
-      @skill_loader = SkillLoader.new(@working_dir, brand_config: @brand_config)
+      @skill_loader = SkillLoader.new(working_dir: @working_dir, brand_config: @brand_config)
 
       # Background sync: compare remote skill versions and download updates quietly.
       # Runs in a daemon thread so Agent startup is never blocked.

data/lib/clacky/brand_config.rb

@@ -18,6 +18,10 @@ module Clacky
   #
   # brand.yml structure:
   #   brand_name: "JohnAI"
+  #   distribution_name: "JohnAI Distribution"
+  #   product_name: "JohnAI Pro"
+  #   logo_url: "https://example.com/logo.png"
+  #   support_contact: "support@johnai.com"
   #   license_key: "0000002A-00000007-DEADBEEF-CAFEBABE-A1B2C3D4"
   #   license_activated_at: "2025-03-01T00:00:00Z"
   #   license_expires_at: "2026-03-01T00:00:00Z"
@@ -38,11 +42,16 @@ module Clacky
 
     attr_reader :brand_name, :license_key, :license_activated_at,
                 :license_expires_at, :license_last_heartbeat, :device_id,
-                :brand_command
+                :brand_command, :distribution_name, :product_name,
+                :logo_url, :support_contact
 
     def initialize(attrs = {})
       @brand_name              = attrs["brand_name"]
       @brand_command           = attrs["brand_command"]
+      @distribution_name       = attrs["distribution_name"]
+      @product_name            = attrs["product_name"]
+      @logo_url                = attrs["logo_url"]
+      @support_contact         = attrs["support_contact"]
       @license_key             = attrs["license_key"]
       @license_activated_at    = parse_time(attrs["license_activated_at"])
       @license_expires_at      = parse_time(attrs["license_expires_at"])
@@ -131,6 +140,7 @@ module Clacky
         @license_expires_at     = parse_time(data["expires_at"])
         # Use brand_name returned by the API; fall back to any existing value
         @brand_name = data["brand_name"] if data["brand_name"] && !data["brand_name"].to_s.strip.empty?
+        apply_distribution(data["distribution"])
         save
         { success: true, message: "License activated successfully!", brand_name: @brand_name, data: data }
       else
@@ -175,12 +185,14 @@ module Clacky
       return { success: false, message: "License not activated" } unless activated?
 
       user_id   = parse_user_id_from_key(@license_key)
+      key_hash  = Digest::SHA256.hexdigest(@license_key)
       ts        = Time.now.utc.to_i.to_s
       nonce     = SecureRandom.hex(16)
       message   = "#{user_id}:#{@device_id}:#{ts}:#{nonce}"
       signature = OpenSSL::HMAC.hexdigest("SHA256", @license_key, message)
 
       payload = {
+        key_hash:  key_hash,
         user_id:   user_id.to_s,
         device_id: @device_id,
         timestamp: ts,
@@ -193,6 +205,7 @@ module Clacky
       if response[:success]
         @license_last_heartbeat = Time.now.utc
         @license_expires_at = parse_time(response[:data]["expires_at"]) if response[:data]["expires_at"]
+        apply_distribution(response[:data]["distribution"])
         save
         { success: true, message: "Heartbeat OK" }
       else
@@ -206,12 +219,14 @@ module Clacky
       return { success: false, error: "License not activated", skills: [] } unless activated?
 
       user_id   = parse_user_id_from_key(@license_key)
+      key_hash  = Digest::SHA256.hexdigest(@license_key)
       ts        = Time.now.utc.to_i.to_s
       nonce     = SecureRandom.hex(16)
       message   = "#{user_id}:#{@device_id}:#{ts}:#{nonce}"
       signature = OpenSSL::HMAC.hexdigest("SHA256", @license_key, message)
 
       payload = {
+        key_hash:  key_hash,
         user_id:   user_id.to_s,
         device_id: @device_id,
         timestamp: ts,
@@ -252,13 +267,9 @@ module Clacky
 
       return { success: false, error: "Missing slug" } if slug.empty?
 
-      # When download_url is nil (e.g. mock/test mode), skip the download and
-      # just record the installed version so the UI reflects a successful install.
       if url.nil?
-        dest_dir = File.join(brand_skills_dir, slug)
-        FileUtils.mkdir_p(dest_dir)
-        record_installed_skill(slug, version, skill_info["name"])
-        return { success: true, slug: slug, version: version }
+        FileUtils.mkdir_p(File.join(brand_skills_dir, slug))
+        return { success: false, error: "No download URL" }
       end
 
       require "zip"
@@ -270,17 +281,28 @@ module Clacky
       tmp_zip = File.join(brand_skills_dir, "#{slug}.zip")
       download_file(url, tmp_zip)
 
-      # Extract into dest_dir (overwrite existing files)
+      # Extract into dest_dir (overwrite existing files).
+      # Auto-detect whether the zip has a single root folder to strip.
+      # Uses get_input_stream instead of entry.extract to avoid rubyzip 3.x
+      # path-safety restrictions on absolute destination paths.
       Zip::File.open(tmp_zip) do |zip|
-        zip.each do |entry|
-          # Strip leading component (the archive root folder) if present
-          parts    = entry.name.split("/")
-          rel_path = parts.length > 1 ? parts[1..].join("/") : parts[0]
-          next if rel_path.empty?
+        entries  = zip.entries.reject(&:directory?)
+        top_dirs = entries.map { |e| e.name.split("/").first }.uniq
+        has_root = top_dirs.length == 1 && entries.any? { |e| e.name.include?("/") }
+
+        entries.each do |entry|
+          rel_path = if has_root
+                       parts = entry.name.split("/")
+                       parts[1..].join("/")
+                     else
+                       entry.name
+                     end
+
+          next if rel_path.nil? || rel_path.empty?
 
           out = File.join(dest_dir, rel_path)
           FileUtils.mkdir_p(File.dirname(out))
-          entry.extract(out) { true }  # overwrite
+          File.open(out, "wb") { |f| f.write(entry.get_input_stream.read) }
         end
       end
 
@@ -290,7 +312,7 @@ module Clacky
       record_installed_skill(slug, version, skill_info["name"])
 
       { success: true, slug: slug, version: version }
-    rescue StandardError => e
+    rescue StandardError, ScriptError => e
       { success: false, error: e.message }
     end
 
@@ -437,13 +459,46 @@ module Clacky
       raise "Brand skill encrypted file not found: #{encrypted_path}"
     end
 
-    # Read the local brand_skills.json metadata.
+    # Read the local brand_skills.json metadata, cross-validated against the
+    # actual file system.  A skill is only considered installed when:
+    #   1. It has an entry in brand_skills.json, AND
+    #   2. Its skill directory exists under brand_skills_dir, AND
+    #   3. That directory contains at least one file (SKILL.md or SKILL.md.enc).
+    #
+    # If the JSON record exists but the directory is missing or empty the entry
+    # is silently dropped from the result and the JSON file is cleaned up so
+    # subsequent installs start from a clean state.
+    #
     # Returns a hash keyed by slug: { "version" => "1.0.0", "name" => "..." }
     def installed_brand_skills
       path = File.join(brand_skills_dir, "brand_skills.json")
       return {} unless File.exist?(path)
 
-      JSON.parse(File.read(path))
+      raw = JSON.parse(File.read(path))
+
+      # Validate each entry against the actual file system.
+      valid   = {}
+      changed = false
+
+      raw.each do |slug, meta|
+        skill_dir = File.join(brand_skills_dir, slug)
+        has_files = Dir.exist?(skill_dir) &&
+                    Dir.glob(File.join(skill_dir, "SKILL.md{,.enc}")).any?
+
+        if has_files
+          valid[slug] = meta
+        else
+          # JSON record exists but files are missing — mark for cleanup.
+          changed = true
+        end
+      end
+
+      # Persist the cleaned-up JSON so stale records don't accumulate.
+      if changed
+        File.write(path, JSON.generate(valid))
+      end
+
+      valid
     rescue StandardError
       {}
     end
@@ -453,6 +508,10 @@ module Clacky
       {
         brand_name:         @brand_name,
         brand_command:      @brand_command,
+        distribution_name:  @distribution_name,
+        product_name:       @product_name,
+        logo_url:           @logo_url,
+        support_contact:    @support_contact,
         branded:            branded?,
         activated:          activated?,
         expired:            expired?,
@@ -466,6 +525,10 @@ module Clacky
       data = {}
       data["brand_name"]             = @brand_name             if @brand_name
       data["brand_command"]          = @brand_command          if @brand_command
+      data["distribution_name"]      = @distribution_name      if @distribution_name
+      data["product_name"]           = @product_name           if @product_name
+      data["logo_url"]               = @logo_url               if @logo_url
+      data["support_contact"]        = @support_contact        if @support_contact
       data["license_key"]            = @license_key            if @license_key
       data["license_activated_at"]   = @license_activated_at.iso8601   if @license_activated_at
       data["license_expires_at"]     = @license_expires_at.iso8601     if @license_expires_at
@@ -474,20 +537,44 @@ module Clacky
       YAML.dump(data)
     end
 
+    # Apply distribution fields from API response.
+    # Updates name, product_name, logo_url, support_contact from the distribution hash.
+    private def apply_distribution(dist)
+      return unless dist.is_a?(Hash)
+
+      @distribution_name = dist["name"]           if dist["name"].to_s.strip != ""
+      @product_name      = dist["product_name"]    if dist["product_name"].to_s.strip != ""
+      @logo_url          = dist["logo_url"]         if dist["logo_url"].to_s.strip != ""
+      @support_contact   = dist["support_contact"]  if dist["support_contact"].to_s.strip != ""
+    end
+
     # Download a remote URL to a local file path.
-    private def download_file(url, dest)
+    private def download_file(url, dest, max_redirects: 10)
       require "net/http"
       require "uri"
 
       uri = URI.parse(url)
-      Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https",
-                      open_timeout: 15, read_timeout: 60) do |http|
-        http.request_get(uri.request_uri) do |resp|
-          raise "HTTP #{resp.code}" unless resp.code.to_i == 200
-
-          File.open(dest, "wb") { |f| resp.read_body { |chunk| f.write(chunk) } }
+      max_redirects.times do
+        Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https",
+                        open_timeout: 15, read_timeout: 60) do |http|
+          http.request_get(uri.request_uri) do |resp|
+            case resp.code.to_i
+            when 200
+              File.open(dest, "wb") { |f| resp.read_body { |chunk| f.write(chunk) } }
+              return
+            when 301, 302, 303, 307, 308
+              location = resp["location"]
+              raise "Redirect with no Location header" if location.nil? || location.empty?
+
+              uri = URI.parse(location)
+              break  # break out of Net::HTTP.start, re-enter loop with new uri
+            else
+              raise "HTTP #{resp.code}"
+            end
+          end
         end
       end
+      raise "Too many redirects"
     end
 
     # Persist installed skill metadata to brand_skills.json.

data/lib/clacky/cli.rb

@@ -647,7 +647,7 @@ module Clacky
             # Clear output area
             ui_controller.layout.clear_output
             # Clear session by creating a new agent
-            agent = Clacky::Agent.new(client, agent_config, working_dir: working_dir, ui: ui_controller)
+            agent = Clacky::Agent.new(client, agent_config, working_dir: working_dir, ui: ui_controller, profile: agent.agent_profile.name)
             ui_controller.show_info("Session cleared. Starting fresh.")
             # Update session bar with reset values
             ui_controller.update_sessionbar(tasks: agent.total_tasks, cost: agent.total_cost)

data/lib/clacky/default_skills/onboard/SKILL.md

@@ -20,7 +20,7 @@ Send a short, warm welcome message (2–3 sentences). Detect the user's language
 text they've already typed; default to English. Do NOT ask any questions yet.
 
 Example (English):
-> Hi! I'm Clacky, your AI coding assistant ⚡
+> Hi! I'm your personal assistant ⚡
 > Let's take 30 seconds to personalize your experience — I'll ask just a couple of quick things.
 
 ### 2. Collect AI personality (card)
@@ -97,7 +97,7 @@ Template:
 # [AI Name] — Soul
 
 ## Identity
-I am [AI Name], an AI coding assistant and technical co-founder.
+I am [AI Name], a personal assistant and technical co-founder.
 [1–2 sentences reflecting the chosen personality.]
 
 ## Personality & Tone

data/lib/clacky/server/http_server.rb

@@ -105,7 +105,7 @@ module Clacky
           session_registry: @registry,
           session_builder:  method(:build_session)
         )
-        @skill_loader    = Clacky::SkillLoader.new(nil, brand_config: Clacky::BrandConfig.load)
+        @skill_loader    = Clacky::SkillLoader.new(working_dir: nil, brand_config: Clacky::BrandConfig.load)
       end
 
       def start
@@ -163,6 +163,7 @@ module Clacky
         end
 
         puts "🌐 Clacky Web UI running at http://#{@host}:#{@port}"
+        puts "   Version: #{Clacky::VERSION}"
         puts "   Press Ctrl-C to stop."
 
         # Auto-create a default session on startup
@@ -385,7 +386,7 @@ module Clacky
         if result[:success]
           # Refresh skill_loader with the now-activated brand config so brand
           # skills are loadable from this point forward (e.g. after sync).
-          @skill_loader = Clacky::SkillLoader.new(nil, brand_config: brand)
+          @skill_loader = Clacky::SkillLoader.new(working_dir: nil, brand_config: brand)
           json_response(res, 200, { ok: true, brand_name: result[:brand_name] || brand.brand_name })
         else
           json_response(res, 422, { ok: false, error: result[:message] })
@@ -459,6 +460,8 @@ module Clacky
         else
           json_response(res, 422, { ok: false, error: result[:error] })
         end
+      rescue StandardError, ScriptError => e
+        json_response(res, 500, { ok: false, error: e.message })
       end
 
       # GET /api/brand

data/lib/clacky/skill_loader.rb

@@ -27,7 +27,7 @@ module Clacky
     # @param working_dir [String] Current working directory for project-level discovery
     # @param brand_config [Clacky::BrandConfig, nil] Optional brand config used to
     #   decrypt brand skills. When nil, brand skills are silently skipped.
-    def initialize(working_dir = nil, brand_config: nil)
+    def initialize(working_dir:, brand_config:)
       @working_dir  = working_dir || Dir.pwd
       @brand_config = brand_config
       @skills = {}            # Map identifier -> Skill
@@ -45,7 +45,7 @@ module Clacky
     def load_all
       # Clear existing skills to ensure idempotent reloading
       clear
-      
+
       load_default_skills
       load_global_claude_skills
       load_global_clacky_skills
@@ -56,9 +56,9 @@ module Clacky
       all_skills
     end
 
-    # Load encrypted brand skills from ~/.clacky/brand_skills/
-    # Each skill directory must contain a SKILL.md.enc file.
-    # Requires a BrandConfig with an activated license to decrypt.
+    # Load brand skills from ~/.clacky/brand_skills/
+    # Supports both encrypted (SKILL.md.enc) and plain (SKILL.md) brand skills.
+    # Encrypted skills require a BrandConfig with an activated license to decrypt.
     # @return [Array<Skill>]
     def load_brand_skills
       return [] unless @brand_config&.activated?
@@ -70,11 +70,13 @@ module Clacky
 
       skills = []
       brand_skills_dir.children.select(&:directory?).each do |skill_dir|
-        # Only load directories that contain an encrypted skill file
-        next unless skill_dir.join("SKILL.md.enc").exist?
+        # Support both encrypted (.enc) and plain brand skills
+        encrypted = skill_dir.join("SKILL.md.enc").exist?
+        plain     = skill_dir.join("SKILL.md").exist?
+        next unless encrypted || plain
 
         skill_name = skill_dir.basename.to_s
-        skill = load_single_brand_skill(skill_dir, skill_name)
+        skill = load_single_brand_skill(skill_dir, skill_name, encrypted: encrypted)
         skills << skill if skill
       end
       skills
@@ -312,16 +314,18 @@ module Clacky
       skills
     end
 
-    # Load a single encrypted brand skill directory.
-    # @param skill_dir [Pathname] Directory containing SKILL.md.enc
+    # Load a single brand skill directory.
+    # Supports encrypted (SKILL.md.enc) and plain (SKILL.md) brand skills.
+    # @param skill_dir [Pathname] Directory containing the skill file
     # @param skill_name [String] Directory basename used as fallback identifier
+    # @param encrypted [Boolean] Whether to treat this as an encrypted brand skill
     # @return [Skill, nil]
-    private def load_single_brand_skill(skill_dir, skill_name)
+    private def load_single_brand_skill(skill_dir, skill_name, encrypted: true)
       skill = Skill.new(
         skill_dir,
         source_path:  skill_dir,
-        brand_skill:  true,
-        brand_config: @brand_config
+        brand_skill:  encrypted,
+        brand_config: encrypted ? @brand_config : nil
       )
 
       existing = @skills[skill.identifier]
@@ -416,22 +420,22 @@ module Clacky
       # Get the gem's lib directory
       gem_lib_dir = File.expand_path("../", __dir__)
       default_skills_dir = File.join(gem_lib_dir, "clacky", "default_skills")
-      
+
       return unless Dir.exist?(default_skills_dir)
-      
+
       # Load each skill directory
       Dir.glob(File.join(default_skills_dir, "*/SKILL.md")).each do |skill_file|
         skill_dir = File.dirname(skill_file)
         skill_name = File.basename(skill_dir)
-        
+
         begin
           skill = Skill.new(Pathname.new(skill_dir))
-          
+
           # Check for duplicates (higher priority skills override)
           if @skills.key?(skill.identifier)
             next  # Skip if already loaded from higher priority location
           end
-          
+
           # Register skill
           @skills[skill.identifier] = skill
           @skills_by_command[skill.slash_command] = skill

data/lib/clacky/ui2/layout_manager.rb

@@ -233,6 +233,11 @@ module Clacky
       def append_output(content)
         return if content.nil?
 
+        # Scrub any invalid byte sequences before they reach the render pipeline.
+        # wrap_long_line calls each_char which raises ArgumentError on invalid UTF-8.
+        content = content.encode('UTF-8', 'UTF-8', invalid: :replace, undef: :replace, replace: '') \
+          unless content.valid_encoding?
+
         @render_mutex.synchronize do
           lines = content.split("\n", -1)  # -1 to keep trailing empty strings
 

data/lib/clacky/ui2/screen_buffer.rb

@@ -15,6 +15,10 @@ module Clacky
         @buffer = []
         @last_input_time = nil
         @rapid_input_threshold = 0.01 # 10ms threshold for detecting paste-like rapid input
+
+        # Keep stdin in UTF-8 mode so getc returns complete multi-byte characters (e.g. CJK).
+        # Switching to BINARY would cause getc to return one byte at a time, breaking Chinese input.
+        $stdin.set_encoding('UTF-8')
       end
 
       # Move cursor to specific position (0-indexed)
@@ -138,8 +142,6 @@ module Clacky
       # @param timeout [Float] Timeout in seconds
       # @return [Symbol, String, Hash, nil] Key symbol, character, or { type: :rapid_input, text: String }
       def read_key(timeout: nil)
-        $stdin.set_encoding('UTF-8')
-
         current_time = Time.now.to_f
         is_rapid_input = @last_input_time && (current_time - @last_input_time) < @rapid_input_threshold
         @last_input_time = current_time
@@ -147,8 +149,9 @@ module Clacky
         char = read_char(timeout: timeout)
         return nil unless char
 
-        # Ensure character is UTF-8 encoded
-        char = char.force_encoding('UTF-8') if char.is_a?(String) && char.encoding != Encoding::UTF_8
+        # Convert raw BINARY bytes to valid UTF-8. Invalid/undefined bytes are dropped
+        # rather than raising ArgumentError (which would crash the input loop).
+        char = safe_to_utf8(char) if char.is_a?(String)
 
         # Handle escape sequences for special keys
         if char == "\e"
@@ -179,7 +182,6 @@ module Clacky
         # If this is rapid input or there are more characters available
         if is_rapid_input || has_more_input
           buffer = char.to_s.dup
-          buffer.force_encoding('UTF-8')
 
           # Keep reading available characters
           loop_count = 0
@@ -190,10 +192,10 @@ module Clacky
             has_data = IO.select([$stdin], nil, nil, 0)
 
             if has_data
-              next_char = $stdin.getc
+              next_char = $stdin.getc rescue nil
               break unless next_char
 
-              next_char = next_char.force_encoding('UTF-8') if next_char.encoding != Encoding::UTF_8
+              next_char = safe_to_utf8(next_char)
               buffer << next_char
               loop_count += 1
               empty_checks = 0  # Reset empty check counter
@@ -213,6 +215,8 @@ module Clacky
 
           # If we buffered multiple characters or newlines, treat as rapid input (paste)
           if buffer.length > 1 || buffer.include?("\n") || buffer.include?("\r")
+            # Ensure the accumulated buffer is valid UTF-8 before regex operations
+            buffer = safe_to_utf8(buffer)
             # Remove any trailing \r or \n from rapid input buffer
             cleaned_buffer = buffer.gsub(/[\r\n]+\z/, '')
             return { type: :rapid_input, text: cleaned_buffer } if cleaned_buffer.length > 0
@@ -251,6 +255,19 @@ module Clacky
       end
 
       private
+
+      # Ensure a string is valid UTF-8.
+      # stdin stays in UTF-8 mode so getc returns complete characters (including CJK).
+      # This method handles the rare case where an invalid byte slips through
+      # (e.g. a stray terminal escape or a partial sequence) by scrubbing it out
+      # rather than letting ArgumentError crash the input loop.
+      # @param str [String] String from getc (UTF-8 encoded, but may have invalid bytes)
+      # @return [String] Valid UTF-8 string
+      private def safe_to_utf8(str)
+        return str if str.valid_encoding?
+
+        str.encode('UTF-8', 'UTF-8', invalid: :replace, undef: :replace, replace: '')
+      end
     end
   end
 end