openclacky 0.9.24 → 0.9.26

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5338bcdeaf4b2aafed416365f56467a99a6107911b24df2bfe9d94d757d03528
-  data.tar.gz: 8e06f6ca6b0d5a0a9c70ab758fc13b2f84d755f7d61e30a9708fdadd4db82309
+  metadata.gz: 65dad1ba4790fcffb30157bcc74a05a9f9cbd3e341ead0e007e6c768b0c11fd1
+  data.tar.gz: f507ade251d206b073eb1b88c236d8905e9c986718d93c62cf3f2b575fa908bb
 SHA512:
-  metadata.gz: 7862cd557ea5ba9e88184b314fd88fc820d1f4e0c5a9bbebbfcdee75f33301876aff7df7f13cf07eaa21c7fb47d0efa65e7f051c1641ced6c20d1142e9e52819
-  data.tar.gz: b33e3cc3331e70328d366a38b67e472c760eb6bbe4b5621532ee4ae60585303d9042c4953f29f31e4256f357765d8aafee2b3e69fa87f31c386f9310be790c46
+  metadata.gz: f70df4500b95cd35c2a3fb245e384f94bbf4051da6528d6b9bd76a9a38e81838844cc68276ab0b7fc3833982252b9d61c1c5c3b414e22422049e2a91f2c24a4b
+  data.tar.gz: 6cd678e1288d06f6997c01c056b898c900ba9b7fcde2bacdd3a35b113d0ab4d33d3e5e2c2fde9a31d1c9c351b615b93f28bcfa305eb7489b4deda1c1c801ce45

data/CHANGELOG.md

@@ -7,6 +7,39 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.9.26] - 2026-04-03
+
+### Added
+- **Long-running shell output streaming**: shell commands that run for a long time now stream output progressively to the Web UI instead of waiting until completion — no more blank screen for slow commands
+
+### Fixed
+- **Session rename for non-active sessions**: renaming a session that isn't currently active now updates immediately in the sidebar (previously required a page refresh)
+- **Feishu channel setup timeout**: increased timeout to 180s to prevent setup failures on slow networks
+- **WSL browser setup tip**: improved browser-setup skill instructions for WSL environments
+- **ARM install mirror**: install scripts now correctly use the Aliyun mirror on ARM machines
+
+## [0.9.25] - 2026-04-02
+
+### Added
+- **CSV file upload support**: you can now upload `.csv` files in the Web UI — agent can read and analyse tabular data directly
+- **Browser install tips**: when a browser-dependent command fails, the agent now shows a clear install tip with instructions to set up Chrome/Edge, rather than a cryptic error
+- **Auto-focus on file upload dialog**: the file input field is now auto-focused when the upload dialog opens, improving keyboard UX
+- **Session ID search in Web UI**: you can now search sessions by session ID in addition to session name
+
+### Fixed
+- **WeChat (Weixin) file upload**: fixed a bug where file attachments sent via WeChat were not correctly forwarded to the agent
+- **WeChat without browser**: WeChat channel now works even when no browser tool is configured — falls back gracefully
+- **API message timeout**: fixed a race condition in message compression / session serialisation that could cause API requests to time out mid-conversation
+- **Session chunk replay**: fixed a bug where streaming (chunk-based) messages were incorrectly replayed when restoring a session
+
+### Improved
+- **Shell tool robustness**: `pkill` commands are now scope-limited to prevent accidental process kills; server process cleans up properly when the terminal is closed
+- **Broken pipe handling**: improved error handling in the HTTP server and shell tool to avoid noisy broken-pipe errors on abrupt connection close
+
+### More
+- Updated product-help skill with new session search and CSV upload documentation
+- Updated channel-setup skill with improved WeChat non-browser setup guide
+
 ## [0.9.24] - 2026-04-02
 
 ### Added

data/lib/clacky/agent/message_compressor_helper.rb

@@ -128,7 +128,11 @@ module Clacky
         original_messages = @history.to_a[0..-2]  # All except the last (compression instruction)
 
         # Archive compressed messages to a chunk MD file before discarding them
