unstick-session

Unstick Session

Detect what's blocking a session and suggest or apply a resolution.

Arguments

$ARGUMENTS format: <session-name> [auto]

Instructions

1. Parse arguments:

   • Extract session name (required)
   • Check for auto flag

2. Capture session output:

   "$PLUGIN_DIR/bin/capture-session" "<session_name>" 40
   

3. Analyze the output and determine:

   • Is it actively working? (Look for ✢, ⏺, Thinking…)
   • Is it stuck? What type?

   Stuck types:

   Type	Signs	Fix
   yes_no	(y/n), [Y/n], Continue?	Send y or n
   multi_choice	❯ 1., numbered options	Send number
   text_input	Enter:, Type:, waiting for input	Send text or Escape
   permission	Bash command, Allow, permission dialog	Send y or n
   interactive_editor	: alone (vim), (END), --More--	:q! or q
   hanging_command	No output, no prompt	Ctrl-C
   worker_idle	❯ prompt, no task	Needs new task

4. Report findings:

   ## Session: <name>
   
   **Status:** <working/stuck>
   **Stuck Type:** <type or N/A>
   **Details:** <what you see>
   
   **Suggested Fix:** <what to do>
   

5. If auto mode and stuck:

   Execute the fix using tmux send-keys:

   # For yes_no:
   tmux send-keys -t "<session>" "y" && tmux send-keys -t "<session>" Enter
   
   # For multi_choice:
   tmux send-keys -t "<session>" "1" && tmux send-keys -t "<session>" Enter
   
   # For text_input (cancel):
   tmux send-keys -t "<session>" Escape
   
   # For permission:
   tmux send-keys -t "<session>" "y" && tmux send-keys -t "<session>" Enter
   
   # For interactive_editor (vim):
   tmux send-keys -t "<session>" Escape && tmux send-keys -l -t "<session>" ":q!" && tmux send-keys -t "<session>" Enter
   
   # For interactive_editor (pager):
   tmux send-keys -t "<session>" "q"
   
   # For hanging_command:
   tmux send-keys -t "<session>" C-c
   

   Then re-capture and verify the fix worked.

Example

/session-tools:unstick-session ai-worker-001

## Session: ai-worker-001

**Status:** stuck
**Stuck Type:** permission
**Details:** Waiting for approval: "Bash command: npm install"

**Suggested Fix:** Send 'y' Enter to approve, or 'n' Enter to deny