session-crash-repair

Detect and repair inconsistent LangGraph checkpoints in Synapse sessions after abnormal process exits.

7|2|Updated Jul 21, 2026
One-click install
npx skills add https://github.com/alex8224/synapse-agent --skill session-crash-repair-alex8224
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: session-crash-repair
Source: https://github.com/alex8224/synapse-agent/tree/main/skills/session-crash-repair
Command: npx skills add https://github.com/alex8224/synapse-agent --skill session-crash-repair-alex8224

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill requires langgraph.

What problem does it solve? When a Synapse agent process crashes or is force-killed mid-turn, the session's LangGraph checkpoint can be left in an inconsistent state: dangling tool calls without results, pending graph tasks that re-execute dangerous commands on resume, and a stale transcript projection. This Skill provides a safe procedure to detect that corruption and repair the session so it can be continued cleanly. ## Core Features & Use Cases - Read-only detection: Inspect the head checkpoint of a thread via SqliteSaver to find pending pregel tasks, dangling tool calls, and non-empty graph state without invoking the model. - Checkpoint repair: Seal dangling tool calls with cancellation ToolMessages using repair_thread_after_cancel, then clear residual middleware pending tasks with an END-node state update. - Transcript rebuild: Regenerate the derived transcript.sqlite projection from the repaired checkpoint so the TUI shows the full history. - Use Case: A user reports that reopening a session causes the agent to immediately execute an unrelated kill command. Use this Skill to detect the pending Send(node='tools') task, seal the dangling call with a crash-reason boundary, and rebuild the transcript before continuing. ## Quick Start Ask the agent to run the read-only detection script against the thread's checkpoints.sqlite file to confirm dangling tool calls, then execute the repair and transcript-rebuild scripts and verify the checklist.

Frequently Asked Questions about session-crash-repair

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I fix a Synapse session that broke after a crash?

Run the read-only detection script against the thread's checkpoints.sqlite to confirm dangling tool calls or pending pregel tasks, then run the repair script using repair_thread_after_cancel with reason="crash" and rebuild the transcript projection from the new head checkpoint.

How do I detect dangling tool calls in a LangGraph checkpoint?

Load the head checkpoint with SqliteSaver and compare each AIMessage tool_call id against the set of ToolMessage tool_call_ids. Any tool call without a matching ToolMessage is dangling, and a non-empty __pregel_tasks channel value also indicates corruption.

Why does my agent execute an old command when I reopen a session?

The checkpoint contains a pending Send(node='tools') task from before the crash, and resuming the graph executes it. Never invoke the thread directly; repair the checkpoint first so pending tasks are sealed and cleared.

Does repairing a checkpoint delete my session history?

No. The checkpoint store is append-only and immutable, so repair only adds a new head checkpoint without modifying history. If something goes wrong, you can roll back by deleting the newly added checkpoint rows.

Why is the transcript still outdated after fixing the checkpoint?

transcript.sqlite is a derived cache whose contains_thread() check only tests existence, so it never invalidates on checkpoint changes. You must manually rebuild it with TranscriptProjection.replace_from_messages using the new head checkpoint id.