-        chunk_index = @compressed_summaries.size + 1
+        # Count existing compressed_summary messages in history to determine the next chunk index.
+        # Using @compressed_summaries.size would reset to 0 on process restart and overwrite existing
+        # chunk files, creating circular chunk references. Counting from history is always accurate.
+        existing_chunk_count = original_messages.count { |m| m[:compressed_summary] }
+        chunk_index = existing_chunk_count + 1
         chunk_path = save_compressed_chunk(
           original_messages,
           compression_context[:recent_messages],

data/lib/clacky/agent/session_serializer.rb

@@ -152,6 +152,16 @@ module Clacky
             # Compressed summary sitting before any user rounds — expand it from chunk md
             chunk_rounds = parse_chunk_md_to_rounds(msg[:chunk_path])
             rounds.concat(chunk_rounds)
+            # After expanding, treat the last chunk round as the current round so that
+            # any orphaned assistant/tool messages that follow in session.json (belonging
+            # to the same task whose user message was compressed into the chunk) get
+            # appended here instead of being silently discarded.
+            current_round = rounds.last
+          elsif rounds.last
+            # Orphaned non-user message with no current_round yet (e.g. recent_messages
+            # after compression started mid-task with no leading user message).
+            # Attach to the last known round rather than drop silently.
+            rounds.last[:events] << msg
           end
         end
 
@@ -211,10 +221,27 @@ module Clacky
       #
       # @param chunk_path [String] Path to the chunk md file
       # @return [Array<Hash>] rounds array (may be empty if file missing/unreadable)
-      private def parse_chunk_md_to_rounds(chunk_path)
-        return [] unless chunk_path && File.exist?(chunk_path.to_s)
+      private def parse_chunk_md_to_rounds(chunk_path, visited: Set.new)
+        return [] unless chunk_path
+
+        # 1. Try the stored absolute path first (same machine, normal case).
+        # 2. If not found, fall back to basename + SESSIONS_DIR (cross-user / cross-machine).
+        resolved = chunk_path.to_s
+        unless File.exist?(resolved)
+          resolved = File.join(Clacky::SessionManager::SESSIONS_DIR, File.basename(resolved))
+        end
+
+        return [] unless File.exist?(resolved)
+
+        # Guard against circular chunk references (e.g. chunk-3 → chunk-2 → chunk-1 → chunk-9 → … → chunk-3)
+        canonical = File.expand_path(resolved)
+        if visited.include?(canonical)
+          Clacky::Logger.warn("parse_chunk_md_to_rounds: circular reference detected, skipping #{canonical}")
+          return []
+        end
+        visited = visited.dup.add(canonical)
 
-        raw = File.read(chunk_path.to_s, encoding: "utf-8")
+        raw = File.read(resolved)
 
         # Parse YAML front matter to get archived_at for synthetic timestamps
         archived_at = nil
@@ -275,7 +302,7 @@ module Clacky
 
           # Nested chunk: expand it recursively, prepend before current rounds
           if sec[:nested_chunk]
-            nested = parse_chunk_md_to_rounds(sec[:nested_chunk])
+            nested = parse_chunk_md_to_rounds(sec[:nested_chunk], visited: visited)
             rounds = nested + rounds unless nested.empty?
             # Also render its summary text as an assistant event in current round if any
             if current_round && !text.empty?

data/lib/clacky/agent.rb

@@ -662,6 +662,20 @@ module Clacky
               sleep 2
               @ui.show_progress(progress_message, prefix_newline: false, output_buffer: output_buffer)
               progress_shown = true
+
+              # For shell commands: stream new stdout lines to WebUI as they arrive
+              if output_buffer && @ui.respond_to?(:show_tool_stdout)
+                last_sent_count = 0
+                loop do
+                  sleep 1
+                  stdout_lines = output_buffer[:stdout_lines]&.to_a || []
+                  new_lines = stdout_lines[last_sent_count..]
+                  if new_lines && !new_lines.empty?
+                    @ui.show_tool_stdout(new_lines)
+                    last_sent_count = stdout_lines.size
+                  end
+                end
+              end
             end
           end
 

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

@@ -79,15 +79,25 @@ Tell the user:
 > I've opened `chrome://inspect/#remote-debugging` in your browser.
 > Please click **"Allow remote debugging for this browser instance"** and let me know when done.
 
-If `open` fails (e.g. on WSL or Linux), fall back to:
+If `open` fails (e.g. on WSL or Linux):
+
+**On WSL**, guide the user in simple steps (no PowerShell commands needed):
+
+> To enable remote debugging, please follow these steps:
+>
+> 1. Open **Edge** on Windows
+> 2. Type the following in the address bar and press Enter:
+>    ```
+>    edge://inspect/#remote-debugging
+>    ```
+> 3. Click **"Allow remote debugging for this browser instance"**
+> 4. Let me know when done and I'll continue ✅
+
+**On Linux (non-WSL)**:
 
 > Please open this URL in Chrome or Edge:
 > `chrome://inspect/#remote-debugging`
 > Then click **"Allow remote debugging for this browser instance"** and let me know when done.
->
-> On WSL: launch your browser from PowerShell with remote debugging enabled:
-> - Edge: `Start-Process msedge --ArgumentList "--remote-debugging-port=9222"`
-> - Chrome: `Start-Process chrome --ArgumentList "--remote-debugging-port=9222"`
 
 Wait for the user to confirm, then retry the connection once. If still failing, stop:
 

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

@@ -92,6 +92,7 @@ Run the setup script (full path is available in the supporting files list above)
 ```bash
 ruby "SKILL_DIR/feishu_setup.rb"
 ```
+**Important**: call `safe_shell` with `timeout: 180` — the script may wait up to 90s for a WebSocket connection in Phase 4.
 
 **If exit code is 0:**
 - The script completed successfully.
@@ -206,7 +207,7 @@ On success: "✅ WeCom channel configured. WeCom client → Contacts → Smart B
 
 Weixin uses a QR code login — no app_id/app_secret needed. The token from the QR scan is saved directly in `channels.yml`.
 
-#### Step 1 — Fetch QR code and open in browser
+#### Step 1 — Fetch QR code
 
 Run the script in `--fetch-qr` mode to get the QR URL without blocking:
 
@@ -221,17 +222,29 @@ Parse the JSON output:
 
 If the output contains `"error"`, show it and stop.
 
-Tell the user:
-> Opening the WeChat QR code in your browser. Please scan it with WeChat, then confirm in the app.
+#### Step 2 — Show QR code to user (browser or manual fallback)
 
-**Open the QR code page in browser** — build a local URL and navigate to it:
+Build the local QR page URL (include current Unix timestamp as `since` to detect new logins only):
+```
+http://${CLACKY_SERVER_HOST}:${CLACKY_SERVER_PORT}/weixin-qr.html?url=<URL-encoded qrcode_url>&since=<current_unix_timestamp>
+```
 
+**Try browser first** — attempt to open the QR page using the browser tool:
 ```
-http://${CLACKY_SERVER_HOST}:${CLACKY_SERVER_PORT}/weixin-qr.html?url=<URL-encoded qrcode_url>
+browser(action="navigate", url="<qr_page_url>")
 ```
 
-Use the browser tool to open this URL. The page renders a proper scannable QR code image using qrcode.js.
-Do NOT open the raw `qrcode_url` directly — that page shows "请使用微信扫码打开" with no actual QR image.
+**If browser succeeds:** Tell the user:
+> I've opened the WeChat QR code in your browser. Please scan it with WeChat, then confirm in the app.
+
+**If browser fails (not configured or unavailable):** Fall back to manual — tell the user:
+> Please open the following link in your browser to scan the WeChat QR code:
+>
+> `http://${CLACKY_SERVER_HOST}:${CLACKY_SERVER_PORT}/weixin-qr.html?url=<URL-encoded qrcode_url>`
+>
+> Scan the QR code with WeChat, confirm in the app, then reply "done".
+
+The page renders a proper scannable QR code image. Do NOT open the raw `qrcode_url` directly — that page shows "请使用微信扫码打开" with no actual QR image.
 
 #### Step 3 — Wait for scan and save credentials
 
@@ -243,7 +256,11 @@ ruby "SKILL_DIR/weixin_setup.rb" --qrcode-id "$QRCODE_ID"
 
 Where `$QRCODE_ID` is the `qrcode_id` from Step 2's JSON output.
 
-This command blocks until the user scans and confirms in WeChat (up to 5 minutes), then automatically saves the token via `POST /api/channels/weixin`.
+Run this command with `timeout: 60`. If it doesn't succeed, **retry up to 3 times with the same `$QRCODE_ID`** — the QR code stays valid for 5 minutes. Only stop retrying if:
+- Exit code is 0 → success
+- Output contains "expired" → QR expired, offer to restart from Step 1
+- Output contains "timed out" → offer to restart from Step 1
+- 3 retries exhausted → show error and offer to restart from Step 1
 
 Tell the user while waiting:
 > Waiting for you to scan the QR code and confirm in WeChat... (this may take a moment)

data/lib/clacky/default_skills/product-help/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: product-help
-description: 'Use this skill when the user asks about my own features, configuration, or usage — installation, skills, Web UI, CLI, API config, memory, sessions, encryption, white-label, publishing, pricing, or troubleshooting. Do NOT trigger for general coding tasks unrelated to me.'
+description: 'Use this skill when the user asks about my own features, configuration, or usage — installation, skills, Web UI, CLI, API config, memory, sessions, encryption, white-label, publishing, pricing, troubleshooting, or restarting the server. Do NOT trigger for general coding tasks unrelated to me.'
 fork_agent: true
 user-invocable: false
 auto_summarize: true
@@ -90,3 +90,16 @@ web_fetch(url: "<URL>", max_length: 5000)
 - If the fetched page doesn't answer the question, try the next most relevant URL (max 2 fetches)
 - If still no answer, tell the user: "请访问 https://www.openclacky.com/docs 查看完整文档"
 - Keep answers concise — extract what's relevant, don't paste the whole page
+
+## Restarting the server
+
+If the user asks to restart the clacky/openclacky server (e.g. "重启", "restart", "请重启openclacky"):
+
+**Do NOT fetch any docs.** Just return this answer directly:
+
+> To restart the server gracefully (hot restart, zero downtime):
+> ```
+> kill -USR1 $CLACKY_MASTER_PID
+> ```
+> This sends USR1 to the Master process, which spawns a new Worker and gracefully stops the old one.
+> The `$CLACKY_MASTER_PID` environment variable is already set in the current session.

data/lib/clacky/server/channel/adapters/weixin/adapter.rb

@@ -260,14 +260,17 @@ module Clacky
           # Extract and materialize file attachments from an inbound item_list.
           #
           # Images are downloaded from CDN and converted to data_url so the agent's
-          # vision pipeline (partition_files → resolve_vision_images) picks them up
-          # correctly. Other file types are returned with cdn_media metadata only
-          # (download-on-demand is not yet implemented for non-image types).
+          # vision pipeline (partition_files → resolve_vision_images) picks them up.
+          # Files (PDF, DOCX, etc.) are downloaded to clacky-uploads so the agent's
+          # file processing pipeline (process_path) can parse them.
+          # Voice/video are kept as cdn_media metadata only (no local download).
           #
-          # Returns Array of Hashes. Image entries include:
+          # Returns Array of Hashes. Image entries:
           #   { type: :image, name: String, mime_type: String, data_url: String }
-          # Other entries include:
-          #   { type: :file/:voice/:video, name: String, cdn_media: Hash }
+          # File entries (downloaded):
+          #   { type: :file, name: String, path: String }
+          # Voice/video entries:
+          #   { type: :voice/:video, name: String, cdn_media: Hash }
           def extract_files(item_list)
             files = []
             item_list.each do |item|
@@ -311,16 +314,46 @@ module Clacky
                   name:      "voice.amr",
                   cdn_media: v["media"]
                 }
