Headless Orchestrator Friction Report - Reading Worker DM Replies

[khaliqgant]

Test Environment

• Model: minimax-m2.5-free
• Harness: opencode (CLI)
• Relay version: 6.0.21
• Skill version: 1.0.5 (@agent-relay/running-headless-orchestrator)

Executive Summary

Successfully spawned and communicated with both codex and claude workers. Core loop works: send task → worker executes → files created. However, reading worker replies via CLI is confusing and unclear.

Test Transcript

Spawning Workers

$ agent-relay spawn Worker1 codex "Create a simple Python file called hello.py that prints 'Hello from codex'"
Spawned agent: Worker1 (pid: 11192)

$ agent-relay spawn Worker2 claude "Create a simple Python file called greet.py that prints 'Hello from claude'"
Spawned agent: Worker2 (pid: 11837)

Sending Tasks

$ agent-relay send Worker3 "Add a comment to your file saying 'Modified by orchestrator'"
Message sent to Worker3

$ agent-relay send Worker2 "Please create a new file called message.txt with the text 'Hello from worker2'"
Message sent to Worker2

$ agent-relay send Worker2 "Create a file called result.json with contents: {\"status\": \"success\", \"worker\": \"claude\"}"
Message sent to Worker2

Attempting to Read Replies - THE FRICTION

$ agent-relay inbox --agent Worker2
Unread Channels:
  #general: 2

Unread DMs:
  relay: 1

Problem: inbox shows count only (1), NOT the actual message content.

$ agent-relay history --to Worker2
DM conversations for Worker2:
  relay: "Create a file called result.json with contents: {"status"..." [3 unread]

Problem: history shows truncated preview. Can't see full worker reply.

$ agent-relay inbox --agent Worker2 --json | jq '.unread_dms'
[
  {
    "from": "relay",
    "unread_count": 2,
    "last_message": {
      "text": "Create a file called result.json..."
    }
  }
]

Problem: JSON also shows "from: relay" which is MY message to the worker, not the worker's reply.

What DID Work - Workers Completed Tasks

Files were created correctly:

• hello.py - print("Hello from codex")
• greet.py - print('Hello from claude')
• message.txt - "Hello from wor..."
• result.json - {"status": "success", "worker": "claude"}

Channel shows status:

$ agent-relay history --to '#general'
[2026-05-15T15:31:32.000Z] Worker3 -> #general: Done. Created `test.py`...
[2026-05-15T15:25:47.000Z] Worker2 -> #general: Completed broker task... created `greet.py`...

Friction Points

1. Cannot read full DM content from workers

• inbox --agent shows count only
• history --to <worker> shows truncated preview
• JSON output also shows "relay" (the sender) not the worker's reply

2. Workers use inconsistent communication channels

• Initial spawn task: uses some internal mechanism (works)
• Completion status: posts to #general channel (visible)
• Detailed responses: via DM (but can't read full content)

3. First codex worker didn't appear in who initially

• Spawn succeeded, work was done, but status not visible in who
• May be a timing issue with codex specifically

4. Skill guidance gap

• Skill says "Workers will send DONE when complete" but doesn't explain HOW to detect that
• No documentation on how to actually read DM content
• Confusion between channel messages (visible) vs DM (hard to read)

Recommendations

1. Fix inbox to show message content - Currently shows only counts
2. Fix history --to <worker> to show full messages - Currently truncated
3. Clarify channel vs DM semantics - Workers report to channel but respond via DM
4. Add "task completion detection" guidance - How to know when work is done

Skill Improvements Made

During testing, I improved the skill to address:

• Added "Valid CLI Options" section (claude, codex, code)
• Added "Handling Log Output" section (ANSI filtering)
• Added "Editing This Skill" section

But the communication friction (reading worker replies) requires a fix in relay itself, not just documentation.