openclacky 1.5.1 → 1.5.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b195de6fb8b38aed47ef40aa59fa0e33aa3b993f52cc584d5c12bd27bd15b55c
-  data.tar.gz: 25b4a406f7f4985e4bdad2cd63c28c2af8875bed7ddf59baae33a94d9ebbe46b
+  metadata.gz: bb5f68cdd24e5d619fa22b79c643953e6c00f54400d7e89d95a9c99373328a55
+  data.tar.gz: 5bc17c114482d78e13d59d5f6b194caffbf9456015bce6082d3bbc63bdf951a2
 SHA512:
-  metadata.gz: 15a21c8d7aa23bbccc4a8255cb2caa14a937ff92ec90cbf20fac58a71675acfdd1f64be47723151841f860ed069add58e43abdccb48b31233cde8351ab9fad23
-  data.tar.gz: 3fbaadab5fcf374369ece22818f2739839ebf974d91a0ecf1dba9aa9e0530e27a801e4366ab2f6403c222501601e4e76f736d73d81eb667ee275e150364d21a1
+  metadata.gz: 55044dd2a193d5ed5e0b64aefee284fec18cb036369482d55936e7c3c01d8740aecee16e0ca75f1e5d1cc643a4d70d66005f1f5eb61d3bfc02a6152ef3b4155d
+  data.tar.gz: 86de30d32d826921245ea60abd5229665eb82445b68f68e6a68f90b519d4b0dd900b077a738c82b65a1d78a3bc974b3d938986445e9149f074b94095ead044c9

data/CHANGELOG.md

@@ -4,6 +4,30 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 
+## [1.5.2] - 2026-07-27
+
+### Added
+- Starter prompts for ext-developer agent on new session page
+- Secondary gateway endpoint for OpenClacky provider with auto-fallback after all retries exhausted
+- Subagent save support and invoke_skill format improvements
+
+### Improved
+- Curly quotes wrapping for starter prompt text
+- Brand license badge now distinguishes unreachable vs expiring states
+
+### Fixed
+- HTTP 429 quota_exceeded now shows correct "quota exceeded" error instead of "rate limit" and stops retrying
+- Search query filter now applies correctly to brand extensions in marketplace
+- Billing page colors unified to warm palette
+- Sub-model switching and card display now use saved provider_id correctly
+- Device revoked error message now includes 15-minute wait hint
+- Extension detail page routes by source param for brand/public distinction
+- Non-slug skill names preserved as name_zh fallback for Chinese matching
+- Sudo and .env writes unblocked in subagent; double-compression skipped
+- Claude tool call ID handling fixed
+- Brand skill preserved when auto-update download fails (C-5754)
+- Extension packing rejected when folder name diverges from ext.yml id (C-5752)
+
 ## [1.5.1] - 2026-07-24
 
 ### Fixed

data/lib/clacky/agent/llm_caller.rb

@@ -201,6 +201,20 @@ module Clacky
             sleep retry_delay
             retry
           else
+            # All retries exhausted for a timeout. Try the secondary gateway URL if available.
+            if !@config.url_fallback_active?
+              fallback_url = @config.fallback_base_url_for_current_provider
+              if fallback_url
+                @config.activate_url_fallback!(fallback_url)
+                rebuild_client_for_current_model!
+                retries = 0
+                @ui&.show_warning(
+                  I18n.t("llm.warn.switching_to_fallback_url", url: fallback_url)
+                )
+                retry
+              end
+            end
+
             raise AgentError.new("[LLM] #{I18n.t("llm.error.request_timeout", retries: max_retries)}", raw_message: e.message)
           end
 
@@ -234,6 +248,21 @@ module Clacky
             sleep retry_delay
             retry
           else
+            # All retries on the primary endpoint exhausted for a network-level
+            # failure (DNS/TCP/TLS). Try the secondary gateway URL if available.
+            if !@config.url_fallback_active?
+              fallback_url = @config.fallback_base_url_for_current_provider
+              if fallback_url
+                @config.activate_url_fallback!(fallback_url)
+                rebuild_client_for_current_model!
+                retries = 0
+                @ui&.show_warning(
+                  I18n.t("llm.warn.switching_to_fallback_url", url: fallback_url)
+                )
+                retry
+              end
+            end
+
             # Don't show_error here — let the outer rescue block handle it to avoid duplicates.
             # Progress cleanup is the caller's responsibility (via its own ensure block).
             raise AgentError.new("[LLM] #{I18n.t("llm.error.network_failed", retries: max_retries)}", raw_message: e.message)