-              when 4  # FILE
+              when 4  # FILE — download to disk so agent can parse it
                 fi = item["file_item"]
                 next unless fi
-                files << {
-                  type:      :file,
-                  name:      fi["file_name"],
-                  md5:       fi["md5"],
-                  len:       fi["len"],
-                  cdn_media: fi["media"]
-                }
+                cdn_media = fi["media"]
+                file_name = fi["file_name"].to_s
+                file_name = "attachment" if file_name.empty?
+                file_md5  = fi["md5"].to_s
+                file_len  = fi["len"].to_s
+
+                if cdn_media
+                  begin
+                    raw_bytes = @api_client.download_media(cdn_media, ApiClient::MEDIA_TYPE_FILE)
+                    saved     = Clacky::Utils::FileProcessor.save(body: raw_bytes, filename: file_name)
+                    Clacky::Logger.info("[WeixinAdapter] file downloaded to #{saved[:path]} (#{raw_bytes.bytesize} bytes)")
+                    files << {
+                      type: :file,
+                      name: saved[:name],
+                      path: saved[:path],
+                      md5:  file_md5.empty? ? nil : file_md5,
+                      len:  file_len.empty? ? nil : file_len
+                    }
+                  rescue => e
+                    Clacky::Logger.warn("[WeixinAdapter] Failed to download file #{file_name}: #{e.message}\n#{e.backtrace.first(3).join("\n")}")
+                    # Fall back to metadata-only so the agent at least knows a file was attached
+                    files << {
+                      type:      :file,
+                      name:      file_name,
+                      cdn_media: cdn_media,
+                      md5:       file_md5.empty? ? nil : file_md5,
+                      len:       file_len.empty? ? nil : file_len
+                    }
+                  end
+                else
+                  files << {
+                    type: :file,
+                    name: file_name,
+                    md5:  file_md5.empty? ? nil : file_md5,
+                    len:  file_len.empty? ? nil : file_len
+                  }
+                end
               when 5  # VIDEO
                 vi = item["video_item"]
                 next unless vi

