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 daemon statusFor machine-readable output:
agh daemon 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 observe health -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. Resume only after the state is understood
agh session resume sess_1234If the provider reports that its original session resource no longer exists, AGH may need to classify the resume failure and fall back according to the implemented session resume rules. Read Resume and Replay before treating resume 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 daemon status and agh observe health | Web UI |
| Resume fails | agh session history and agh session repair | Resume 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 daemon status -o json
agh observe health -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.