feat(agentctl): headless stage join, request, and approve helpers

Phase 525 exposes joinGuildStageChannel, requestGuildStageSpeak, and approveGuildStageSpeaker for automated stage 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.488 (Phase 525):** Headless helpers `joinGuildStageChannel`, `requestGuildStageSpeak`, `approveGuildStageSpeaker` for stage roundtrip automation. Bundle: `npm run test:phase525-stage` (app repo).
+
 **v0.8.487 (Phase 524):** Headless helpers `joinGuildVoiceChannel`, `leaveGuildVoiceChannel`, `setGuildVoiceMute` for voice roundtrip automation. Bundle: `npm run test:phase524-voice` (app repo).
 
 ## Smoke tests

headless.js

@@ -644,6 +644,21 @@ class HeadlessSession {
     return this.platform.setVoiceMute(opts)
   }
 
+  async joinGuildStageChannel (channelId) {
+    if (!this.platform) throw new Error('headless not started')
+    return this.platform.joinStageChannel(channelId)
+  }
+
+  async requestGuildStageSpeak () {
+    if (!this.platform) throw new Error('headless not started')
+    return this.platform.requestStageSpeak()
+  }
+
+  async approveGuildStageSpeaker (userId) {
+    if (!this.platform) throw new Error('headless not started')
+    return this.platform.approveStageSpeaker(userId)
+  }
+
   /**
    * @param {string|object} scenario path to JSON or object with `steps`
    */