data/lib/clacky/server/http_server.rb

@@ -9,6 +9,7 @@ require "tmpdir"
 require "uri"
 require "open3"
 require "securerandom"
+require "timeout"
 require_relative "session_registry"
 require_relative "web_ui_controller"
 require_relative "scheduler"
@@ -317,12 +318,32 @@ module Clacky
         path   = req.path
         method = req.request_method
 
-        # WebSocket upgrade
+
+
+        # WebSocket upgrade — no timeout applied (long-lived connection)
         if websocket_upgrade?(req)
           handle_websocket(req, res)
           return
         end
 
+        # Wrap all REST handlers in a timeout so a hung handler (e.g. infinite
+        # recursion in chunk parsing) returns a proper 503 instead of an empty 200.
+        timeout_sec = 10
+        Timeout.timeout(timeout_sec) do
+          _dispatch_rest(req, res)
+        end
+      rescue Timeout::Error
+        Clacky::Logger.warn("[HTTP 503] #{method} #{path} timed out after #{timeout_sec}s")
+        json_response(res, 503, { error: "Request timed out" })
+      rescue => e
+        Clacky::Logger.warn("[HTTP 500] #{e.class}: #{e.message}\n#{e.backtrace.first(5).join("\n")}")
+        json_response(res, 500, { error: e.message })
+      end
+
+      def _dispatch_rest(req, res)
+        path   = req.path
+        method = req.request_method
+
         case [method, path]
         when ["GET",    "/api/sessions"]      then api_list_sessions(req, res)
         when ["POST",   "/api/sessions"]      then api_create_session(req, res)
