openclacky 1.2.2 → 1.2.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cfaa1f45ce6ab05b0a101571f59e809d92430ee862196b21a714ceb56c3ec8b5
-  data.tar.gz: 6d76cd4d7bf8568fd8229dc9770f23fb027296c660ad0ba3d514be61df69c5ce
+  metadata.gz: 39490977253b82c6bf0e0e7c89e3763b86dbe56a46e8c6e716774c06387bc7a7
+  data.tar.gz: 25224b037f948e7252467337a4e04051340d4bd7ff75456d7a8653acfc43e94c
 SHA512:
-  metadata.gz: aa5e444bc28d570022df63172027028d99224191f6d2a0b26537cb5c1597c523b165b35efd58747312586aa01f133c522b5c9cae46b5f25d06501b1a083b6e31
-  data.tar.gz: ae1d58c07b9a24937b1c4182e19a093394565fdc972c5caf72cba66f3bf0419cbdd0874f7b2d741d7b00b8efdd8fe83a2efee767f7df1a3e8e6656b237631721
+  metadata.gz: 9ba3260b11c8b7f37c075ebc392567f3b049246932e65e1fc12df99363f86921af28c05e5fd4d46ddb1cd796092fc11315b80ef67937c13b5e6cbb9a276cdc47
+  data.tar.gz: 8de209627490544c48f3d07f8b010cc40fe6ef51e597734b61adb7c6285d65d3a309aebebe9f9f563a681db60596b797e5a79d9eaa46c85805b37b75cca9369c

data/CHANGELOG.md

@@ -5,6 +5,18 @@ 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/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.2.3] - 2026-05-27
+
+### Added
+- Qwen 3.7 model support
+- WSL network doctor PowerShell script
+- Limit on glob/grep file walker to prevent excessive traversal
+
+### Fixed
+- Terminal single-line mode issue
+- Terminal execution hang
+- apt try logic
+
 ## [1.2.2] - 2026-05-25
 
 ### More

data/lib/clacky/default_skills/browser-setup/SKILL.md

@@ -111,6 +111,96 @@ chrome-devtools-mcp --version 2>/dev/null
 
 If still missing after user confirms, stop with error message.
 
+### Step 2.5 — WSL networking setup (only when session context shows `OS: WSL/Windows`)
+
+**Skip this entire step on macOS / Linux.** Look at the session context line that begins with `[Session context: ...]` — only run this step if it includes `OS: WSL/Windows`.
+
+#### Background (read this so you know what to do)
+
+The browser tool runs inside WSL but Chrome/Edge runs on Windows. By default WSL2 uses NAT networking, which means `127.0.0.1` inside WSL **cannot** reach Windows' Chrome debug port. The fix is to enable WSL2 **mirrored networking** (`networkingMode=mirrored` in `%USERPROFILE%\.wslconfig`), which makes WSL share Windows' network stack so `127.0.0.1` works directly.
+
+We have a helper script that handles all the Windows-side details:
+
+```
+~/.clacky/scripts/wsl_network_doctor.ps1
+```
+
+It exposes three subcommands:
+
+| Subcommand | What it does | Exit code |
+|---|---|---|
+| `status` | Check whether mirrored is configured (auto-passes on WSL1) | `0` OK / `10` NEED_ENABLE |
+| `enable` | Write `networkingMode=mirrored` to `.wslconfig` (does NOT shut down WSL) | `0` success / `1` fail |
+| `repair` | Restart Windows Host Network Service (HNS) via UAC prompt | `0` launched / `1` fail |
+
+Invoke it from WSL like this:
+
+```bash
+powershell.exe -NoProfile -ExecutionPolicy Bypass -File "$(wslpath -w ~/.clacky/scripts/wsl_network_doctor.ps1)" <subcommand>
+```
+
+#### Step 2.5.1 — Check status
+
+```bash
+powershell.exe -NoProfile -ExecutionPolicy Bypass -File "$(wslpath -w ~/.clacky/scripts/wsl_network_doctor.ps1)" status
+```
+
+- Exit `0` (output starts with `OK:`) → either mirrored is configured (WSL2) or
+  Ubuntu is running on WSL1 (which shares the Windows network stack and needs no
+  config). Either way, proceed to Step 3.
+- Exit `10` (output starts with `NEED_ENABLE:`) → continue to Step 2.5.2.
+- Any other failure → show the output to the user and ask them to retry. Stop here.
+
+#### Step 2.5.2 — Enable mirrored (only when NEED_ENABLE)
+
+Tell the user what's about to happen (in their language):
+
+> WSL doesn't have mirrored networking enabled yet — the browser tool needs it to reach Chrome on Windows.
+> I'll add one line to `%USERPROFILE%\.wslconfig`. Your current WSL session will NOT be restarted.
+
+Run:
+
+```bash
+powershell.exe -NoProfile -ExecutionPolicy Bypass -File "$(wslpath -w ~/.clacky/scripts/wsl_network_doctor.ps1)" enable
+```
+
+If the script exits `0`:
+
+> ✅ `.wslconfig` updated. Tell the user (in their language):
+>
+> The config takes effect only after WSL restarts, but we can't restart WSL from inside WSL.
+> Please:
+>
+> 1. Open **PowerShell** on Windows
+> 2. Run: `wsl --shutdown`
+> 3. Reopen the Clacky terminal
+> 4. Run `/browser-setup` again
+>
+> Stop here. Wait for the user to come back in a new session.
+
+If the script exits non-zero, show the output to the user and stop. Do NOT proceed to Step 3 — without mirrored networking the browser tool will not work.
+
+#### Step 2.5.3 — When to run repair
+
+Do NOT run `repair` proactively. Only run it later if **all** of the following are true:
+
+- `status` returned `OK` (mirrored is configured)
+- The user has restarted WSL since the config was written
+- Step 3's `browser(action="status")` still fails with a "Chrome/Edge is not running or remote debugging is not enabled" error
+
+In that situation, tell the user (in their language):
+
+> The config looks correct but the browser still can't connect. Windows Host Network Service may be stuck — I'll restart it.
+> **A Windows User Account Control (UAC) prompt will appear shortly. Please click "Yes".**
+
+Then run:
+
+```bash
+powershell.exe -NoProfile -ExecutionPolicy Bypass -File "$(wslpath -w ~/.clacky/scripts/wsl_network_doctor.ps1)" repair
+```
+
+After it returns, tell the user to run `wsl --shutdown` in PowerShell and reopen Clacky. Stop and wait.
+
 ### Step 3 — Verify Chrome/Edge is running with remote debugging
 
 **CRITICAL**: Do NOT attempt `browser()` calls yet. First check if the browser is reachable using the API:

