Debug a Failed or Stuck Session
Diagnose AGH sessions by checking daemon health, session status, event history, repair output, and stored runtime files.
- Audience
- Operators running durable agent work
- Focus
- Guides guidance shaped for scanability, day-two clarity, and operator context.
This guide gets you from "the session is not behaving" to evidence you can act on. It starts with runtime health, then narrows to one session and its durable event trail.
1. Confirm the daemon is reachable
agh statusFor machine-readable output:
agh status -o jsonWhat happened: AGH checked the background daemon through the local runtime control path. If this fails, debug the daemon before debugging the session.
Useful follow-up pages:
2. Check global runtime health
agh doctor -o jsonLook for unhealthy subsystems before focusing on the agent process. Memory indexing, event storage, or daemon connectivity problems can make a session look broken even when the provider process is not the root cause.
3. Inspect the session status
agh session status sess_1234 -o jsonCheck:
- session state
- agent name and workspace
- stop reason
- current prompt state
- created and updated timestamps
What happened: the daemon returned the current session record, not a reconstructed transcript. Use this to learn what AGH thinks the session is doing right now.
4. Read the durable event stream
agh session events sess_1234Follow live events when the session is still active:
agh session events sess_1234 --followWhat happened: AGH read the append-only session event database. This is the best evidence for prompt submission, permission requests, provider messages, tool calls, errors, and stop behavior.
5. Reconstruct the conversation history
agh session history sess_1234Use history when you need to understand the user-visible turn sequence. Use events when you need operational detail.
6. Run repair when the transcript is interrupted
agh session repair sess_1234What happened: AGH inspected the session transcript and reported whether it can repair interrupted state. Repair is for damaged or interrupted transcript state, not a substitute for daemon health checks.
7. Attach or recap only after the state is understood
agh session recap sess_1234
agh session resume sess_1234agh session resume attaches to an eligible live session. If the session is terminal or not
attachable, inspect the deterministic recap, history, and repair output before starting new work.
Read Resume Attach and Replay before treating attach refusal as a
data-loss problem.
Common symptoms
| Symptom | First check | Then read |
|---|---|---|
agh session prompt hangs | agh session events --follow | Event Streaming |
| Session is stopped unexpectedly | agh session status -o json | Session Lifecycle |
| Web UI is stale | agh status and agh doctor | Web UI |
| Attach is refused | agh session list --resumable and agh session recap | Resume Attach and Replay |
| Agent cannot see project context | agh workspace info <name> | Workspace Resolver |
| Memory is missing | agh memory health -o json | Memory System |
Evidence to collect before filing a bug
Collect output from:
agh status -o json
agh doctor -o json
agh session status sess_1234 -o json
agh session events sess_1234
agh session history sess_1234Do not include raw secrets, provider API keys, OAuth tokens, or claim tokens in bug reports. AGH redacts sensitive runtime fields, but copied terminal context may still include local environment details.
Next steps
- Use Choose the Right Operator Surface when you need the best surface for scripts, agents, or browser integrations.
- Use Database Operations when event or catalog storage is the likely problem.
- Use Troubleshooting for daemon, socket, agent, and database failure paths.