Extend headless agentctl with waitEvent and document Phase 295 scenarios.

HeadlessSession supports waitEvent steps and optional hyperswarm DHT; README lists leave-voice-noop and settings-deep-link scenarios with smoke commands.

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

bin/agentctl.cjs

@@ -3,7 +3,12 @@
 
 const fs = require('bare-fs')
 const path = require('bare-path')
-const { AgentClient, HeadlessSession, resolveAgentctlAddress } = require('..')
+const {
+  AgentClient,
+  HeadlessSession,
+  PearcordMeshCluster,
+  resolveAgentctlAddress
+} = require('..')
 
 function usage () {
   console.log(`pearcord-agentctl — control a running Pearcord worker or run headless IPC
@@ -17,7 +22,9 @@ Usage:
   agentctl log-tail [--lines N] [--host HOST] [--port PORT]
   agentctl run <scenario.json> [--timeout MS] [--host HOST] [--port PORT]
   agentctl headless run <scenario.json>
+  agentctl headless mesh run <scenario.json> [--peers N]
   agentctl headless ipc '<json>'
+  agentctl mesh run <scenario.json> [--peers N]
 
 Environment:
   PEARCORD_AGENTCTL=1          Enable TCP server in apps/pearcord worker
@@ -64,6 +71,20 @@ async function main () {
 
   if (cmd === 'headless') {
     const sub = args._[1]
+    if (sub === 'mesh') {
+      const meshSub = args._[2]
+      if (meshSub !== 'run') throw new Error('use: headless mesh run <scenario.json>')
+      const file = args._[3]
+      if (!file) throw new Error('scenario.json path required')
+      const cluster = new PearcordMeshCluster({ peerCount: 3 })
+      try {
+        const result = await cluster.runScenario(path.resolve(file))
+        console.log(JSON.stringify({ ok: true, result }, null, 2))
+      } finally {
+        await cluster.close()
+      }
+      return
+    }
     const session = new HeadlessSession()
     await session.start()
     try {
@@ -88,6 +109,21 @@ async function main () {
     }
   }
 
+  if (cmd === 'mesh') {
+    const meshSub = args._[1]
+    if (meshSub !== 'run') throw new Error('use: mesh run <scenario.json>')
+    const file = args._[2]
+    if (!file) throw new Error('scenario.json path required')
+    const cluster = new PearcordMeshCluster({ peerCount: 3 })
+    try {
+      const result = await cluster.runScenario(path.resolve(file))
+      console.log(JSON.stringify({ ok: true, result }, null, 2))
+    } finally {
+      await cluster.close()
+    }
+    return
+  }
+
   const client = clientFromArgs(args)
   try {
     if (cmd === 'ping') {