data/lib/clacky/providers.rb

@@ -335,28 +335,23 @@ module Clacky
         "name" => "Qwen (Alibaba)",
         "base_url" => "https://dashscope.aliyuncs.com/compatible-mode/v1",
         "api" => "openai-completions",
-        "default_model" => "qwen3.6-plus",
+        "default_model" => "qwen3.7-max",
         "models" => [
+          "qwen3.7-max",
           "qwen3.6-plus",
           "qwen3.6-max",
           "qwen3.6-27b",
           "qwen3.6-flash",
           "qwen-plus-latest",
-          "qwen-vl-plus",
-          "qwen-vl-max"
         ],
         "endpoint_variants" => [
           { "label" => "Mainland China",  "label_key" => "settings.models.baseurl.variant.mainland_cn",   "base_url" => "https://dashscope.aliyuncs.com/compatible-mode/v1",     "region" => "cn"   }.freeze,
           { "label" => "Singapore",       "label_key" => "settings.models.baseurl.variant.international", "base_url" => "https://dashscope-intl.aliyuncs.com/compatible-mode/v1", "region" => "intl" }.freeze,
           { "label" => "US (Virginia)",   "label_key" => "settings.models.baseurl.variant.us",            "base_url" => "https://dashscope-us.aliyuncs.com/compatible-mode/v1",   "region" => "us"   }.freeze
         ].freeze,
