Recipe Investigate a Stuck Session

Recipe: Investigate a Stuck Session

Use when: a session remains active or waiting longer than expected.

Procedure

1. Record the session ID, source, provider, project, state, and newest timestamp.

2. Refresh the browser once and compare CLI evidence:

   npx ccam session <session-id>
   npx ccam agents --session <session-id>
   npx ccam events --session <session-id> --limit 50

3. Inspect child agents. A waiting parent with an active child is normally delegated work.

4. Read the latest transcript entries. Identify a user prompt, permission request, long-running tool, provider error, or clean terminal message.

5. Determine collection mode:

   • local hooks: confirm the provider process and hook delivery;
   • remote hooks: confirm HTTPS/auth and producer reachability;
   • remote source: check provider-specific sync and transcript freshness;
   • container/Windows: local process-liveness probing may be unable to answer.

6. If the provider is still working, observe rather than mutate.

7. If the provider ended but history is incomplete, rescan/import and verify reconciliation.

8. If the UI alone is stale, repair the client/WebSocket path.

Do not

• edit status directly in SQLite;
• stop all agents because one card looks old;
• lower stale thresholds globally before understanding normal workload duration;
• relaunch the same task without checking the working tree.

Done when

You can state whether the producer is alive, whether evidence is reaching CCAM, and why the displayed state is correct or stale. Record the last good and first missing event if escalating.

See Core Concepts.