@@ -272,6 +301,25 @@ module Clacky
           sleep retry_delay
           retry
         else
+          # All retries on the current endpoint exhausted.
+          # If a secondary gateway URL is configured and not yet tried, switch
+          # to it now, rebuild the client, and reset the retry counter so the
+          # same request gets a fresh MAX_RETRIES_ON_FALLBACK budget on the
+          # new endpoint.  This is a one-shot switch — url_fallback_active?
+          # prevents a second switch if the fallback URL also fails.
+          if !@config.url_fallback_active?
+            fallback_url = @config.fallback_base_url_for_current_provider
+            if fallback_url
+              @config.activate_url_fallback!(fallback_url)
+              rebuild_client_for_current_model!
+              retries = 0
+              @ui&.show_warning(
+                I18n.t("llm.warn.switching_to_fallback_url", url: fallback_url)
+              )
+              retry
+            end
+          end
+
           # Don't show_error here — let the outer rescue block handle it to avoid duplicates.
           # Progress cleanup is the caller's responsibility (via its own ensure block).
           raise AgentError.new("[LLM] #{I18n.t("llm.error.service_unavailable", retries: current_max)}", raw_message: e.message)

data/lib/clacky/agent/message_compressor_helper.rb

@@ -122,6 +122,13 @@ module Clacky
       #   handle_compression_response, so recent task progress is preserved.
       # @return [Hash, nil] Compression context or nil if not needed
       def compress_messages_if_needed(force: false, pull_back_from_tail: 0)
+        # Subagents must not proactively compress — their history is a clone of the
+        # parent's and will be discarded when the subagent exits. The parent will
+        # compress its own history after the subagent returns, so doing it here is
+        # pure waste (same data compressed twice). Context-overflow recovery
+        # (force: true) is still allowed as a safety net for long-running subagents.
+        return nil if @is_subagent && !force
+
         # Check if compression is enabled
         return nil unless @config.enable_compression
 

data/lib/clacky/agent/session_serializer.rb

@@ -641,13 +641,55 @@ module Clacky
 
             ui.show_tool_result(blk[:content].to_s)
           end
+          replay_subagent_transcript(msg, ui)
 
         when "tool"
           # OpenAI-format tool result
           ui.show_tool_result(msg[:content].to_s)
+          replay_subagent_transcript(msg, ui)
         end
       end
 
+      # Replay a subagent transcript stored on a tool result message. Emits a
+      # bracketed sequence of UI events the frontend can render as a collapsible
+      # sub-process block: subagent_start → (assistant_message / tool_call /
+      # tool_result)* → subagent_end. No-op when the message carries no transcript.
+      def replay_subagent_transcript(msg, ui)
+        transcript = msg[:subagent_transcript]
+        return unless transcript.is_a?(Hash)
+
+        events = transcript[:events] || transcript["events"] || []
+        return if events.empty?
+
+        ui.show_subagent_start(
+          skill:      transcript[:skill]      || transcript["skill"],
+          iterations: transcript[:iterations] || transcript["iterations"],
+          cost_usd:   transcript[:cost_usd]   || transcript["cost_usd"]
+        )
+
+        events.each do |ev|
+          role = (ev[:role] || ev["role"]).to_s
+          content = ev[:content] || ev["content"]
+          tool_calls = ev[:tool_calls] || ev["tool_calls"]
+
+          case role
+          when "assistant"
+            text = extract_text_from_content(content).to_s.strip
+            ui.show_assistant_message(text, files: []) unless text.empty?
+            Array(tool_calls).each do |tc|
+              name = tc[:name] || tc["name"] || ""
+              args_raw = tc[:arguments] || tc["arguments"] || {}
+              args = args_raw.is_a?(String) ? (JSON.parse(args_raw) rescue args_raw) : args_raw
+              ui.show_tool_call(name, args)
+            end
+          when "tool", "user"
+            ui.show_tool_result(extract_text_from_content(content).to_s)
+          end
+        end
+
+        ui.show_subagent_end
+      end
+
       # Replace the system message in @messages with a freshly built system prompt.
       # Called after restore_session so newly installed skills and any other
       # configuration changes since the session was saved take effect immediately.

