feat(agentctl): headless voice join, leave, and mute helpers

Phase 524 exposes joinGuildVoiceChannel, leaveGuildVoiceChannel, and setGuildVoiceMute for automated voice roundtrip smokes.

Co-authored-by: Cursor <[email protected]>

README.md

@@ -124,6 +124,8 @@ See [docs/AGENTCTL.md](../../docs/AGENTCTL.md) for full reference, security note
 - Optional `PEARCORD_AGENTCTL_TOKEN` shared secret; still localhost-only.
 - Can execute any UI IPC type (moderation, guild admin, etc.) — same power as the logged-in user session.
 
+**v0.8.487 (Phase 524):** Headless helpers `joinGuildVoiceChannel`, `leaveGuildVoiceChannel`, `setGuildVoiceMute` for voice roundtrip automation. Bundle: `npm run test:phase524-voice` (app repo).
+
 ## Smoke tests
 
 ```bash

headless.js

@@ -628,6 +628,22 @@ class HeadlessSession {
     return this.platform.embeds.resolveForContent(content)
   }
 
+  async joinGuildVoiceChannel (channelId, opts = {}) {
+    if (!this.platform) throw new Error('headless not started')
+    if (opts.listenOnly) return this.platform.joinVoiceListenOnly(channelId)
+    return this.platform.joinVoiceChannel(channelId, opts)
+  }
+
+  async leaveGuildVoiceChannel () {
+    if (!this.platform) throw new Error('headless not started')
+    return this.platform.leaveVoiceChannel()
+  }
+
+  async setGuildVoiceMute (opts = {}) {
+    if (!this.platform) throw new Error('headless not started')
+    return this.platform.setVoiceMute(opts)
+  }
+
   /**
    * @param {string|object} scenario path to JSON or object with `steps`
    */