@@ -395,9 +416,6 @@ module Clacky
             not_found(res)
           end
         end
-      rescue => e
-        $stderr.puts "[HTTP 500] #{e.class}: #{e.message}\n#{e.backtrace.first(3).join("\n")}"
-        json_response(res, 500, { error: e.message })
       end
 
       # ── REST API ──────────────────────────────────────────────────────────────
@@ -1102,6 +1120,9 @@ module Clacky
         fields = body.transform_keys(&:to_sym).reject { |k, _| k == :platform }
         fields = fields.transform_values { |v| v.is_a?(String) ? v.strip : v }
 
+        # Record when the token was last updated so clients can detect re-login
+        fields[:token_updated_at] = Time.now.to_i if platform == :weixin && fields.key?(:token)
+
         # Validate credentials against live API before persisting.
         # Merge with existing config so partial updates (e.g. allowed_users only) still validate correctly.
         klass = Clacky::Channel::Adapters.find(platform)
@@ -1177,10 +1198,10 @@ module Clacky
           }
         when :weixin
           {
-            base_url:      raw["base_url"] || Clacky::Channel::Adapters::Weixin::ApiClient::DEFAULT_BASE_URL,
-            allowed_users: raw["allowed_users"] || [],
-            # Indicate whether a token is present (never expose the token itself)
-            has_token:     !raw["token"].to_s.strip.empty?
+            base_url:          raw["base_url"] || Clacky::Channel::Adapters::Weixin::ApiClient::DEFAULT_BASE_URL,
+            allowed_users:     raw["allowed_users"] || [],
+            has_token:         !raw["token"].to_s.strip.empty?,
+            token_updated_at:  raw["token_updated_at"]  # Unix timestamp, nil if never set
           }
         else
           {}
