feat(agentctl): joinFirstStage step for stage channel scenarios (v0.8.385)

Headless and attached run paths support join-stage IPC; used by
agentctl-stage-join.json in test:agentctl-phase422-voice.

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

README.md

@@ -183,10 +183,11 @@ Bundled scenarios under `apps/pearcord/scenarios/`:
 | `agentctl-voice-leave-roundtrip.json` | Join first voice channel then `leave-voice` clears occupancy (v0.8.333) |
 | `agentctl-attachment-send.json` | Fixture stage + send message with `attachmentIds` (v0.8.384) |
 | `agentctl-attachment-preview.json` | PNG stage + preview IPC event (v0.8.384) |
+| `agentctl-stage-join.json` | Create stage channel + `join-stage` (v0.8.385) |
 
 `mesh.connectGuildMeshThread(scenarioPath)` — optional `markThreadAndParentRead: true` in scenario JSON (v0.8.279). host steps + invite + `create-thread` + reply; guest must receive `threadReply` token.
 
-Scenario step extras (headless + attached `run`): `joinFirstVoice`, `openDmPeer`, `selectFirstForumChannel`, `selectSecondForumChannel`, `selectFirstTextChannel`, `selectSecondTextChannel`, `selectChannelNamed`, `selectChannelOtherThanActive`, `selectParentOfActiveThread`, `selectActiveThread`, `threadName` with `selectActiveThread`, `markActiveChannelRead`, `seedInboxNotification`, `markLatestNotificationRead`, `openLatestNotification`, `seedMentionAlertForActiveChannel`, `createThreadFromLastMessage`, `markThreadAndParentRead`, `toggleReactionOnLastMessage` (emoji string or `{ emoji }`), `stageFixtureAttachment` (`{ image: true }` for PNG), `sendMessageWithStagedAttachments`, `requestPreviewForStagedAttachment`, `messagesMin`, `messageContentIncludes`, `searchResultsMin`, `searchResultsMax`, `searchResultsCached`, `searchUnchanged`, `searchRecentIncludes`, `mentionAlertCountMax`, `notificationUnreadMin`, `notificationUnreadMax`, `reactionCountMin`, `reactionsInclude`, `attachmentsOnLastMessageMin`, `activeChannelName`, `parentChannelPermissions` on `wait`. `waitEvent` supports `payloadType` (e.g. `attachment-preview`).
+Scenario step extras (headless + attached `run`): `joinFirstVoice`, `joinFirstStage`, `openDmPeer`, `selectFirstForumChannel`, `selectSecondForumChannel`, `selectFirstTextChannel`, `selectSecondTextChannel`, `selectChannelNamed`, `selectChannelOtherThanActive`, `selectParentOfActiveThread`, `selectActiveThread`, `threadName` with `selectActiveThread`, `markActiveChannelRead`, `seedInboxNotification`, `markLatestNotificationRead`, `openLatestNotification`, `seedMentionAlertForActiveChannel`, `createThreadFromLastMessage`, `markThreadAndParentRead`, `toggleReactionOnLastMessage` (emoji string or `{ emoji }`), `stageFixtureAttachment` (`{ image: true }` for PNG), `sendMessageWithStagedAttachments`, `requestPreviewForStagedAttachment`, `messagesMin`, `messageContentIncludes`, `searchResultsMin`, `searchResultsMax`, `searchResultsCached`, `searchUnchanged`, `searchRecentIncludes`, `mentionAlertCountMax`, `notificationUnreadMin`, `notificationUnreadMax`, `reactionCountMin`, `reactionsInclude`, `attachmentsOnLastMessageMin`, `activeChannelName`, `parentChannelPermissions` on `wait`. `waitEvent` supports `payloadType` (e.g. `attachment-preview`).
 
 ## Dependencies
 

headless.js

@@ -113,6 +113,12 @@ class HeadlessSession {
         const view = await this.ipc({ type: 'join-voice', channelId: ch.id })
         results.push({ joinFirstVoice: true, channelId: ch.id, view })
       }
+      if (step.joinFirstStage) {
+        const ch = (this._lastView?.channels || []).find((c) => c.type === 'stage')
+        if (!ch) throw new Error('no stage channel in view')
+        const view = await this.ipc({ type: 'join-stage', channelId: ch.id })
+        results.push({ joinFirstStage: true, channelId: ch.id, view })
+      }
       if (step.openDmPeer) {
         const peer = step.openDmPeer
         const view = await this.ipc({

server.js

@@ -151,6 +151,13 @@ class AgentServer {
         await this.refreshView(false)
         results.push({ joinFirstVoice: true, channelId: ch.id })
       }
+      if (step.joinFirstStage) {
+        const ch = (this._lastView?.channels || []).find((c) => c.type === 'stage')
+        if (!ch) throw new Error('no stage channel in view')
+        await this.dispatchIpc({ type: 'join-stage', channelId: ch.id })
+        await this.refreshView(false)
+        results.push({ joinFirstStage: true, channelId: ch.id })
+      }
       if (step.openDmPeer) {
         const peer = step.openDmPeer
         await this.dispatchIpc({