feat: `meshd watch` — persistent event stream for agent workflows

[gitcoder89431]

Summary

Add meshd watch as a persistent, human-readable event stream for terminal monitoring and agent consumption. The killer feature for multi-machine agent workflows.

Motivation

Claude Code running on machine A has no way to confirm a file it wrote has actually propagated to machine B before it proceeds. meshd watch closes this gap by providing a blocking, streamable event feed that agents (and humans) can subscribe to.

Proposed Behavior

# Human-readable stream (default)
meshd watch
# 12:03:01  ↑ synced    notes.md          → MacBook
# 12:03:02  ● connected  Phone              relay
# 12:03:04  ⚠ conflict   photo.jpg          MacBook vs Phone
# 12:03:09  ↓ received  projects/main.go   ← MacBook

# JSON stream (for agents / scripts)
meshd watch --json
# {"time":"12:03:01","event":"synced","file":"notes.md","device":"MacBook","direction":"out"}

# Filter to specific events
meshd watch --filter synced,conflict

# Wait for a specific file to sync and exit
meshd watch --until 'notes.md synced'

The Agent-Native Use Case

# In a Claude Code agent workflow:
echo "updated" > ~/meshd/trigger.txt
meshd watch --until 'trigger.txt synced' --timeout 30s
# exits 0 when confirmed synced to all online peers, 1 on timeout
# agents can now safely proceed knowing remote machine has the file

MCP Tool Addition

Add wait_for_sync tool to the MCP server:

{"tool": "wait_for_sync", "file": "trigger.txt", "timeout_seconds": 30}
// blocks until file confirmed synced to all online peers, returns device list

Implementation Notes

• Built on /rest/events?since=<n> long-poll (same as TUI)
• --until uses FolderCompletion events with completion: 100 for the target file's folder
• Event types to expose: StateChanged, DeviceConnected, DeviceDisconnected, FolderCompletion, LocalChangeDetected, RemoteChangeDetected, ItemFinished
• SIGTERM / ctrl+c exits cleanly with code 0

Related

• --watch flag for status JSON feat: --watch flag for meshd status --json (live streaming JSON) #1

[gitcoder89431]

Shipped in v0.4.0: meshd watch streams events, meshd watch --until idle blocks until synced, --json for agent workflows.