Recovery & troubleshooting

The runtime is designed to survive terminal disconnects while keeping recovery conservative and explicit.

What survives what

ActionAgentsState

Quit dashboardkeep runningintact

Detach tmuxkeep runningintact

Rebootstopintact; marked disconnected

clishake stopstop deliberatelyintact

Start with doctor

terminal

$ clishake doctor

It checks tmux availability, adapter versions, project layout, config validity, the state database, event log, and stale agent-to-pane mappings.

Common symptoms

Agent is stuck in “starting”

The harness may be waiting on folder trust, login, or tool approval. Answer the highlighted dialog with a, A, or d, or focus the agent pane directly.

Agent is disconnected after reboot

This is expected. State survives, processes do not. Run clishake agent restart <name>.

A message failed delivery

The recipient may be stopped, still starting, or an observed sub-agent without its own terminal. Check clishake agents and resend when ready.

A worktree path already exists

clishake refuses to clobber an unregistered directory. Move it, remove it deliberately, or opt into shared mode.

Known limits

Real-harness insight is mostly process-level unless the harness exposes structured artifacts.
Third-party harness permissions are not a clishake sandbox boundary.
Automatic crash restarts require a long-running clishake dashboard.
Conflict detection is advisory; branch integration remains human-owned.
The current release is single-machine and single-project per session.