@@ -1624,6 +1645,7 @@ module Clacky
       # Returns a list of UI events (same format as WS events) for the frontend to render.
       def api_session_messages(session_id, req, res)
         unless @registry.ensure(session_id)
+          Clacky::Logger.warn("[messages] registry.ensure failed", session_id: session_id)
           return json_response(res, 404, { error: "Session not found" })
         end
 
@@ -1636,6 +1658,7 @@ module Clacky
         @registry.with_session(session_id) { |s| agent = s[:agent] }
 
         unless agent
+          Clacky::Logger.warn("[messages] agent is nil", session_id: session_id)
           return json_response(res, 200, { events: [], has_more: false })
         end
 
@@ -1691,7 +1714,7 @@ module Clacky
         handshake = WebSocket::Handshake::Server.new
         handshake << build_handshake_request(req)
         unless handshake.finished? && handshake.valid?
-          $stderr.puts "WebSocket handshake invalid"
+          Clacky::Logger.warn("WebSocket handshake invalid")
           return
         end
 
@@ -1730,8 +1753,8 @@ module Clacky
               end
             end
           end
-        rescue IOError, Errno::ECONNRESET, Errno::EPIPE
-          # Client disconnected
+        rescue IOError, Errno::ECONNRESET, Errno::EPIPE, Errno::EBADF
+          # Client disconnected or socket became invalid
         ensure
           on_ws_close(conn)
           socket.close rescue nil
@@ -1741,7 +1764,7 @@ module Clacky
         res.instance_variable_set(:@header, {})
         res.status = -1
       rescue => e
-        $stderr.puts "WebSocket handler error: #{e.class}: #{e.message}"
+        Clacky::Logger.error("WebSocket handler error: #{e.class}: #{e.message}")
       end
 
       # Build a raw HTTP request string from WEBrick request for WebSocket::Handshake::Server
@@ -1946,15 +1969,28 @@ module Clacky
       end
 
       # Broadcast an event to all clients subscribed to a session.
+      # Dead connections (broken pipe / closed socket) are removed automatically.
       def broadcast(session_id, event)
         clients = @ws_mutex.synchronize { (@ws_clients[session_id] || []).dup }
-        clients.each { |conn| conn.send_json(event) rescue nil }
+        dead = clients.reject { |conn| conn.send_json(event) }
+        return if dead.empty?
+
+        @ws_mutex.synchronize do
+          (@ws_clients[session_id] || []).reject! { |conn| dead.include?(conn) }
+        end
       end
 
       # Broadcast an event to every connected client (regardless of session subscription).
+      # Dead connections are removed automatically.
       def broadcast_all(event)
         clients = @ws_mutex.synchronize { @all_ws_conns.dup }
-        clients.each { |conn| conn.send_json(event) rescue nil }
+        dead = clients.reject { |conn| conn.send_json(event) }
+        return if dead.empty?
+
+        @ws_mutex.synchronize do
+          @all_ws_conns.reject! { |conn| dead.include?(conn) }
+          @ws_clients.each_value { |list| list.reject! { |conn| dead.include?(conn) } }
+        end
       end
 
       # Broadcast a session_update event to all clients so they can patch their
@@ -2163,16 +2199,29 @@ module Clacky
           @socket     = socket
           @version    = version
           @send_mutex = Mutex.new
+          @closed     = false
         end
 
+        # Returns true if the underlying socket has been detected as dead.
+        def closed?
+          @closed
+        end
+
+        # Send a JSON-serializable object over the WebSocket.
+        # Returns true on success, false if the connection is dead.
         def send_json(data)
           send_raw(:text, JSON.generate(data))
         rescue => e
-          $stderr.puts "WS send error: #{e.message}"
+          Clacky::Logger.debug("WS send error (connection dead): #{e.message}")
+          false
         end
 