data/lib/clacky/agent/skill_manager.rb

@@ -639,6 +639,13 @@ module Clacky
         # Generate summary
         summary = generate_subagent_summary(subagent)
 
+        # Capture the subagent's own message trail (everything it appended after
+        # the fork) so the parent session can persist and later replay the full
+        # subagent process — not just the collapsed summary. Stored transiently
+        # on the parent agent; observe() attaches it to the invoke_skill tool
+        # result message. Kept out of the LLM payload via INTERNAL_FIELDS.
+        @pending_subagent_transcript = extract_subagent_transcript(subagent, skill.identifier)
+
         # Mutate the subagent_instructions message in-place to become the result summary
         @history.mutate_last_matching(->(m) { m[:subagent_instructions] }) do |m|
           m[:content] = summary

data/lib/clacky/agent.rb

@@ -105,6 +105,7 @@ module Clacky
       @ui = ui  # UIController for direct UI interaction
       @debug_logs = []  # Debug logs for troubleshooting
       @pending_injections = []     # Pending inline skill injections to flush after observe()
+      @pending_subagent_transcript = nil # Subagent trail to attach to the next tool result (observe)
       @pending_script_tmpdirs = [] # Decrypted-script tmpdirs that live for the agent's lifetime
       @pending_error_rollback = false  # Deferred rollback flag set by restore_session on error
       @last_run_interrupted = false    # Set when run() exits via AgentInterrupted; tells the next run() to keep the task-start snapshot (continuation of the same task across a relay, not a brand-new task)
@@ -212,7 +213,7 @@ module Clacky
     private def rebuild_client_for_current_model!
       @client = Clacky::Client.new(
         @config.api_key,
-        base_url: @config.base_url,
+        base_url: @config.effective_base_url,
         model: @config.model_name,
         anthropic_format: @config.anthropic_format?
       )
@@ -249,6 +250,7 @@ module Clacky
         id: model["id"],
         model: model["model"],
         base_url: model["base_url"],
+        provider_id: model["provider_id"],
         card_model: base_entry&.dig("model"),
         sub_model: sub_model
       }
@@ -1138,6 +1140,8 @@ module Clacky
         @history.append(truncated.merge(task_id: @current_task_id))
       end
 
+      attach_pending_subagent_transcript(response)
+
       # Append a follow-up `role:"user"` message for any image payloads that
       # could not be delivered inside the tool message.
       #
@@ -1181,6 +1185,24 @@ module Clacky
       end
     end
 
+    # Attach the captured subagent transcript (set by execute_skill_with_subagent)
+    # to the invoke_skill tool result message just appended by observe(). The
+    # transcript rides on the tool message as :subagent_transcript — an internal
+    # field stripped before the LLM call but persisted to session.json and
+    # replayed to the WebUI. Cleared after attaching so it fires exactly once.
+    private def attach_pending_subagent_transcript(response)
+      transcript = @pending_subagent_transcript
+      return unless transcript
+
+      @pending_subagent_transcript = nil
+
+      skill_call = Array(response[:tool_calls]).find { |tc| (tc[:name] || tc.dig(:function, :name)) == "invoke_skill" }
+      target_id = skill_call && skill_call[:id]
+      return unless target_id
+
+      @history.attach_to_tool_result(target_id, :subagent_transcript, transcript)
+    end
+
     # Cap oversized tool result content to keep a single tool message from
     # blowing up the prompt budget (issue #218: a 7350-path glob produced a
     # ~890k-char result that pushed history past the model context window
@@ -1541,6 +1563,41 @@ module Clacky
       parts.join("\n")
     end
 
