fix-stuck-session

Fix Stuck Cowork Session

Resolve the common "RPC error: process with name already running" bug that blocks Cowork sessions. Uses a tiered approach — trying the most elegant fix first, then escalating only if needed.

SOSA Supervised Gate

CRITICAL: Before ANY fix action (archiving, killing processes, clearing cache), present findings to the user and ask for explicit confirmation. Example:

| Session Name | Title | Status | Error | Proposed Action |
|-------------|-------|--------|-------|-----------------|
| busy-wizardly-mccarthy | WhatsApp reminder | idle | RPC error: already running | Archive |

"I found [N] stuck session(s). Should I proceed with the fix?"

Do NOT proceed without explicit user confirmation. This applies to ALL tiers below.

Understanding the Problem

Two root causes produce this error:

1. Orphaned State File — The session JSON at ~/Library/Application Support/Claude/ local-agent-mode-sessions/<org-id>/<user-id>/local_<uuid>.json retains isArchived: false and holds a vmProcessName, blocking new sessions.
2. Orphaned Process — A previous session crashed but its process entry was never cleaned up.

Both manifest as the same blocking error that prevents follow-up messages or session resumption.

Diagnostic & Fix Procedure

Work through these tiers in order. Stop as soon as the issue is resolved.

Tier 1: Identify the Stuck Session

Parse the error message to extract the session name and process ID if present.

Use mcp__session_info__list_sessions to cross-reference which sessions are idle but holding a process name. Report findings to the user in a table (see Supervised Gate above).

Tier 2: Archive Session State File (Fastest Fix)

macOS — Find and archive the stuck session JSON:

mdfind -onlyin ~/Library/Application\ Support/Claude "RPC error"

Then set isArchived: true:

python3 -c "
import json
path = '<session-file-path>'
with open(path) as f:
    data = json.load(f)
data['isArchived'] = True
with open(path, 'w') as f:
    json.dump(data, f, indent=2)
print('Archived: ' + data.get('processName', 'unknown'))
"