+        # Send a raw WebSocket frame.
+        # Returns true on success, false on broken/closed socket.
         def send_raw(type, data)
           @send_mutex.synchronize do
+            return false if @closed
+
             outgoing = WebSocket::Frame::Outgoing::Server.new(
               version: @version,
               data: data,
@@ -2180,8 +2229,15 @@ module Clacky
             )
             @socket.write(outgoing.to_s)
           end
+          true
+        rescue Errno::EPIPE, Errno::ECONNRESET, IOError, Errno::EBADF => e
+          @closed = true
+          Clacky::Logger.debug("WS send_raw error (client disconnected): #{e.message}")
+          false
         rescue => e
-          $stderr.puts "WS send_raw error: #{e.message}"
+          @closed = true
+          Clacky::Logger.debug("WS send_raw unexpected error: #{e.message}")
+          false
         end
       end
     end

data/lib/clacky/server/server_master.rb

@@ -58,6 +58,7 @@ module Clacky
         Signal.trap("USR1") { @restart_requested  = true }
         Signal.trap("TERM") { @shutdown_requested = true }
         Signal.trap("INT")  { @shutdown_requested = true }
+        Signal.trap("HUP")  { @shutdown_requested = true }
 
         # 4. Spawn first worker
         @worker_pid = spawn_worker

data/lib/clacky/server/session_registry.rb

@@ -64,15 +64,17 @@ module Clacky
         session_data = nil
 
         @mutex.synchronize do
-          # Already fully ready — fast path.
-          return true if @sessions.key?(session_id)
-
-          # Another thread is currently restoring this session — wait for it.
+          # Another thread is currently restoring this session (including the case where
+          # @registry.create was already called but with_session agent-set is not yet done) —
+          # wait for it to finish so callers never see agent=nil.
           if @restoring[session_id]
             @restore_cond.wait(@mutex) until !@restoring[session_id]
             return @sessions.key?(session_id)
           end
 
+          # Already fully ready (not being restored) — fast path.
+          return true if @sessions.key?(session_id)
+
           return false unless @session_manager && @session_restorer
 
           session_data = @session_manager.load(session_id)
@@ -174,10 +176,13 @@ module Clacky
         # ── date filter (YYYY-MM-DD, matches created_at prefix) ──────────────
         all = all.select { |s| s[:created_at].to_s.start_with?(date) } if date
 
-        # ── name search ──────────────────────────────────────────────────────
+        # ── name / id search ─────────────────────────────────────────────────
         if q && !q.empty?
           q_down = q.downcase
-          all = all.select { |s| (s[:name] || "").downcase.include?(q_down) }
+          all = all.select { |s|
+            (s[:name] || "").downcase.include?(q_down) ||
+              (s[:session_id] || "").downcase.include?(q_down)
+          }
         end
 
         all = all.select { |s| (s[:created_at] || "") < before } if before

data/lib/clacky/server/web_ui_controller.rb

@@ -208,6 +208,14 @@ module Clacky
         forward_to_subscribers { |sub| sub.show_progress(message) }
       end
 
+      # Stream shell stdout/stderr lines to the browser while a command is running.
+      # Called periodically from the progress_timer thread in agent.rb.
+      def show_tool_stdout(lines)
+        return if lines.nil? || lines.empty?
+        emit("tool_stdout", lines: lines)
+        # Not forwarded to IM subscribers — too noisy
+      end
+
       def clear_progress
         elapsed = @progress_start_time ? (Time.now - @progress_start_time).round(1) : 0
         @progress_start_time = nil

data/lib/clacky/tools/safe_shell.rb

@@ -341,6 +341,10 @@ module Clacky
         @safe_check_command = Clacky::Utils::Encoding.safe_check(command)
 
         case @safe_check_command
+        when /pkill.*clacky|killall.*clacky|kill\s+.*\bclacky\b/i
+          raise SecurityError, "Killing the clacky server process is not allowed. To restart, use: kill -USR1 $CLACKY_MASTER_PID"
+        when /clacky\s+server/
+          raise SecurityError, "Managing the clacky server from within a session is not allowed. To restart, use: kill -USR1 $CLACKY_MASTER_PID"
         when /^rm\s+/
           replace_rm_command(command)
         when /^chmod\s+x/