feat(agentctl): headless role create/delete and overwrite upsert (Phase 534)

Add createGuildCustomRole, deleteGuildCustomRole, and
upsertChannelPermissionOverwrite for roles automation.

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.497 (Phase 534):** Headless helpers `createGuildCustomRole(name, opts)`, `deleteGuildCustomRole(roleId)`, and `upsertChannelPermissionOverwrite(channelId, payload)` for roles automation. Bundle: `npm run test:phase534-roles` (app repo).
+
 **v0.8.496 (Phase 533):** Headless helpers `createGuildChannel(name, opts)`, `deleteGuildChannel(channelId)`, and `reorderGuildChannels(parentId, channelIds)` for guild-admin automation. Bundle: `npm run test:phase533-guild-admin` (app repo).
 
 **v0.8.495 (Phase 532):** Headless helpers `createGuildInvite()`, `joinGuildInvite(code)`, and `revokeGuildInvite(code)` for invite automation. Bundle: `npm run test:phase532-invites` (app repo).

headless.js

@@ -619,6 +619,31 @@ class HeadlessSession {
     return this.platform.sendMessage(content, opts)
   }
 
+  async createGuildCustomRole (name, opts = {}) {
+    if (!this.platform) throw new Error('headless not started')
+    const row = await this.platform.createGuildCustomRole({
+      name,
+      color: opts.color,
+      permissions: opts.permissions
+    })
+    await this.refreshView()
+    return row
+  }
+
+  async deleteGuildCustomRole (roleId) {
+    if (!this.platform) throw new Error('headless not started')
+    const prev = await this.platform.deleteGuildCustomRole(roleId)
+    await this.refreshView()
+    return prev
+  }
+
+  async upsertChannelPermissionOverwrite (channelId, payload = {}) {
+    if (!this.platform) throw new Error('headless not started')
+    const row = await this.platform.upsertChannelPermissionOverwrite(channelId, payload)
+    await this.refreshView()
+    return row
+  }
+
   async createGuildChannel (name, opts = {}) {
     if (!this.platform) throw new Error('headless not started')
     const channel = await this.platform.createChannel({