feat(agentctl): Phase 663 onboarding and join-preview journeys

Add runOnboardingBranchSelectionJourney and runJoinInvitePreviewJourney
for headless smoke coverage of needsGuild and invite preview paths.

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

headless.js

@@ -1956,6 +1956,34 @@ class HeadlessSession {
     return row
   }
 
+  /** P663-41: onboarding needs-guild state after first register. */
+  async runOnboardingBranchSelectionJourney () {
+    if (!this.platform) throw new Error('headless not started')
+    await this.registerUser({ username: 'onboard_branch', displayName: 'Onboard Branch' })
+    const v = await this.refreshView()
+    if (!v.needsGuild) throw new Error('expected needsGuild after register')
+    if (!v.onboarded) throw new Error('expected onboarded')
+    return { needsGuild: true }
+  }
+
+  /** P663-42: invite preview + invalid code recovery. */
+  async runJoinInvitePreviewJourney () {
+    if (!this.platform) throw new Error('headless not started')
+    await this.registerUser({ username: 'join_preview', displayName: 'Join Preview' })
+    await this.createGuild({ name: 'Preview Host' })
+    await this.wait({ mode: 'guild' }, 45000)
+    const inv = await this.platform.createInvite()
+    const code = inv?.shareCode || inv?.code
+    if (!code) throw new Error('expected invite code')
+    const good = await this.platform.previewJoinInvite(code)
+    if (!good?.ok || !good.preview?.guildName) {
+      throw new Error('expected preview for valid invite')
+    }
+    const bad = await this.platform.previewJoinInvite('not-a-valid-code')
+    if (bad?.ok) throw new Error('expected invalid preview failure')
+    return { previewName: good.preview.guildName, badCode: bad?.code }
+  }
+
   /** P662-47: reorder staged attachments + caption/spoiler metadata. */
   async runMediaStagingReorderJourney () {
     if (!this.platform) throw new Error('headless not started')