-        "capabilities" => { "vision" => false }.freeze,
-        "model_capabilities" => {
-          "qwen3.6-27b"  => { "vision" => true }.freeze,
-          "qwen-vl-plus" => { "vision" => true }.freeze,
-          "qwen-vl-max"  => { "vision" => true }.freeze
-        }.freeze,
+        "capabilities" => { "vision" => true }.freeze,
         "lite_models" => {
+          "qwen3.7-max"      => "qwen3.6-flash",
           "qwen3.6-plus"     => "qwen3.6-flash",
           "qwen3.6-max"      => "qwen3.6-flash",
           "qwen3.6-27b"      => "qwen3.6-flash",

data/lib/clacky/tools/glob.rb

@@ -49,6 +49,14 @@ module Clacky
           return { error: "Base path does not exist: #{base_path}" }
         end
 
+        if Clacky::Utils::FileIgnoreHelper.dangerous_root?(base_path)
+          return {
+            error: "Refusing to recursively glob from broad path '#{base_path}'. " \
+                   "Narrow base_path to a specific subdirectory, " \
+                   "or use '.' to search the working directory."
+          }
+        end
+
         begin
           expanded_path = base_path
 
@@ -70,7 +78,8 @@ module Clacky
           fnmatch_flags = File::FNM_PATHNAME | File::FNM_DOTMATCH
 
           matches = []
-          Clacky::Utils::FileIgnoreHelper.walk_files(expanded_path, skipped: skipped) do |file|
+          walk_status = {}
+          Clacky::Utils::FileIgnoreHelper.walk_files(expanded_path, skipped: skipped, status: walk_status) do |file|
             relative = file[(expanded_path.length + 1)..]
 
             unless File.fnmatch(effective_pattern, relative, fnmatch_flags)
@@ -101,11 +110,13 @@ module Clacky
           # Convert to absolute paths
           matches = matches.map { |path| File.expand_path(path) }
 
+          walk_truncated = walk_status[:truncated] == true
           {
             matches: matches,
             total_matches: total_matches,
             returned: matches.length,
-            truncated: total_matches > limit,
+            truncated: total_matches > limit || walk_truncated,
+            truncation_reason: walk_status[:truncation_reason],
             skipped_files: skipped,
             error: nil
           }
@@ -129,9 +140,13 @@ module Clacky
           count = result[:returned] || 0
           total = result[:total_matches] || 0
           truncated = result[:truncated] ? " (truncated)" : ""
-          
+
           msg = "[OK] Found #{count}/#{total} files#{truncated}"
-          
+
+          if result[:truncation_reason]
+            msg += " [walk #{result[:truncation_reason]}]"
+          end
+
           # Add skipped files info if present
           if result[:skipped_files]
             skipped = result[:skipped_files]

data/lib/clacky/tools/grep.rb

@@ -92,6 +92,14 @@ module Clacky
           return { error: "Path does not exist: #{path}" }
         end
 
+        if File.directory?(expanded_path) && Clacky::Utils::FileIgnoreHelper.dangerous_root?(expanded_path)
+          return {
+            error: "Refusing to recursively grep from broad path '#{path}'. " \
+                   "Narrow the path to a specific subdirectory, " \
+                   "or use '.' to search the working directory."
+          }
+        end
+
         # Limit context_lines
         context_lines = [[context_lines, 0].max, 10].min
 
@@ -115,10 +123,14 @@ module Clacky
                   else
                     fnmatch_flags = File::FNM_PATHNAME | File::FNM_DOTMATCH
                     collected = []
-                    Clacky::Utils::FileIgnoreHelper.walk_files(expanded_path, skipped: skipped) do |f|
+                    walk_status = {}
+                    Clacky::Utils::FileIgnoreHelper.walk_files(expanded_path, skipped: skipped, status: walk_status) do |f|
                       relative = f[(expanded_path.length + 1)..]
                       collected << f if File.fnmatch(file_pattern, relative, fnmatch_flags)
                     end
+                    if walk_status[:truncated]
+                      truncation_reason ||= "walk #{walk_status[:truncation_reason]}"
+                    end
                     collected
                   end
 

data/lib/clacky/tools/security.rb

@@ -20,7 +20,7 @@ module Clacky
     # to a shell / PTY for execution):
     #
     #   1. Block hard-dangerous commands:       sudo, pkill clacky, eval, exec,
-    #                                           `...`, $(...), | sh, | bash,
+    #                                           `...`, | sh, | bash,
     #                                           redirect to /etc /usr /bin.
     #   2. Rewrite `curl ... | bash` → save     script to a file for manual
     #                                           review instead of exec.
@@ -246,7 +246,6 @@ module Clacky
             /exec\s*\(/,
             /system\s*\(/,
             /`[^`]+`/,
-            /\$\([^)]+\)/,
             /\|\s*sh\s*$/,
             /\|\s*bash\s*$/,
             />\s*\/etc\//,

data/lib/clacky/tools/terminal.rb

@@ -72,6 +72,9 @@ module Clacky
           {session_id, input:"pw\n"}      reply to prompt / poll (input:"")
           {session_id, kill:true}         stop
 
+        Single-line only. For multi-line scripts (heredoc, loops, multi-statement blocks)
+        write a file first, then run it: write(path:"/tmp/run.sh", content:...) → terminal(command:"bash /tmp/run.sh").
+
         Response: exit_code = done; session_id = running (state: waiting/background/timeout).
         If output exceeds the limit, `output` is truncated and `full_output_file` points
         at a file on disk — use terminal(command: "grep ... <path>") to search it.
@@ -228,6 +231,17 @@ module Clacky
 
         # Start a new command
         if command && !command.to_s.strip.empty?
+          if multiline_command?(command)
+            return {
+              error: "Multi-line commands are unreliable in our PTY shell " \
+                     "(heredocs / unclosed quotes / multi-line blocks can hang the session).",
+              hint: "Write the script to a file first, then execute it. " \
+                    "Example: 1) write(path: \"/tmp/run.sh\", content: \"...\")  " \
+                    "2) terminal(command: \"bash /tmp/run.sh\")",
+              multiline_blocked: true
+            }
+          end
+
           return do_start(command.to_s, cwd: cwd, env: env, timeout: timeout,
                           idle_ms: idle_ms, background: background ? true : false)
         end
@@ -325,6 +339,12 @@ module Clacky
           project_root: cwd || Dir.pwd
         )
 
+        # WSL interop fix: Windows .exe processes inherit the PTY's stdin fd
+        # and attempt to use it as a Windows Console, causing them to hang
+        # indefinitely. Redirect stdin from /dev/null for any .exe invocation
+        # that doesn't already have an explicit stdin redirect.
+        safe_command = redirect_exe_stdin(safe_command)
+
         # Background / dedicated path — never reuse the persistent shell,
         # because these commands stay running and would occupy the slot.
         if background
@@ -768,7 +788,7 @@ module Clacky
 
         spawn_env = {
           "TERM" => "xterm-256color",
-          "PS1"  => "",
+          "PS1"  => " ",
           # Prevent our sub-shell from polluting the user's ~/.zsh_history
           # (or ~/.bash_history). We fork a full interactive login shell to
           # get rbenv/nvm/brew-shellenv/mise loaded, but every command we
@@ -1179,6 +1199,17 @@ module Clacky
         SLOW_COMMAND_PATTERNS.any? { |pat| s.include?(pat) }
       end
 
+      # True when `command` spans multiple lines. Trailing newlines are
+      # ignored — a single-line command terminated with "\n" is still
+      # single-line. Multi-line commands frequently hang the persistent
+      # PTY shell (incomplete heredoc, unclosed quote, multi-line block
+      # without closer) — the agent should write a script file and
+      # invoke it instead.
+      private def multiline_command?(command)
+        return false if command.nil?
+        command.to_s.sub(/\n+\z/, "").include?("\n")
+      end
+
       # Apply per-line truncation to a cleaned (post-OutputCleaner) string.
       # If any single line exceeds MAX_LINE_CHARS, we chop it at that length
       # and append `…[line truncated: <original> chars]` so the LLM knows
@@ -1358,6 +1389,16 @@ module Clacky
         return "" if lines.empty?
         lines.last(DISPLAY_TAIL_LINES).join("\n")
       end
+
+      # WSL interop fix: Windows .exe processes inherit the PTY stdin fd
+      # and try to use it as a Windows Console, which hangs indefinitely.
+      # Detect .exe invocations and redirect stdin from /dev/null unless
+      # the command already has an explicit stdin redirect.
+      private def redirect_exe_stdin(command)
+        return command unless command =~ /\.exe\b/i
+        return command if command =~ /<\s*[^\s|&;]/
+        "#{command} </dev/null"
+      end
     end
   end
 end

data/lib/clacky/utils/file_ignore_helper.rb

@@ -116,21 +116,94 @@ module Clacky
         CONFIG_FILE_PATTERNS.any? { |pattern| file.match?(pattern) }
       end
 
+      # Paths considered too broad to recursively walk by default. Searching from
+      # these would commonly traverse millions of files (system roots, $HOME with
+      # many workspaces, WSL Windows mounts). Tools should refuse such requests
+      # and ask for a narrower base_path.
+      def self.dangerous_root?(path)
+        return false if path.nil? || path.empty?
+
+        expanded = File.expand_path(path)
+        return true if expanded == "/"
+
+        system_roots = ["/root", "/home", "/Users", "/mnt", "/media", "/var", "/etc", "/usr", "/opt"]
+        return true if system_roots.include?(expanded)
+
+        ["/Users/", "/home/"].each do |prefix|
+          next unless expanded.start_with?(prefix)
+          tail = expanded[prefix.length..]
+          return true if tail && !tail.empty? && !tail.include?("/")
+        end
+
+        return true if expanded =~ %r{\A/mnt/[a-zA-Z]\z}
+
+        home = ENV["HOME"]
+        return true if home && !home.empty? && expanded == File.expand_path(home)
+
+        false
+      end
+
+      # Hard ceiling on directories visited in a single walk. Prevents indefinite
+      # traversal across huge trees (e.g. /root, $HOME, /mnt/c on WSL).
+      MAX_DIRS_VISITED = 20_000
+
+      # Wall-clock budget for a single walk, in seconds.
+      WALK_TIMEOUT_SECONDS = 15
+
+      # Raised internally to abort a walk when a budget is exhausted.
+      class WalkBudgetExceeded < StandardError
+        attr_reader :reason
+        def initialize(reason)
+          @reason = reason
+          super(reason.to_s)
+        end
+      end
+
       # Walk a directory tree, pruning ignored directories early.
       # Yields each non-ignored file path. Supports nested .gitignore files.
       # @param skipped [Hash, nil] If provided, increments :ignored for each gitignore-skipped entry.
-      def self.walk_files(base_path, gitignore: nil, skipped: nil, &block)
-        return enum_for(:walk_files, base_path, gitignore: gitignore, skipped: skipped) unless block_given?
+      # @param status [Hash, nil] If provided, populated with :truncated and :truncation_reason
+      #   when the walk is aborted due to dir-count or wall-clock budget.
+      def self.walk_files(base_path, gitignore: nil, skipped: nil, status: nil,
+                          max_dirs_visited: MAX_DIRS_VISITED,
+                          timeout_seconds: WALK_TIMEOUT_SECONDS,
+                          &block)
+        unless block_given?
+          return enum_for(:walk_files, base_path,
+                          gitignore: gitignore, skipped: skipped, status: status,
+                          max_dirs_visited: max_dirs_visited, timeout_seconds: timeout_seconds)
+        end
 
         root_gitignore = gitignore || begin
           gi_path = find_gitignore(base_path)
           gi_path ? Clacky::GitignoreParser.new(gi_path) : nil
         end
 
-        _walk_recursive(base_path, base_path, root_gitignore, skipped, &block)
+        budget = {
+          dirs_visited: 0,
+          max_dirs: max_dirs_visited,
+          deadline: timeout_seconds ? (Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout_seconds) : nil
+        }
+
+        begin
+          _walk_recursive(base_path, base_path, root_gitignore, skipped, budget, &block)
+        rescue WalkBudgetExceeded => e
+          if status
+            status[:truncated] = true
+            status[:truncation_reason] = e.reason.to_s
+          end
+        end
       end
 
-      def self._walk_recursive(dir, base_path, gitignore, skipped, &block)
+      def self._walk_recursive(dir, base_path, gitignore, skipped, budget, &block)
+        budget[:dirs_visited] += 1
+        if budget[:dirs_visited] > budget[:max_dirs]
+          raise WalkBudgetExceeded.new(:max_dirs_visited)
+        end
+        if budget[:deadline] && Process.clock_gettime(Process::CLOCK_MONOTONIC) > budget[:deadline]
+          raise WalkBudgetExceeded.new(:timeout)
+        end
+
         child_gitignore_path = File.join(dir, ".gitignore")
         if dir != base_path && File.exist?(child_gitignore_path)
           gitignore ||= Clacky::GitignoreParser.new(nil)
@@ -153,7 +226,7 @@ module Clacky
             if gitignore&.ignored?("#{relative}/") || should_ignore_file?(full, base_path, gitignore)
               next
             end
-            _walk_recursive(full, base_path, gitignore, skipped, &block)
+            _walk_recursive(full, base_path, gitignore, skipped, budget, &block)
           else
             if !is_config_file?(full) && should_ignore_file?(full, base_path, gitignore)
               skipped[:ignored] += 1 if skipped

data/lib/clacky/utils/model_pricing.rb

@@ -366,6 +366,24 @@ module Clacky
       #     surprising users with the explicit 25% surcharge).
       #   - We bill reads at 20% (implicit rate) — the conservative side; users on
       #     explicit caching will see real bills slightly *lower* than displayed.
+      "qwen3.7-max" => {
+        input:  { default: 1.20, over_200k: 1.20 },
+        output: { default: 6.00, over_200k: 6.00 },
+        cache:  { write: 1.20, read: 0.24 }
+      },
+
+      "qwen3.7-plus" => {
+        input:  { default: 0.40, over_200k: 0.40 },
+        output: { default: 2.40, over_200k: 2.40 },
+        cache:  { write: 0.40, read: 0.08 }
+      },
+
+      "qwen3.7-flash" => {
+        input:  { default: 0.15, over_200k: 0.15 },
+        output: { default: 0.90, over_200k: 0.90 },
+        cache:  { write: 0.15, read: 0.03 }
+      },
+
       "qwen3.6-plus" => {
         input:  { default: 0.40, over_200k: 0.40 },
         output: { default: 2.40, over_200k: 2.40 },
@@ -571,9 +589,16 @@ module Clacky
           "minimax-m2.7"
 
         # Qwen (Alibaba DashScope) — strict anchored match per registered
-        # model id in providers.rb. qwen3.6-* are the new flagship line;
-        # qwen-plus-latest is the rolling alias for the latest Qwen-Plus
-        # release; qwen-vl-* are the multimodal SKUs.
+        # model id in providers.rb. qwen3.7-* is the latest flagship line;
+        # qwen3.6-* are the previous generation; qwen-plus-latest is the
+        # rolling alias for the latest Qwen-Plus release; qwen-vl-* are
+        # the multimodal SKUs.
+        when /^qwen3\.7-max$/i
+          "qwen3.7-max"
+        when /^qwen3\.7-plus$/i
+          "qwen3.7-plus"
+        when /^qwen3\.7-flash$/i
+          "qwen3.7-flash"
         when /^qwen3\.6-plus$/i
           "qwen3.6-plus"
         when /^qwen3\.6-max$/i

data/lib/clacky/utils/scripts_manager.rb

@@ -21,6 +21,7 @@ module Clacky
         install_browser.sh
         install_system_deps.sh
         install_rails_deps.sh
+        wsl_network_doctor.ps1
       ].freeze
 
       # Copy bundled scripts to ~/.clacky/scripts/ if missing or outdated.

data/lib/clacky/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Clacky
-  VERSION = "1.2.2"
+  VERSION = "1.2.3"
 end

data/scripts/build/lib/apt.sh

@@ -4,6 +4,76 @@
 # Sets-Vars: (none)
 # Include via: @include lib/apt.sh
 
+# Wait until apt/dpkg lock files are no longer held (e.g. by apt-daily on
+# freshly-booted WSL/Ubuntu). Uses flock(1) — the same mechanism apt uses —
+# rather than checking file existence (the lock files are always present;
+# advisory locks live in the kernel, not the filesystem).
+wait_apt_lock() {
+    [ "$DISTRO" = "ubuntu" ] || [ "$DISTRO" = "debian" ] || return 0
+
+    local locks=(
+        "/var/lib/dpkg/lock-frontend"
+        "/var/lib/dpkg/lock"
+        "/var/lib/apt/lists/lock"
+    )
+    local max_wait="${1:-120}"
+    local waited=0
+    local announced=false
+
+    while :; do
+        local busy=false
+        for f in "${locks[@]}"; do
+            [ -e "$f" ] || continue
+            if ! sudo flock -n "$f" -c true 2>/dev/null; then
+                busy=true
+                break
+            fi
+        done
+
+        [ "$busy" = false ] && break
+
+        if [ "$announced" = false ]; then
+            print_info "Waiting for system apt/dpkg to finish (up to ${max_wait}s)..."
+            announced=true
+        fi
+
+        if [ "$waited" -ge "$max_wait" ]; then
+            print_error "apt is still locked after ${max_wait}s."
+            print_info  "On WSL try: 'wsl --shutdown' from PowerShell, then rerun the installer."
+            return 1
+        fi
+
+        sleep 3
+        waited=$((waited + 3))
+    done
+
+    [ "$announced" = true ] && print_success "apt lock released"
+    return 0
+}
+
+# Run an apt-get subcommand with lock-wait + transient-failure retry.
+# Usage: apt_get_run update [-qq]
+#        apt_get_run install -y pkg1 pkg2
+apt_get_run() {
+    local attempts=3
+    local i=1
+    while [ "$i" -le "$attempts" ]; do
+        wait_apt_lock 120 || return 1
+        if sudo apt-get "$@"; then
+            return 0
+        fi
+        local rc=$?
+        if [ "$i" -lt "$attempts" ]; then
+            print_warning "apt-get $1 failed (exit $rc), retrying ($i/$((attempts-1)))..."
+            sleep 5
+        else
+            print_error "apt-get $1 failed after $attempts attempts."
+            return "$rc"
+        fi
+        i=$((i + 1))
+    done
+}
+
 # Configure apt mirror for CN region and run apt-get update.
 # Guards: only runs on ubuntu/debian ($DISTRO).
 # Relies on $USE_CN_MIRRORS set by detect_network_region (network.sh).
@@ -51,6 +121,6 @@ EOF
         print_info "Region: global — using default apt sources"
     fi
 
-    sudo apt-get update -qq
+    apt_get_run update -qq || return 1
     print_success "apt updated"
 }

data/scripts/build/src/install.sh.cc

@@ -34,7 +34,7 @@ ensure_ruby() {
 
     if is_linux_apt; then
         print_info "Installing Ruby via apt..."
-        sudo apt-get install -y ruby ruby-dev 2>/dev/null && check_ruby && return 0
+        apt_get_run install -y ruby ruby-dev 2>/dev/null && check_ruby && return 0
         print_warning "apt Ruby install failed or version too old"
     fi
 

data/scripts/build/src/install_rails_deps.sh.cc

@@ -31,8 +31,8 @@ install_ruby() {
     if is_macos; then
         brew install openssl@3 libyaml gmp
     elif is_linux_apt; then
-        sudo apt-get install -y \
-            rustc libssl-dev libyaml-dev zlib1g-dev libgmp-dev
+        apt_get_run install -y \
+            rustc libssl-dev libyaml-dev zlib1g-dev libgmp-dev || return 1
     fi
 
     ensure_mise || return 1
@@ -75,8 +75,8 @@ install_postgres() {
 
     elif is_linux_apt; then
         setup_apt_mirror
-        sudo apt-get install -y postgresql libpq-dev \
-            libssl-dev libreadline-dev zlib1g-dev libyaml-dev libffi-dev
+        apt_get_run install -y postgresql libpq-dev \
+            libssl-dev libreadline-dev zlib1g-dev libyaml-dev libffi-dev || return 1
         sudo systemctl enable --now postgresql || true
     fi
 

data/scripts/build/src/install_system_deps.sh.cc

@@ -67,7 +67,7 @@ ensure_linux_deps() {
 
     detect_network_region
     setup_apt_mirror
-    sudo apt-get install -y build-essential git curl python3
+    apt_get_run install -y build-essential git curl python3 || return 1
     print_success "Dependencies installed"
 }
 

data/scripts/install.sh

@@ -271,6 +271,76 @@ detect_network_region() {
 
 # ---[ @include lib/apt.sh ]---
 
+# Wait until apt/dpkg lock files are no longer held (e.g. by apt-daily on
+# freshly-booted WSL/Ubuntu). Uses flock(1) — the same mechanism apt uses —
+# rather than checking file existence (the lock files are always present;
+# advisory locks live in the kernel, not the filesystem).
+wait_apt_lock() {
+    [ "$DISTRO" = "ubuntu" ] || [ "$DISTRO" = "debian" ] || return 0
+
+    local locks=(
+        "/var/lib/dpkg/lock-frontend"
+        "/var/lib/dpkg/lock"
+        "/var/lib/apt/lists/lock"
+    )
+    local max_wait="${1:-120}"
+    local waited=0
+    local announced=false
+
+    while :; do
+        local busy=false
+        for f in "${locks[@]}"; do
+            [ -e "$f" ] || continue
+            if ! sudo flock -n "$f" -c true 2>/dev/null; then
+                busy=true
+                break
+            fi
+        done
+
+        [ "$busy" = false ] && break
+
+        if [ "$announced" = false ]; then
+            print_info "Waiting for system apt/dpkg to finish (up to ${max_wait}s)..."
+            announced=true
+        fi
+
+        if [ "$waited" -ge "$max_wait" ]; then
+            print_error "apt is still locked after ${max_wait}s."
+            print_info  "On WSL try: 'wsl --shutdown' from PowerShell, then rerun the installer."
+            return 1
+        fi
+
+        sleep 3
+        waited=$((waited + 3))
+    done
+
+    [ "$announced" = true ] && print_success "apt lock released"
+    return 0
+}
+
+# Run an apt-get subcommand with lock-wait + transient-failure retry.
+# Usage: apt_get_run update [-qq]
+#        apt_get_run install -y pkg1 pkg2
+apt_get_run() {
+    local attempts=3
+    local i=1
+    while [ "$i" -le "$attempts" ]; do
+        wait_apt_lock 120 || return 1
+        if sudo apt-get "$@"; then
+            return 0
+        fi
+        local rc=$?
+        if [ "$i" -lt "$attempts" ]; then
+            print_warning "apt-get $1 failed (exit $rc), retrying ($i/$((attempts-1)))..."
+            sleep 5
+        else
+            print_error "apt-get $1 failed after $attempts attempts."
+            return "$rc"
+        fi
+        i=$((i + 1))
+    done
+}
+
 # Configure apt mirror for CN region and run apt-get update.
 # Guards: only runs on ubuntu/debian ($DISTRO).
 # Relies on $USE_CN_MIRRORS set by detect_network_region (network.sh).
@@ -318,7 +388,7 @@ EOF
         print_info "Region: global — using default apt sources"
     fi
 
-    sudo apt-get update -qq
+    apt_get_run update -qq || return 1
     print_success "apt updated"
 }
 
@@ -427,7 +497,7 @@ ensure_ruby() {
 
     if is_linux_apt; then
         print_info "Installing Ruby via apt..."
-        sudo apt-get install -y ruby ruby-dev 2>/dev/null && check_ruby && return 0
+        apt_get_run install -y ruby ruby-dev 2>/dev/null && check_ruby && return 0
         print_warning "apt Ruby install failed or version too old"
     fi
 

data/scripts/install_rails_deps.sh

@@ -275,6 +275,76 @@ detect_network_region() {
 
 # ---[ @include lib/apt.sh ]---
 
+# Wait until apt/dpkg lock files are no longer held (e.g. by apt-daily on
+# freshly-booted WSL/Ubuntu). Uses flock(1) — the same mechanism apt uses —
+# rather than checking file existence (the lock files are always present;
+# advisory locks live in the kernel, not the filesystem).
+wait_apt_lock() {
+    [ "$DISTRO" = "ubuntu" ] || [ "$DISTRO" = "debian" ] || return 0
+
+    local locks=(
+        "/var/lib/dpkg/lock-frontend"
+        "/var/lib/dpkg/lock"
+        "/var/lib/apt/lists/lock"
+    )
+    local max_wait="${1:-120}"
+    local waited=0
+    local announced=false
+
+    while :; do
+        local busy=false
+        for f in "${locks[@]}"; do
+            [ -e "$f" ] || continue
+            if ! sudo flock -n "$f" -c true 2>/dev/null; then
+                busy=true
+                break
+            fi
+        done
+
+        [ "$busy" = false ] && break
+
+        if [ "$announced" = false ]; then
+            print_info "Waiting for system apt/dpkg to finish (up to ${max_wait}s)..."
+            announced=true
+        fi
+
+        if [ "$waited" -ge "$max_wait" ]; then
+            print_error "apt is still locked after ${max_wait}s."
+            print_info  "On WSL try: 'wsl --shutdown' from PowerShell, then rerun the installer."
+            return 1
+        fi
+
+        sleep 3
+        waited=$((waited + 3))
+    done
+
+    [ "$announced" = true ] && print_success "apt lock released"
+    return 0
+}
+
+# Run an apt-get subcommand with lock-wait + transient-failure retry.
+# Usage: apt_get_run update [-qq]
+#        apt_get_run install -y pkg1 pkg2
+apt_get_run() {
+    local attempts=3
+    local i=1
+    while [ "$i" -le "$attempts" ]; do
+        wait_apt_lock 120 || return 1
+        if sudo apt-get "$@"; then
+            return 0
+        fi
+        local rc=$?
+        if [ "$i" -lt "$attempts" ]; then
+            print_warning "apt-get $1 failed (exit $rc), retrying ($i/$((attempts-1)))..."
+            sleep 5
+        else
+            print_error "apt-get $1 failed after $attempts attempts."
+            return "$rc"
+        fi
+        i=$((i + 1))
+    done
+}
+
 # Configure apt mirror for CN region and run apt-get update.
 # Guards: only runs on ubuntu/debian ($DISTRO).
 # Relies on $USE_CN_MIRRORS set by detect_network_region (network.sh).
@@ -322,7 +392,7 @@ EOF
         print_info "Region: global — using default apt sources"
     fi
 
-    sudo apt-get update -qq
+    apt_get_run update -qq || return 1
     print_success "apt updated"
 }
 
@@ -632,8 +702,8 @@ install_ruby() {
     if is_macos; then
         brew install openssl@3 libyaml gmp
     elif is_linux_apt; then
-        sudo apt-get install -y \
-            rustc libssl-dev libyaml-dev zlib1g-dev libgmp-dev
+        apt_get_run install -y \
+            rustc libssl-dev libyaml-dev zlib1g-dev libgmp-dev || return 1
     fi
 
     ensure_mise || return 1
@@ -676,8 +746,8 @@ install_postgres() {
 
     elif is_linux_apt; then
         setup_apt_mirror
-        sudo apt-get install -y postgresql libpq-dev \
-            libssl-dev libreadline-dev zlib1g-dev libyaml-dev libffi-dev
+        apt_get_run install -y postgresql libpq-dev \
+            libssl-dev libreadline-dev zlib1g-dev libyaml-dev libffi-dev || return 1
         sudo systemctl enable --now postgresql || true
     fi
 

data/scripts/install_system_deps.sh

@@ -270,6 +270,76 @@ detect_network_region() {
 
 # ---[ @include lib/apt.sh ]---
 
+# Wait until apt/dpkg lock files are no longer held (e.g. by apt-daily on
+# freshly-booted WSL/Ubuntu). Uses flock(1) — the same mechanism apt uses —
+# rather than checking file existence (the lock files are always present;
+# advisory locks live in the kernel, not the filesystem).
+wait_apt_lock() {
+    [ "$DISTRO" = "ubuntu" ] || [ "$DISTRO" = "debian" ] || return 0
+
+    local locks=(
+        "/var/lib/dpkg/lock-frontend"
+        "/var/lib/dpkg/lock"
+        "/var/lib/apt/lists/lock"
+    )
+    local max_wait="${1:-120}"
+    local waited=0
+    local announced=false
+
+    while :; do
+        local busy=false
+        for f in "${locks[@]}"; do
+            [ -e "$f" ] || continue
+            if ! sudo flock -n "$f" -c true 2>/dev/null; then
+                busy=true
+                break
+            fi
+        done
+
+        [ "$busy" = false ] && break
+
+        if [ "$announced" = false ]; then
+            print_info "Waiting for system apt/dpkg to finish (up to ${max_wait}s)..."
+            announced=true
+        fi
+
+        if [ "$waited" -ge "$max_wait" ]; then
+            print_error "apt is still locked after ${max_wait}s."
+            print_info  "On WSL try: 'wsl --shutdown' from PowerShell, then rerun the installer."
+            return 1
+        fi
+
+        sleep 3
+        waited=$((waited + 3))
+    done
+
+    [ "$announced" = true ] && print_success "apt lock released"
+    return 0
+}
+
+# Run an apt-get subcommand with lock-wait + transient-failure retry.
+# Usage: apt_get_run update [-qq]
+#        apt_get_run install -y pkg1 pkg2
+apt_get_run() {
+    local attempts=3
+    local i=1
+    while [ "$i" -le "$attempts" ]; do
+        wait_apt_lock 120 || return 1
+        if sudo apt-get "$@"; then
+            return 0
+        fi
+        local rc=$?
+        if [ "$i" -lt "$attempts" ]; then
+            print_warning "apt-get $1 failed (exit $rc), retrying ($i/$((attempts-1)))..."
+            sleep 5
+        else
+            print_error "apt-get $1 failed after $attempts attempts."
+            return "$rc"
+        fi
+        i=$((i + 1))
+    done
+}
+
 # Configure apt mirror for CN region and run apt-get update.
 # Guards: only runs on ubuntu/debian ($DISTRO).
 # Relies on $USE_CN_MIRRORS set by detect_network_region (network.sh).
@@ -317,7 +387,7 @@ EOF
         print_info "Region: global — using default apt sources"
     fi
 
-    sudo apt-get update -qq
+    apt_get_run update -qq || return 1
     print_success "apt updated"
 }
 
@@ -462,7 +532,7 @@ ensure_linux_deps() {
 
     detect_network_region
     setup_apt_mirror
-    sudo apt-get install -y build-essential git curl python3
+    apt_get_run install -y build-essential git curl python3 || return 1
     print_success "Dependencies installed"
 }
 

data/scripts/wsl_network_doctor.ps1

@@ -0,0 +1,196 @@
+# wsl_network_doctor.ps1 — diagnose & repair WSL2 mirrored networking for the browser tool.
+#
+# Designed to be invoked from inside WSL via:
+#   powershell.exe -NoProfile -ExecutionPolicy Bypass -File <win-path-to-this-script> <subcommand>
+#
+# Subcommands:
+#   status   Check whether mirrored networking is configured.
+#   enable   Write networkingMode=mirrored to %USERPROFILE%\.wslconfig.
+#   repair   Restart Windows Host Network Service (HNS) via UAC elevation.
+#
+# Exit codes (status only):
+#   0   OK              — mirrored configured, OR running on WSL1 (no config needed)
+#   10  NEED_ENABLE     — mirrored not configured, run `enable`
+#   20  NEED_REPAIR     — configured but suspected broken, run `repair`
+#   1   unexpected error
+#
+# `enable` and `repair` exit 0 on success, 1 on failure.
+
+param(
+    [Parameter(Position = 0)]
+    [ValidateSet('status', 'enable', 'repair')]
+    [string]$Command
+)
+
+$ErrorActionPreference = 'Stop'
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+function Get-WslConfigPath {
+    return (Join-Path $env:USERPROFILE '.wslconfig')
+}
+
+function Test-MirroredConfigured {
+    $cfg = Get-WslConfigPath
+    if (-not (Test-Path $cfg)) { return $false }
+    $content = Get-Content $cfg -Raw -ErrorAction SilentlyContinue
+    if ($null -eq $content) { return $false }
+    return ($content -match '(?im)^\s*networkingMode\s*=\s*mirrored\s*$')
+}
+
+# Returns 1 or 2 if Ubuntu is registered, $null otherwise.
+# Parses `wsl.exe -l -v` output (UTF-16, may contain a star marker on default distro).
+function Get-UbuntuWslVersion {
+    try {
+        $raw = & wsl.exe -l -v 2>$null
+    } catch {
+        return $null
+    }
+    if (-not $raw) { return $null }
+
+    foreach ($line in $raw) {
+        $clean = ($line -replace '\s+', ' ').Trim().TrimStart('*').Trim()
+        if ($clean -match '^Ubuntu(?:-[\w\.]+)?\s+\S+\s+(\d+)\s*$') {
+            return [int]$matches[1]
+        }
+    }
+    return $null
+}
+
+# ---------------------------------------------------------------------------
+# Subcommand: status
+# ---------------------------------------------------------------------------
+
+function Invoke-Status {
+    $wslVer = Get-UbuntuWslVersion
+    if ($wslVer -eq 1) {
+        Write-Host "OK: Ubuntu is running on WSL1 — shares the Windows network stack directly."
+        Write-Host "No mirrored configuration needed. The browser tool can connect to 127.0.0.1 as-is."
+        exit 0
+    }
+
+    if (Test-MirroredConfigured) {
+        Write-Host "OK: mirrored networking is configured in .wslconfig."
+        Write-Host "If the browser tool still cannot connect, run: wsl_network_doctor.ps1 repair"
+        exit 0
+    }
+
+    Write-Host "NEED_ENABLE: mirrored networking is not configured."
+    Write-Host "Run: wsl_network_doctor.ps1 enable"
+    exit 10
+}
+
+# ---------------------------------------------------------------------------
+# Subcommand: enable
+# ---------------------------------------------------------------------------
+
+function Invoke-Enable {
+    if (Test-MirroredConfigured) {
+        Write-Host "OK: already enabled. No changes needed."
+        Write-Host "If the browser tool still cannot connect, run: wsl_network_doctor.ps1 repair"
+        exit 0
+    }
+
+    $cfg = Get-WslConfigPath
+    Write-Host "Writing networkingMode=mirrored to $cfg ..."
+
+    if (-not (Test-Path $cfg)) {
+        New-Item -ItemType File -Path $cfg -Force | Out-Null
+    }
+
+    $content = Get-Content $cfg -Raw -ErrorAction SilentlyContinue
+    if ($null -eq $content) { $content = '' }
+
+    if ($content -match '(?im)^\s*networkingMode\s*=') {
+        $new = [regex]::Replace($content, '(?im)^\s*networkingMode\s*=.*$', 'networkingMode=mirrored')
+        Set-Content -Path $cfg -Value $new -NoNewline
+    } else {
+        if ($content -notmatch '(?im)^\[wsl2\]') {
+            if ($content.Length -gt 0 -and -not $content.EndsWith([char]10)) {
+                Add-Content -Path $cfg -Value ''
+            }
+            Add-Content -Path $cfg -Value '[wsl2]'
+        }
+        Add-Content -Path $cfg -Value 'networkingMode=mirrored'
+    }
+
+    Write-Host "WROTE: .wslconfig updated."
+    Write-Host ""
+    Write-Host "Next step (cannot be done from inside WSL):"
+    Write-Host "  1. Open Windows PowerShell"
+    Write-Host "  2. Run: wsl --shutdown"
+    Write-Host "  3. Reopen Clacky and run /browser-setup again"
+    exit 0
+}
+
+# ---------------------------------------------------------------------------
+# Subcommand: repair
+# ---------------------------------------------------------------------------
+# Restart Windows Host Network Service (HNS). Requires admin → triggers UAC.
+# Does NOT call `wsl --shutdown` here — the user must run it manually after
+# the elevated window finishes, otherwise our own WSL session would be killed.
+
+function Invoke-Repair {
+    Write-Host "Repairing Windows Host Network Service (HNS) ..."
+    Write-Host ""
+    Write-Host "A Windows User Account Control (UAC) dialog will appear."
+    Write-Host "Please click 'Yes' to allow the repair script to run."
+    Write-Host ""
+
+    $inner = @'
+try {
+    Stop-Service hns -Force -ErrorAction SilentlyContinue
+    Start-Service hns -ErrorAction Stop
+    Write-Host "HNS restarted successfully."
+} catch {
+    Write-Host "Repair failed: $_"
+    Start-Sleep 5
+    exit 1
+}
+Write-Host ""
+Write-Host "Repair complete. Please run 'wsl --shutdown' in PowerShell, then reopen Clacky."
+Start-Sleep 4
+'@
+
+    $encoded = [Convert]::ToBase64String([Text.Encoding]::Unicode.GetBytes($inner))
+
+    try {
+        Start-Process powershell -Verb RunAs -ArgumentList '-NoProfile', '-EncodedCommand', $encoded
+    } catch {
+        Write-Host "FAILED: could not trigger UAC prompt: $_"
+        Write-Host ""
+        Write-Host "You can run the repair manually:"
+        Write-Host "  1. Open PowerShell as Administrator"
+        Write-Host "  2. Run: net stop hns; net start hns"
+        Write-Host "  3. Run: wsl --shutdown"
+        Write-Host "  4. Reopen Clacky"
+        exit 1
+    }
+
+    Write-Host "Repair script launched in an elevated PowerShell window."
+    Write-Host ""
+    Write-Host "After the elevated window finishes:"
+    Write-Host "  1. Run in regular PowerShell: wsl --shutdown"
+    Write-Host "  2. Reopen Clacky and run /browser-setup again"
+    exit 0
+}
+
+# ---------------------------------------------------------------------------
+# Dispatch
+# ---------------------------------------------------------------------------
+
+switch ($Command) {
+    'status' { Invoke-Status }
+    'enable' { Invoke-Enable }
+    'repair' { Invoke-Repair }
+    default {
+        Write-Host "Usage: wsl_network_doctor.ps1 {status|enable|repair}"
+        Write-Host ""
+        Write-Host "  status  Check whether WSL2 mirrored networking is configured."
+        Write-Host "  enable  Write networkingMode=mirrored to %USERPROFILE%\.wslconfig."
+        Write-Host "  repair  Restart Windows Host Network Service (HNS) via UAC."
+        exit 2
+    }
+}

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: openclacky
 version: !ruby/object:Gem::Version
-  version: 1.2.2
+  version: 1.2.3
 platform: ruby
 authors:
 - windy
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-05-25 00:00:00.000000000 Z
+date: 2026-05-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -596,6 +596,7 @@ files:
 - scripts/install_rails_deps.sh
 - scripts/install_system_deps.sh
 - scripts/uninstall.sh
+- scripts/wsl_network_doctor.ps1
 - sig/clacky.rbs
 homepage: https://github.com/clacky-ai/openclacky
 licenses: