| name | inspect-sessions |
| description | Inspect Synergy session metadata, health, messages, parts, inbox, indexes, lineage, and migration state without unsafe hydration or filesystem mutation. Use for corrupt or missing sessions, stuck pending replies, raw session JSON, Scope lookup, recovery, storage debugging, and session persistence investigations. |
Inspect Session State
Start with Recovery-safe Commands
Preserve the target SYNERGY_HOME and working directory so Scope resolution matches the session.
synergy session list --format json --max-count 20
synergy session list --with-health --format json
synergy session inspect <session-id> --json
session inspect reads health metadata without hydrating the message history. Supply --scope <scope-id> only when the global session index is missing.
For index problems, preview repairs before any mutation:
synergy session repair --dry-run --json
Run --apply or session delete --yes only when the user explicitly requests the state change and the inspection proves it is appropriate.
Inspect Raw Storage Read-only
Read Storage and paths and Sessions and messages before interpreting records.
Resolve the root as <SYNERGY_HOME or OS home>/.synergy/data/. Use the session index to find the owning Scope, then inspect:
session_index/<session-id>.json
sessions/<scope-id>/<session-id>/info.json
sessions/<scope-id>/<session-id>/messages/<message-id>/info.json
sessions/<scope-id>/<session-id>/messages/<message-id>/parts/<part-id>.json
Use jq, rg, find, and ls only for read-only inspection. Derive exact paths from packages/synergy/src/storage/path.ts when a collection name is uncertain; do not rely on an old directory diagram.
Reconstruct the Invariants
Check independently:
- session info readability, Scope, parent/child lineage, workflow, and
pendingReply
- root user message and assistant
rootID / parentID semantics
visible, includeInContext, message origin, and part origin- tool-call/result pairing and terminal assistant state
- inbox
mode (task, steer, or context)
- compaction anchor and continuation summary
- session indexes versus readable on-disk records
- migration log entries for the owning domain
Use MessageV2.deriveSemantics() and MessageV2.isSystemPart() when writing diagnostic code. Do not re-derive canonical semantics from retired booleans.
Protect Data
Never hand-edit a live session, copy only part of its directory tree, or delete an index to make an error disappear. Use session export/import, recovery repair, migrations, or domain APIs for changes. Stop the isolated target runtime before any raw backup; copy library.db only with a consistent SQLite backup workflow.
Redact session content, absolute paths, credentials, and IDs before sharing evidence.
Report
Return the target home/Scope, commands and records inspected, violated invariant, affected indexes or messages, repair preview, and the safest supported next action.
