feat(agentctl): headless stageGuildAttachment and send with attachments (Phase 522)

Expose stageGuildAttachment and sendGuildMessageWithAttachments on
HeadlessSession for autonomous attachment verification.

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

README.md

@@ -17,6 +17,8 @@ Both modes use **`pearcord-ui-flow` `dispatchUiMessage`** — the same handler a
 
 `AgentClient` resolves RPC replies before treating `{ event: "state" | "sidecar" }` push lines as events (fixes `wait-event` responses that include an `event` field).
 
+**v0.8.485 (Phase 522):** Headless `stageGuildAttachment(opts)` and `sendGuildMessageWithAttachments(content, attachmentIds, opts)` for attachment automation. Bundle: `npm run test:agentctl-phase522-attachments` (app repo; chains `test:attachments` + `test:agentctl-phase481-attachments`).
+
 **v0.8.484 (Phase 521):** Headless `toggleGuildReaction(messageId, emoji)` for reaction automation. Bundle: `npm run test:agentctl-phase521-reactions` (app repo; chains `test:reactions` + `test:agentctl-reaction-toggle`).
 
 **v0.8.483 (Phase 520):** Headless `sendGuildMessage(content, opts)`, `editGuildMessage(messageId, content)`, and `deleteGuildMessage(messageId)` for messaging automation. Bundle: `npm run test:agentctl-phase520-messaging` (app repo; chains `test:agentctl-phase482-messaging`).

headless.js

@@ -607,6 +607,16 @@ class HeadlessSession {
     return this.platform.toggleReaction(messageId, emoji)
   }
 
+  async stageGuildAttachment (opts) {
+    if (!this.platform) throw new Error('headless not started')
+    return this.platform.stageAttachment(opts)
+  }
+
+  async sendGuildMessageWithAttachments (content, attachmentIds, opts = {}) {
+    if (!this.platform) throw new Error('headless not started')
+    return this.platform.sendMessage(content, { ...opts, attachmentIds })
+  }
+
   /**
    * @param {string|object} scenario path to JSON or object with `steps`
    */