+    # Extract the subagent's own message trail for persistence/replay.
+    # Returns a trimmed, LLM-free array of {role, content, tool_calls} hashes
+    # capturing only what the subagent did after the fork — system-injected
+    # scaffolding (fork instructions, ack) is dropped. Stored on the parent's
+    # invoke_skill tool result under :subagent_transcript so the WebUI can
+    # render a collapsible sub-process without polluting the main thread.
+    def extract_subagent_transcript(subagent, skill_identifier)
+      parent_count = subagent.instance_variable_get(:@parent_message_count) || 0
+      new_messages = subagent.history.to_a[parent_count..] || []
+
+      events = new_messages.filter_map do |m|
+        next if m[:system_injected]
+        role = m[:role].to_s
+        next unless %w[assistant tool user].include?(role)
+
+        entry = { role: role }
+        entry[:content] = m[:content] if m[:content] && !m[:content].to_s.empty?
+        if m[:tool_calls].is_a?(Array) && !m[:tool_calls].empty?
+          entry[:tool_calls] = m[:tool_calls].map do |tc|
+            func = tc[:function] || tc
+            { name: func[:name] || tc[:name], arguments: func[:arguments] || tc[:arguments] || {} }
+          end
+        end
+        entry[:tool_call_id] = m[:tool_call_id] if m[:tool_call_id]
+        entry.key?(:content) || entry.key?(:tool_calls) ? entry : nil
+      end
+
+      {
+        skill: skill_identifier,
+        iterations: subagent.iterations,
+        cost_usd: subagent.total_cost.round(4),
+        events: events
+      }
+    end
+
     # Deep clone helper for messages using Marshal
     # @param obj [Object] Object to clone
     # @return [Object] Deep cloned object

data/lib/clacky/agent_config.rb

@@ -1053,6 +1053,48 @@ module Clacky
       end
     end
 
+    # ── URL-level fallback ─────────────────────────────────────────────────
+    # Independent from the model-name fallback above.  When all max_retries
+    # on the primary endpoint are exhausted, the caller may switch to a
+    # secondary gateway URL (same model, different host) via these methods.
+    # The URL fallback is intentionally one-shot per session — we do not
+    # probe or reset it automatically, keeping the logic simple.
+
+    # Look up the fallback base URL for the current model's provider.
+    # Returns nil if the provider has no secondary gateway configured.
+    # @return [String, nil]
+    def fallback_base_url_for_current_provider
+      m = current_model
+      return nil unless m
+
+      provider_id = Clacky::Providers.resolve_provider(
+        base_url: m["base_url"],
+        api_key:  m["api_key"]
+      )
+      return nil unless provider_id
+
+      Clacky::Providers.fallback_base_url(provider_id)
+    end
+
+    # Activate the URL fallback: override base_url with the secondary gateway.
+    # Idempotent — safe to call multiple times.
+    # @param fallback_url [String] the secondary gateway URL
+    def activate_url_fallback!(fallback_url)
+      @url_fallback_active = true
+      @url_fallback_base_url = fallback_url
+    end
+
+    # Returns true when the secondary gateway URL is in use.
+    def url_fallback_active?
+      @url_fallback_active == true
+    end
+
+    # The effective base URL for API calls.
+    # Returns the URL-fallback override when active, otherwise the model's configured base_url.
+    def effective_base_url
+      @url_fallback_active ? @url_fallback_base_url : base_url
+    end
+
     # Get current model configuration.
     #
     # Resolution order:

data/lib/clacky/brand_config.rb

@@ -40,6 +40,16 @@ module Clacky
     # Grace period for offline heartbeat failures (3 days)
     HEARTBEAT_GRACE_PERIOD = 3 * 86_400
 
+    # Per-slug locks serializing concurrent brand-skill installs. Each Agent
+    # spawns its own background sync thread, so several may try to install the
+    # same skill at once; a shared per-slug mutex collapses that to one download.
+    @install_locks       = {}
+    @install_locks_guard = Mutex.new
+
+    def self.install_lock_for(slug)
+      @install_locks_guard.synchronize { @install_locks[slug] ||= Mutex.new }
+    end
+
     attr_reader :product_name, :package_name, :license_key, :license_activated_at,
                 :license_expires_at, :license_last_heartbeat, :device_id,
                 :logo_url, :support_contact, :license_user_id,
@@ -1106,72 +1116,91 @@ module Clacky
 
       require "zip"
 
