hosts/.agents/skills/agent-tui/references/session-lifecycle.md

Session Lifecycle and Concurrency

Use this file when managing multiple sessions or debugging stuck runs.

Lifecycle Overview

1. run creates a session and returns session_id.
2. Commands without --session target the most recent session.
3. Use --session <id> when multiple sessions exist.
4. End automation sessions with kill --yes or sessions cleanup --yes.

Recommended Pattern

• Capture session_id from run JSON output.
• Pass --session <id> to every subsequent command in the flow.
• When running multiple apps concurrently, never rely on the default session.

Inspect and Attach

• sessions: list active sessions.
• sessions show <id>: show session details.
• sessions switch <id>: set the active session.
• sessions attach: attach in TTY mode (detach with Ctrl-P Ctrl-B). Use -s <id> to target a specific session.
• -s <id> sessions attach -T: stream output only (no TTY).

Cleanup and Recovery

• kill --yes: terminate the current session without prompting.
• sessions cleanup --yes: remove dead/orphaned sessions without prompting.
• sessions cleanup --all --yes: remove all sessions (including active) without prompting.

Restart Behavior

• restart: restart the current session command.
• daemon restart: restarts daemon and terminates all sessions.

Utilities

• env: show environment configuration affecting the CLI.
• version: show CLI + daemon version info.