stuck

name	stuck
description	Diagnose a frozen, slow, or stuck agent session by inspecting running processes and recent logs
when_to_use	When the agent appears frozen, is consuming excessive CPU or memory, or a tool call seems to have hung with no output.
argument-hint	optional: PID or process name to focus on
context	inline
allowed-tools	["bash","read_file"]
disable-model-invocation	true

Diagnose the stuck or slow session.

$ARGUMENTS

Step 1: List agent-related processes

ps aux | grep -E "(agentd|ai-coding|go run)" | grep -v grep

For each suspicious process, note:

• PID
• CPU% and RSS (memory)
• Elapsed time (how long it has been running)
• Process state: R (running), S (sleeping), D (uninterruptible I/O), T (stopped), Z (zombie)

Signs of a stuck session:

State	Meaning
D	Blocked on I/O — possibly waiting on a file, network, or subprocess
T	Stopped (Ctrl+Z was pressed, or SIGSTOP sent)
Z	Zombie — parent is not reaping the child
High CPU (≥90%) sustained	Infinite loop or CPU-bound operation
High RSS (≥1 GB)	Memory leak or unbounded accumulation

Step 2: Inspect child processes

For any suspicious PID from Step 1:

pstree -p <PID> 2>/dev/null || ps --ppid <PID> 2>/dev/null || echo "pstree unavailable"

This shows if the agent is waiting on a child process (git, shell command, etc.).

Step 3: Check for hung tool calls

# Look for long-running subprocesses that might be blocking a tool
ps aux --sort=etime | grep -E "(git|bash|sh)" | head -20

Step 4: Check recent log output

ls -t /tmp/ai-coding-*.log 2>/dev/null | head -1 | xargs tail -30 2>/dev/null \
  || ls -t /tmp/agentd-*.log 2>/dev/null | head -1 | xargs tail -30 2>/dev/null \
  || echo "No log file found"

Step 5: Report and recommend action

Structure the report as:

Process snapshot

Table of all agent-related processes with PID, state, CPU, memory, elapsed time.

Root cause (if found)

• What is stuck and why
• Which child process is blocking (if any)

Recommended action

• If D state: the process is waiting on I/O; check disk, network, or file locks. May resolve on its own; wait 30 s before killing.
• If T state: run kill -CONT <PID> to resume, or kill <PID> to terminate cleanly.
• If Z state: the parent must call wait(); restart the parent process.
• If high CPU: check if a bash tool command is in an infinite loop; send Ctrl+C or kill <PID>.
• If high memory: send SIGTERM (kill <PID>) for a graceful shutdown.
• If child is stuck: kill <child-PID> first, then the parent should unblock.