-      dest_dir = File.join(brand_skills_dir, slug)
-      FileUtils.mkdir_p(dest_dir)
+      # Serialize installs of the same slug so concurrent background syncs (one
+      # per Agent) don't redundantly download the same ZIP or race on the same
+      # destination directory.
+      install_lock = self.class.install_lock_for(slug)
+      install_lock.synchronize do
+        dest_dir = File.join(brand_skills_dir, slug)
+
+        # Download and extract into a unique staging directory, never touching
+        # dest_dir until everything succeeds. A failed or corrupt download must
+        # never destroy the already-installed version.
+        stage_id   = "#{Process.pid}.#{SecureRandom.hex(4)}"
+        stage_dir  = File.join(brand_skills_dir, ".staging-#{slug}-#{stage_id}")
+        tmp_zip    = File.join(brand_skills_dir, ".#{slug}-#{stage_id}.zip")
+        FileUtils.mkdir_p(stage_dir)
+
+        begin
+          # Download the zip file to a temp path via PlatformHttpClient so the
+          # primary → fallback host failover applies uniformly to every download.
+          dl = platform_client.download_file(url, tmp_zip)
+          raise dl[:error].to_s unless dl[:success]
+
+          zip_size = File.size?(tmp_zip).to_i
+          raise "Empty ZIP downloaded for #{slug}" if zip_size < 22  # min valid zip = empty central directory
+
+          # Extract into stage_dir.
+          # 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.
+          # Uses chunked read + size verification for robustness.
+          Zip::File.open(tmp_zip) do |zip|
+            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(stage_dir, rel_path)
+              FileUtils.mkdir_p(File.dirname(out))
+
+              # Chunked copy with size verification
+              written = 0
+              File.open(out, "wb") do |f|
+                entry.get_input_stream do |input|
+                  while (chunk = input.read(65536))
+                    f.write(chunk)
+                    written += chunk.bytesize
+                  end
+                end
+              end
 
-      # Download the zip file to a temp path via PlatformHttpClient so the
-      # primary → fallback host failover applies uniformly to every download.
-      tmp_zip = File.join(brand_skills_dir, "#{slug}.zip")
-      dl = platform_client.download_file(url, tmp_zip)
-      raise dl[:error].to_s unless dl[:success]
-
-      zip_size = File.size?(tmp_zip).to_i
-      raise "Empty ZIP downloaded for #{slug}" if zip_size < 22  # min valid zip = empty central directory
-
-      # 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.
-      # Uses chunked read + size verification for robustness.
-      Zip::File.open(tmp_zip) do |zip|
-        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))
-
-          # Chunked copy with size verification
-          written = 0
-          File.open(out, "wb") do |f|
-            entry.get_input_stream do |input|
-              while (chunk = input.read(65536))
-                f.write(chunk)
-                written += chunk.bytesize
+              # Verify file size matches ZIP entry declaration
+              if written != entry.size
+                raise "Size mismatch for #{entry.name}: expected #{entry.size}, got #{written}"
               end
             end
           end
 
-          # Verify file size matches ZIP entry declaration
-          if written != entry.size
-            raise "Size mismatch for #{entry.name}: expected #{entry.size}, got #{written}"
-          end
+          # Everything extracted successfully — atomically swap staging into
+          # place. Only now is the previous version removed.
+          FileUtils.rm_rf(dest_dir)
+          FileUtils.mv(stage_dir, dest_dir)
+
+          record_installed_skill(slug, version, skill_info["description"],
+                                 encrypted: encrypted,
+                                 description_zh: skill_info["description_zh"],
+                                 name_zh: skill_info["name_zh"])
+
+          { success: true, name: slug, version: version }
+        rescue StandardError, ScriptError => e
+          # Only clean up our own staging artifacts; the installed version in
+          # dest_dir is left untouched so a failed update never loses a skill.
+          { success: false, error: e.message }
+        ensure
+          FileUtils.rm_f(tmp_zip)
+          FileUtils.rm_rf(stage_dir) if Dir.exist?(stage_dir)
         end
       end
-
-      FileUtils.rm_f(tmp_zip)
-
-
-      record_installed_skill(slug, version, skill_info["description"],
-                             encrypted: encrypted,
-                             description_zh: skill_info["description_zh"],
-                             name_zh: skill_info["name_zh"])
-
-      { success: true, name: slug, version: version }
-    rescue StandardError, ScriptError => e
-      FileUtils.rm_f(tmp_zip) if defined?(tmp_zip) && tmp_zip
-      FileUtils.rm_rf(dest_dir) if defined?(dest_dir) && dest_dir
-      { success: false, error: e.message }
     end
 
     # Install a mock brand skill for brand-test mode.

