feat: add local clipboard watching with automatic sync + TUI visibility

Add opt-in clipboard watching (`[watch] enabled = true`) so the daemon
automatically detects meaningful local clipboard changes (especially
screenshots) and makes them immediately available to remote hosts.

- Intelligent hybrid polling + debounce/filtering (prioritizes images,
  ignores rapid tiny text changes)
- Updates internal state + watchHub notifications for proactive delivery
- `pastelocal-remote --watch` now benefits from real-time change notifications
- TUI dashboard shows watch status (enabled + last change time)
- Added `--watch` mode documentation and clear logging
- Added focused tests + fixed all review feedback (TUI render, reload enable,
  data race via atomic.Bool, graceful shutdown, etc.)

This makes the remote clipboard experience feel much more native for
agentic coding workflows over SSH. The feature is fully opt-in and
respects the existing security model.

Co-authored-by: Grok Build <grok@x.ai>

Author: morganlinton

cmd/pastelocal-remote/main.go

@@ -258,7 +258,9 @@ func runSend(client *http.Client, baseURL, token, filePath, format string) int {
 	return 0
 }
 
-// runWatch connects to the WebSocket endpoint and prints notifications.
+// runWatch connects to the WebSocket /clipboard/watch endpoint (or falls back to polling)
+// and prints notifications. With daemon clipboard watching enabled, changes are
+// pushed proactively when the local OS clipboard changes (screenshots etc).
 func runWatch(baseURL, token string) int {
 	// For WebSocket, we need to use a WebSocket client.
 	// Convert http:// to ws://.

internal/config/config.go

@@ -41,6 +41,7 @@ type Config struct {
 	Redaction          RedactionConfig `toml:"redaction"`
 	Processors         ProcessorConfig `toml:"processors"`
 	Relay              RelayConfig     `toml:"relay"`
+	Watch              WatchConfig     `toml:"watch"`
 }
 
 type MacOSConfig struct {
@@ -52,13 +53,13 @@ type LinuxConfig struct {
 }
 
 type Host struct {
-	AddedAt     time.Time   `toml:"added_at"`
-	RemotePort  int         `toml:"remote_port"`
-	RemoteUser  string      `toml:"remote_user"`
-	RemotePath  string      `toml:"remote_path"`
-	Termius     bool        `toml:"termius"`
-	Permissions []string    `toml:"permissions"` // "read", "write"
-	TokenHash   string      `toml:"token_hash"`  // SHA-256 of per-host token
+	AddedAt     time.Time `toml:"added_at"`
+	RemotePort  int       `toml:"remote_port"`
+	RemoteUser  string    `toml:"remote_user"`
+	RemotePath  string    `toml:"remote_path"`
+	Termius     bool      `toml:"termius"`
+	Permissions []string  `toml:"permissions"` // "read", "write"
+	TokenHash   string    `toml:"token_hash"`  // SHA-256 of per-host token
 }
 
 // HistoryConfig controls the clipboard history ring buffer.
@@ -77,16 +78,16 @@ type RedactionConfig struct {
 // RedactionRule defines a single content redaction rule.
 type RedactionRule struct {
 	Name        string `toml:"name"`
-	Pattern     string `toml:"pattern"`      // regex pattern
-	Action      string `toml:"action"`        // "redact" or "block"
+	Pattern     string `toml:"pattern"` // regex pattern
+	Action      string `toml:"action"`  // "redact" or "block"
 	Description string `toml:"description"`
 }
 
 // ProcessorConfig controls the clipboard processor pipeline.
 type ProcessorConfig struct {
-	Enabled    bool              `toml:"enabled"`
-	Timeout    int               `toml:"timeout_seconds"`
-	Chain      []ProcessorEntry  `toml:"chain"`
+	Enabled bool             `toml:"enabled"`
+	Timeout int              `toml:"timeout_seconds"`
+	Chain   []ProcessorEntry `toml:"chain"`
 }
 
 // ProcessorEntry represents a single processor in the pipeline.
@@ -97,13 +98,22 @@ type ProcessorEntry struct {
 
 // RelayConfig controls the E2E encrypted relay for multi-device sync.
 type RelayConfig struct {
-	Enabled      bool   `toml:"enabled"`
-	RelayURL     string `toml:"relay_url"`
-	DeviceID     string `toml:"device_id"`
+	Enabled       bool   `toml:"enabled"`
+	RelayURL      string `toml:"relay_url"`
+	DeviceID      string `toml:"device_id"`
 	DeviceKeyPath string `toml:"device_key_path"`
 	AuthTokenPath string `toml:"auth_token_path"`
-	AutoUpload   bool   `toml:"auto_upload"`
-	UploadTTL    int    `toml:"upload_ttl"` // seconds
+	AutoUpload    bool   `toml:"auto_upload"`
+	UploadTTL     int    `toml:"upload_ttl"` // seconds
+}
+
+// WatchConfig controls the optional local clipboard watcher in the daemon.
+// When enabled (opt-in), the daemon automatically detects meaningful
+// OS clipboard changes (screenshots, substantial text) using polling with
+// debouncing and filtering. Detected changes update internal state and
+// notify active /clipboard/watch subscribers.
+type WatchConfig struct {
+	Enabled bool `toml:"enabled"`
 }
 
 // mu protects file operations during Save to prevent concurrent writes.
@@ -135,14 +145,15 @@ func Default() *Config {
 			Timeout: 5,
 		},
 		Relay: RelayConfig{
-			Enabled:      false,
-			RelayURL:     "http://localhost:7332",
-			DeviceID:     "",
+			Enabled:       false,
+			RelayURL:      "http://localhost:7332",
+			DeviceID:      "",
 			DeviceKeyPath: "~/.config/pastelocal/device-key",
 			AuthTokenPath: "~/.config/pastelocal/relay-token",
-			AutoUpload:   false,
-			UploadTTL:    300,
+			AutoUpload:    false,
+			UploadTTL:     300,
 		},
+		Watch: WatchConfig{Enabled: false},
 	}
 }
 

internal/config/config_test.go

@@ -185,7 +185,7 @@ func TestSaveLoadRoundTrip(t *testing.T) {
 	original.Hosts = map[string]Host{
 		"server1": {
 			AddedAt:    time.Date(2024, 6, 15, 12, 0, 0, 0, time.UTC),
-			RemotePort:  22,
+			RemotePort: 22,
 			RemoteUser: "admin",
 			RemotePath: "/opt/app",
 			Termius:    false,
@@ -480,21 +480,21 @@ func TestMultipleHostsAddRemove(t *testing.T) {
 	hosts := map[string]Host{
 		"server1": {
 			AddedAt:    time.Date(2024, 1, 1, 0, 0, 0, 0, time.UTC),
-			RemotePort:  22,
+			RemotePort: 22,
 			RemoteUser: "admin",
 			RemotePath: "/opt/app",
 			Termius:    true,
 		},
 		"server2": {
 			AddedAt:    time.Date(2024, 2, 1, 0, 0, 0, 0, time.UTC),
-			RemotePort:  2222,
+			RemotePort: 2222,
 			RemoteUser: "deploy",
 			RemotePath: "/home/deploy",
 			Termius:    false,
 		},
 		"server3": {
 			AddedAt:    time.Date(2024, 3, 1, 0, 0, 0, 0, time.UTC),
-			RemotePort:  22,
+			RemotePort: 22,
 			RemoteUser: "root",
 			RemotePath: "/root",
 			Termius:    false,
@@ -583,8 +583,8 @@ func TestMergeDefaultsAllZero(t *testing.T) {
 
 func TestMergeDefaultsPartialOverride(t *testing.T) {
 	cfg := &Config{
-		Port:    8080,
-		Hosts:   map[string]Host{"existing": {}},
+		Port:  8080,
+		Hosts: map[string]Host{"existing": {}},
 	}
 
 	mergeDefaults(cfg)
@@ -831,14 +831,14 @@ func TestSaveAndReloadWithHosts(t *testing.T) {
 	cfg.Port = 8080
 	cfg.AddHost("host1", Host{
 		AddedAt:    time.Date(2024, 1, 15, 10, 30, 0, 0, time.UTC),
-		RemotePort:  22,
+		RemotePort: 22,
 		RemoteUser: "admin",
 		RemotePath: "/opt",
 		Termius:    true,
 	})
 	cfg.AddHost("host2", Host{
 		AddedAt:    time.Date(2024, 6, 1, 0, 0, 0, 0, time.UTC),
-		RemotePort:  2222,
+		RemotePort: 2222,
 		RemoteUser: "deploy",
 		RemotePath: "/home/deploy",
 		Termius:    false,
@@ -868,3 +868,29 @@ func TestSaveAndReloadWithHosts(t *testing.T) {
 		t.Error("host1.Termius = false, want true")
 	}
 }
+
+func TestWatchConfig(t *testing.T) {
+	// Default should be disabled (opt-in)
+	cfg := Default()
+	if cfg.Watch.Enabled {
+		t.Error("Watch.Enabled should default to false")
+	}
+
+	// Load from TOML with [watch] section
+	dir := t.TempDir()
+	path := filepath.Join(dir, "cfg.toml")
+	tomlContent := `port = 7331
+[watch]
+enabled = true
+`
+	if err := os.WriteFile(path, []byte(tomlContent), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	loaded, err := Load(path)
+	if err != nil {
+		t.Fatalf("load: %v", err)
+	}
+	if !loaded.Watch.Enabled {
+		t.Error("Watch.Enabled should be true when set in config")
+	}
+}

internal/proto/types.go

@@ -6,19 +6,19 @@ const ProtocolVersion = 2
 // ClipboardResponse is the JSON response for GET /clipboard on success.
 type ClipboardResponse struct {
 	OK         bool   `json:"ok"`
-	Image      string `json:"image,omitempty"`       // base64-encoded image (png/jpeg/etc)
-	Text       string `json:"text,omitempty"`         // plain text content (when format is text)
-	Format     string `json:"format"`                 // "png", "text", "html"
+	Image      string `json:"image,omitempty"` // base64-encoded image (png/jpeg/etc)
+	Text       string `json:"text,omitempty"`  // plain text content (when format is text)
+	Format     string `json:"format"`          // "png", "text", "html"
 	ByteCount  int64  `json:"byte_count"`
-	CapturedAt string `json:"captured_at"`            // RFC3339
-	ID         string `json:"id,omitempty"`            // unique ID for history entries
+	CapturedAt string `json:"captured_at"`  // RFC3339
+	ID         string `json:"id,omitempty"` // unique ID for history entries
 }
 
 // ClipboardWriteRequest is the JSON request for POST /clipboard.
 type ClipboardWriteRequest struct {
-	Format string `json:"format"`           // "png" or "text"
-	Image  string `json:"image,omitempty"`  // base64-encoded image (when format is png)
-	Text   string `json:"text,omitempty"`   // plain text (when format is text)
+	Format string `json:"format"`          // "png" or "text"
+	Image  string `json:"image,omitempty"` // base64-encoded image (when format is png)
+	Text   string `json:"text,omitempty"`  // plain text (when format is text)
 }
 
 // ClipboardWriteResponse is the JSON response for POST /clipboard on success.
@@ -41,6 +41,9 @@ type VersionResponse struct {
 	OK              bool   `json:"ok"`
 	ProtocolVersion int    `json:"protocol_version"`
 	BinaryVersion   string `json:"binary_version"`
+	// Watch-related status (populated by daemon when clipboard watching is enabled).
+	WatchEnabled        bool   `json:"watch_enabled"`
+	LastClipboardChange string `json:"last_clipboard_change,omitempty"`
 }
 
 // HealthResponse is the JSON response for GET /health.
@@ -59,13 +62,13 @@ type HistoryEntry struct {
 
 // HistoryResponse is the JSON response for GET /clipboard/history.
 type HistoryResponse struct {
-	OK     bool            `json:"ok"`
-	Items  []HistoryEntry  `json:"items"`
+	OK    bool           `json:"ok"`
+	Items []HistoryEntry `json:"items"`
 }
 
 // WatchNotification is the JSON payload pushed over the WebSocket.
 type WatchNotification struct {
-	Event      string `json:"event"`       // "clipboard_changed"
+	Event      string `json:"event"` // "clipboard_changed"
 	CapturedAt string `json:"captured_at"`
 	Format     string `json:"format"`
 	ID         string `json:"id,omitempty"`
@@ -91,7 +94,7 @@ type SnippetListResponse struct {
 // SnippetSaveRequest is the JSON request for POST /snippets.
 type SnippetSaveRequest struct {
 	Name        string `json:"name"`
-	Format      string `json:"format"`      // "text" or "png"
+	Format      string `json:"format"` // "text" or "png"
 	Text        string `json:"text,omitempty"`
 	Image       string `json:"image,omitempty"` // base64
 	Description string `json:"description,omitempty"`

internal/server/handlers.go

@@ -172,7 +172,7 @@ func (s *Server) handleClipboardGet(w http.ResponseWriter, r *http.Request) {
 			Event:     "clipboard_read",
 			ImageHash: fmt.Sprintf("%x", hash),
 			ByteCount: int64(len(content.Data)),
-			SourceIP:   remoteIP,
+			SourceIP:  remoteIP,
 			Auth:      token,
 		}
 		if err := WriteAudit(s.cfg.AuditLog, entry); err != nil {
@@ -334,7 +334,7 @@ func (s *Server) handleClipboardPost(w http.ResponseWriter, r *http.Request) {
 			Event:     "clipboard_write",
 			ImageHash: fmt.Sprintf("%x", hash),
 			ByteCount: int64(len(content.Data)),
-			SourceIP:   remoteIP,
+			SourceIP:  remoteIP,
 			Auth:      token,
 		}
 		if err := WriteAudit(s.cfg.AuditLog, entry); err != nil {
@@ -440,6 +440,13 @@ func (s *Server) handleVersion(w http.ResponseWriter, r *http.Request) {
 		ProtocolVersion: proto.ProtocolVersion,
 		BinaryVersion:   BinaryVersion,
 	}
+	// Populate optional watch status (available even without auth, for local TUI/dashboard).
+	if enabled, t := s.WatchStatus(); enabled || !t.IsZero() {
+		resp.WatchEnabled = enabled
+		if enabled && !t.IsZero() {
+			resp.LastClipboardChange = t.Format(time.RFC3339)
+		}
+	}
 	w.Header().Set("Content-Type", "application/json")
 	json.NewEncoder(w).Encode(resp)
 }

internal/server/history.go

@@ -28,11 +28,11 @@ type historyEntry struct {
 // clipboard reads. Data is encrypted at rest using AES-GCM with a
 // key derived from the auth token.
 type HistoryBuffer struct {
-	mu     sync.Mutex
+	mu      sync.Mutex
 	entries []*historyEntry
-	size   int
-	ttl    time.Duration
-	key    []byte // AES key derived from token
+	size    int
+	ttl     time.Duration
+	key     []byte // AES key derived from token
 }
 
 // NewHistoryBuffer creates a new HistoryBuffer with the given capacity and TTL.

internal/server/processor.go

@@ -7,8 +7,8 @@ import (
 	"os/exec"
 	"time"
 
-	"github.com/pastelocal/pastelocal/internal/config"
 	"github.com/pastelocal/pastelocal/internal/clipboard"
+	"github.com/pastelocal/pastelocal/internal/config"
 	cliperr "github.com/pastelocal/pastelocal/internal/errors"
 )
 

internal/server/redaction.go

@@ -14,10 +14,10 @@ type RedactionEngine struct {
 }
 
 type compiledRule struct {
-	name    string
-	action  string // "redact" or "block"
-	re      *regexp.Regexp
-	desc    string
+	name   string
+	action string // "redact" or "block"
+	re     *regexp.Regexp
+	desc   string
 }
 
 // NewRedactionEngine creates a new engine from the config.