Backend selection configuration and documentation

[geoffjay]

Context

Part of #671 (PTY execution backend epic). Blocked by: #673 (PtyBackend), #676 (xterm.js), #677 (CLI integration).

Final integration issue: wire up backend selection in the orchestrator, update configuration, and document the feature.

Problem

The orchestrator's main.rs currently selects backend via AGENTD_BACKEND env var with two options: tmux (default) and docker. This needs to support pty as a third option, with proper configuration, validation, and documentation.

Changes

1. Orchestrator Backend Selection

In crates/orchestrator/src/main.rs, extend the backend match:

let backend: Arc<dyn ExecutionBackend> = match backend_type.as_str() {
    "tmux" => Arc::new(TmuxBackend::new("agentd-orch")),
    "docker" => { /* existing docker setup */ },
    "pty" => Arc::new(PtyBackend::new("agentd-orch")),
    _ => { /* error */ }
};

2. Wrap Service Backend Selection

The standalone wrap service (crates/wrap/src/main.rs) currently only uses TmuxManager directly in its API handlers. It should also support backend selection for consistency.

3. Configuration Documentation

Document the three backends with their trade-offs:

Backend	Dependency	PTY Streaming	Health Check	Web Terminal	Use Case
tmux	tmux binary	❌	❌ (always Unknown)	❌	Default, simple, battle-tested
docker	Docker daemon	❌	✅	❌	Isolated execution, resource limits
pty	None	✅	✅	✅	Web terminal, no external deps

4. Feature Detection

Add a capability endpoint so clients can discover what the active backend supports:

GET /backend/capabilities

{
  "backend": "pty",
  "capabilities": {
    "terminal_streaming": true,
    "health_check": true,
    "resource_limits": false,
    "network_policy": false,
    "interactive": true
  }
}

The UI and CLI use this to show/hide features (e.g., Terminal tab only shown when terminal_streaming: true).

Implementation Steps

1. Add pty option to backend selection in crates/orchestrator/src/main.rs
2. Add capability detection endpoint to orchestrator API
3. Update wrap service to support backend selection
4. Update UI to check capabilities before showing Terminal tab
5. Update CLI info command to display capabilities
6. Write configuration guide

Relevant Files

• crates/orchestrator/src/main.rs — backend selection
• crates/orchestrator/src/api.rs — API routes
• crates/wrap/src/main.rs — wrap service entry point
• crates/wrap/src/api.rs — wrap API handlers
• ui/src/components/agents/AgentTerminal.tsx — capability check before render

Acceptance Criteria

• AGENTD_BACKEND=pty correctly initializes PtyBackend in orchestrator
• Capability endpoint returns accurate backend capabilities
• UI hides Terminal tab when backend doesn't support PTY streaming
• CLI shows capabilities in agent wrap info
• Configuration documented with trade-off comparison table
• Invalid backend values produce clear error messages at startup
• Integration test: orchestrator starts with each backend type

Caution

All work for this issue must branch from feature/autonomous-pipeline and PR back into it — never directly to main.