data/lib/clacky/client.rb

@@ -616,7 +616,7 @@ module Clacky
       when 401       then I18n.t("llm.error.invalid_api_key")
       when 403       then I18n.t("llm.error.403.#{error_code || "default"}")
       when 404       then I18n.t("llm.error.endpoint_not_found")
-      when 429       then I18n.t("llm.error.rate_limit_429")
+      when 429       then error_code == "quota_exceeded" ? I18n.t("llm.error.quota_exhausted") : I18n.t("llm.error.rate_limit_429")
       when 500..599  then I18n.t("llm.error.server_error", status: response.status)
       else                extract_error_message(error_body, response.body)
       end
@@ -670,7 +670,11 @@ module Clacky
         raise AgentError.new("[LLM] #{translated}", raw_message: error_message)
       when 404
         raise AgentError.new("[LLM] #{I18n.t("llm.error.endpoint_not_found")}", raw_message: error_message)
-      when 429 then raise RetryableError, "[LLM] #{I18n.t("llm.error.rate_limit_429")}"
+      when 429
+        if error_code == "quota_exceeded"
+          raise AgentError.new("[LLM] #{I18n.t("llm.error.quota_exhausted")}", raw_message: error_message)
+        end
+        raise RetryableError, "[LLM] #{I18n.t("llm.error.rate_limit_429")}"
       when 500..599 then raise RetryableError, "[LLM] #{I18n.t("llm.error.server_error", status: response.status)}"
       else raise AgentError.new("[LLM] #{I18n.t("llm.error.unexpected", status: response.status)}", raw_message: error_message)
       end

data/lib/clacky/default_extensions/ext-studio/panels/studio/view.js

@@ -51,6 +51,7 @@
       "err.version_conflict": "Version {{ver}} has already been published. Please enter a higher version number above and try again.",
       "err.invalid_version": "Invalid version. Use format like 1.0.0.",
       "err.name_taken": "The name \"{{id}}\" is already taken by another user.",
+      "err.id_folder_mismatch": "Extension ID mismatch: the folder is named \"{{folder}}\" but ext.yml declares id \"{{id}}\". Rename the folder or the id so they match before publishing.",
       "rename.label": "Choose a new ID for your extension:",
       "rename.placeholder": "e.g. my-ext-yourname",
       "rename.hint": "Only lowercase letters, digits and hyphens. This will rename the local folder and update ext.yml.",
@@ -235,6 +236,7 @@
       "err.version_conflict": "版本 {{ver}} 已发布过，请在上方输入更高的版本号后重试。",
       "err.invalid_version": "版本号格式不对，请使用如 1.0.0 的格式。",
       "err.name_taken": "扩展名「{{id}}」已被其他用户占用。",
+      "err.id_folder_mismatch": "扩展 ID 不一致：文件夹名为「{{folder}}」，但 ext.yml 声明的 id 是「{{id}}」。请先把文件夹名或 id 改成一致再发布。",
       "rename.label": "请为你的扩展选择一个新 ID：",
       "rename.placeholder": "例如 my-ext-yourname",
       "rename.hint": "只能使用小写字母、数字和连字符。",
