feat: push-based worker-to-conductor communication in taskMaestro

[JeremyDev87]

Purpose

Current taskMaestro relies on conductor polling (capture-pane) to detect worker status. This is unreliable — multiple false positives/negatives occurred due to stale RESULT.json, spinner misclassification, and timing gaps. Workers should PUSH status to the conductor pane directly via tmux send-keys.

Background

In the 2026-03-22 session:

• Polling misclassified completed spinners as active (3 incidents)
• Stale RESULT.json from previous wave caused false-positive completion
• 5+ minutes between detection and nudge for stuck workers
• Conductor had no real-time visibility into worker progress

Push model eliminates all of these: worker reports status immediately when events occur.

Changes

• .claude/skills/taskmaestro/SKILL.md — Add push-based communication protocol to worker prompt template and conductor handling

Design

Worker→Conductor Protocol

Workers send structured messages to conductor pane (pane 0) via tmux send-keys:

# Worker completion
tmux send-keys -t "${SESSION}:${WIN}.${CONDUCTOR}" \
  "[TM:DONE] pane=${MY_PANE} issue=#813 pr=884 status=success" Enter

# Worker error (needs help)
tmux send-keys -t "${SESSION}:${WIN}.${CONDUCTOR}" \
  "[TM:ERROR] pane=${MY_PANE} issue=#813 error='yarn install failed'" Enter

# Worker needs decision
tmux send-keys -t "${SESSION}:${WIN}.${CONDUCTOR}" \
  "[TM:DECIDE] pane=${MY_PANE} issue=#813 question='2 approaches: A or B?'" Enter

# Worker progress checkpoint
tmux send-keys -t "${SESSION}:${WIN}.${CONDUCTOR}" \
  "[TM:PROGRESS] pane=${MY_PANE} issue=#813 phase=ACT step='TDD GREEN'" Enter

Message Format

[TM:<TYPE>] pane=<N> issue=<#NNN> <payload>

Type	When	Payload
DONE	Task complete, PR created	pr=<N> status=success|failure
ERROR	Unrecoverable error	error='<message>'
DECIDE	Needs conductor input	question='<question>'
PROGRESS	Phase transition	phase=PLAN|ACT|EVAL step='<desc>'

Worker Prompt Template Addition

Add to assign subcommand's worker prompt:

[TASKMAESTRO COMMUNICATION PROTOCOL]
You can communicate with the conductor (pane 0) via tmux:

CONDUCTOR_PANE=0
SESSION=$(tmux display-message -p '#{session_name}')
WIN=$(tmux display-message -p '#{window_index}')
MY_PANE=$(tmux display-message -p '#{pane_index}')

When you complete: tmux send-keys -t "$SESSION:$WIN.$CONDUCTOR_PANE" "[TM:DONE] pane=$MY_PANE issue=<issue> pr=<pr_number> status=success" Enter
When you hit an error you can't fix: tmux send-keys -t "$SESSION:$WIN.$CONDUCTOR_PANE" "[TM:ERROR] pane=$MY_PANE issue=<issue> error='<msg>'" Enter

Conductor Handling

Conductor watches for [TM:*] messages in its own input. When received:

• [TM:DONE] → update state, check if all workers done → wave transition
• [TM:ERROR] → alert user, attempt auto-recovery or nudge
• [TM:DECIDE] → present question to user, relay answer back via send-keys
• [TM:PROGRESS] → update status display

Hybrid Model (Push + Pull fallback)

Push is primary, polling is fallback for workers that crash without sending a message:

• Workers PUSH status on events (immediate)
• Conductor POLLS every 2min as safety net (catches crashed workers only)
• Polling no longer makes status judgments — just checks for dead processes

Acceptance Criteria

• Worker prompt template includes tmux push protocol
• [TM:DONE], [TM:ERROR], [TM:DECIDE], [TM:PROGRESS] message types defined
• Conductor pane receives and parses [TM:*] messages
• Polling demoted to crash-detection fallback only
• RESULT.json still written (for persistence) but not primary detection
• Works with current tmux socket/session detection
• Can be merged independently

References

• taskMaestro skill: .claude/skills/taskmaestro/SKILL.md
• Related: feat: auto-nudge stuck workers with 'continue' in taskMaestro watch mode #861 (auto-nudge), feat: improve taskMaestro watch mode status detection accuracy #864 (status detection)
• Parent: Improve taskMaestro parallel execution reliability (retrospective action items) #866 (retrospective action items)