@@ -726,6 +728,7 @@
         } catch (e) {
           const msg = e.message || "";
           const isConflict = /must be greater than/i.test(msg);
+          const mismatch = msg.match(/folder is '([^']+)' but ext\.yml declares id '([^']+)'/);
           if (isConflict) {
             setProgress(t("err.version_conflict", { ver }), true);
             verInput.classList.add("studio-input-error");
@@ -733,6 +736,8 @@
             verInput.focus();
             verInput.select();
             verInput.addEventListener("input", () => verInput.classList.remove("studio-input-error"), { once: true });
+          } else if (mismatch) {
+            setProgress(t("err.id_folder_mismatch", { folder: mismatch[1], id: mismatch[2] }), true);
           } else {
             setProgress(t("err.generic", { msg }), true);
           }

data/lib/clacky/extension/packager.rb

@@ -3,6 +3,7 @@
 require "fileutils"
 require "tmpdir"
 require "open-uri"
+require "psych"
 require "zip"
 
 module Clacky
@@ -38,6 +39,7 @@ module Clacky
           raise Error, "no container found at #{container_dir} (expected #{MANIFEST})"
         end
 
+        refuse_id_folder_mismatch!(slug, container_dir)
         verify_container!(slug, container_dir)
         refuse_protected!(slug, container_dir)
 
@@ -96,6 +98,21 @@ module Clacky
         Clacky::ExtensionLoader.invalidate_cache!
       end
 
+      # The container's identity must be the same on both sides of the publish
+      # boundary: the client keys extensions by folder name, the marketplace
+      # keys them by ext.yml `id`. If they diverge, a rename on one side alone
+      # lets a container masquerade under a name the uniqueness check never saw.
+      private def refuse_id_folder_mismatch!(slug, container_dir)
+        manifest = File.join(container_dir, MANIFEST)
+        data     = Psych.safe_load(File.read(manifest), permitted_classes: [], aliases: true) || {}
+        declared = data["id"].to_s.strip
+        return if declared == slug
+
+        raise Error,
+              "extension id mismatch: folder is '#{slug}' but #{MANIFEST} declares id '#{declared}'. " \
+              "Rename the folder or the id so they match before packing."
+      end
+
       # Packing is for authored (open) containers. Anything already protected or
       # carrying encrypted skills is produced by the platform pipeline; refuse
       # to re-pack it so we never smuggle marketplace artifacts out of band.

data/lib/clacky/locales/en.rb

@@ -9,11 +9,12 @@ module Clacky
       "llm.error.403.model_not_allowed" => "This model is not available on your current plan",
       "llm.error.403.api_key_revoked"   => "API key has been revoked, please generate a new one",
       "llm.error.403.api_key_expired"   => "API key has expired, please generate a new one",
-      "llm.error.403.quota_exceeded"    => "Quota exceeded, please upgrade your plan",
+      "llm.error.403.quota_exceeded"    => "API key quota exceeded. Please update the quota or disable the limit in the admin console",
       "llm.error.403.access_denied"     => "Access denied, please check your API key permissions",
       "llm.error.403.default"           => "Access denied",
       "llm.error.endpoint_not_found"    => "API endpoint not found, please check your service URL",
       "llm.error.rate_limit_429"        => "Rate limit exceeded, please wait a moment",
+      "llm.error.quota_exhausted"       => "API quota exhausted (key usage limit reached). Please raise the quota or upgrade your plan in the console",
       "llm.error.server_error"          => "Service temporarily unavailable (%<status>d), retrying...",
       "llm.error.unexpected"            => "Unexpected error (%<status>d)",
       "llm.error.html_response"         => "Service temporarily unavailable (received HTML error page), retrying...",
@@ -21,6 +22,7 @@ module Clacky
       "llm.error.request_timeout"       => "Request timed out after %<retries>d retries",
       "llm.error.network_failed"        => "Network connection failed after %<retries>d retries",
       "llm.error.service_unavailable"   => "Service unavailable after %<retries>d retries",
+      "llm.warn.switching_to_fallback_url" => "Primary endpoint unreachable. Switching to fallback gateway: %<url>s",
       "platform.error.invalid_proof"        => "Invalid license key — please check and try again.",
       "platform.error.invalid_signature"    => "Invalid request signature.",
       "platform.error.nonce_replayed"       => "Duplicate request detected. Please try again.",
@@ -28,7 +30,7 @@ module Clacky
       "platform.error.license_revoked"      => "This license has been revoked. Please contact support.",
       "platform.error.license_expired"      => "This license has expired. Please renew to continue.",
       "platform.error.device_limit_reached" => "Device limit reached for this license.",
-      "platform.error.device_revoked"       => "This device has been revoked from the license.",
+      "platform.error.device_revoked"       => "This device has been revoked from the license. To re-activate, please wait 15 minutes and try again.",
       "platform.error.invalid_license"      => "License key not found. Please verify the key.",
       "platform.error.device_not_found"     => "Device not registered. Please re-activate.",
       "platform.error.contributor_required" => "Publishing extensions requires becoming a contributor. Sign in, open \"My Extensions\", and click \"Become a contributor\" (no review needed).",