Keep the original intact
Diagnose first and write any supported repair to a new destination that cannot overwrite existing work.
Skill
Session Doctor
Understand a broken session before you repair it.
For people whose agent session will not resume. Session Doctor checks the supported transcript structure, names the ambiguity and prepares a separate repair copy when the evidence supports one, leaving the original available.
Diagnosis: one tool call has no result Original: unchanged Repair eligibility: only if pairing and order are otherwise unambiguous New copy: explicit destination, must not already exist Inserted status: interrupted; result unavailable Still to check: actual host and provider accept the repaired copy.
Fictional diagnostic outline. No real session transcript was opened or modified for this example.
See what is actually missing
Distinguish a missing tool result from malformed JSON, duplicate IDs or an unsupported event format.
Avoid invented history
A synthetic repair entry says interrupted with no result available; it never pretends an action completed.
The film
A zipper with a missing tooth.
In 70 seconds, a laptop sleeps halfway through a job and the session will not resume. Session Doctor looks before it touches anything, names the one tool call with no result, leaves the original alone and repairs a copy with a piece that tells the truth. A broken line or a repeated ID stops it for review. Captions are on the player; a transcript is below.
Read the transcript
Your agent session is a zipper. Every tool call locks onto its result.
Halfway through a job, your laptop sleeps.
Next morning, the session won’t resume. And you can’t see why.
You could paste in a result that says it worked.
Session Doctor looks before it touches anything.
It names the problem. One tool call, with no result.
It leaves the original alone, and repairs a copy.
The new piece tells the truth. Interrupted. No result available.
A broken line, or a repeated ID, and it stops for review.
Then you test the resume in your own app.
On screen: Mark the gap. Don’t fake the result.
Session Doctor. Understand a broken session before you repair it.
The session and the photo-renaming job are a fictional example. The film shows how the skill behaves; it does not report results.
See the work take shape.
Fictional diagnostic outline. No real session transcript was opened or modified for this example.
Identify the format
Record the host, transcript revision and failure class without exposing private transcript contents.
Inspect the structure
Check supported direct role/content JSONL for pairing, duplicate IDs, malformed lines and advisory ordering concerns.
Prepare a copy and verify
Repair only an unambiguous missing result into a new file, recheck it and separately test resumption in the actual host.
Fictional example
Recover an interrupted tool call
The brief Use Session Doctor to inspect a disposable direct role/content JSONL transcript. Diagnose before changing anything. If a missing tool result is unambiguous, prepare a new repair copy that marks the result unavailable, preserve the original and explain the remaining host-resume check.
Before
An interrupted tool call is “fixed” by a fabricated successful result or truncated history.
After applying the method
A new copy records the missing result as interrupted and leaves the original intact.
The repaired structure remains honest about what actually executed.
A clear job.
A useful stopping point.
A session cannot resume or provider errors suggest structural corruption.
Use it when
- A supported direct-message JSONL transcript cannot resume.
- A tool call appears to have no result after interruption.
- You need a redacted diagnosis before host-specific recovery.
Choose another route when
- Blindly rewriting an unfamiliar event envelope.
- Equating a structurally clean copy with provider acceptance.
Diagnose
A session or provider has failed.
Severity-ranked findings with supported evidence and envelope limits.
Repair
A specific repair is authorized.
A separate repaired copy and verification report.
Escalate
The format or failure remains uncertain.
A minimal redacted support bundle and next diagnostic step.
Read the canonical method
Session Doctor
Diagnose before changing session state. Identify the exact transcript format, revision, error class and provider context. Do not print private transcript contents or credentials in a support report.
For direct role/content JSONL, scripts/session_doctor.py SOURCE reads at most 16 MB and checks tool-call/result pairing, duplicate IDs, malformed lines and advisory ordering/size concerns. Unknown event envelopes are reported unsupported, not silently interpreted as healthy. Consecutive roles are an advisory because provider formats differ.
Repair: scripts/session_doctor.py SOURCE --repair-copy NEWFILE only fills missing tool results when the structure is otherwise unambiguous. It labels synthetic entries as interrupted/error with no result available, preserves the original bytes and refuses to overwrite a destination. It does not claim the tool ran. Malformed JSON, duplicate IDs and delayed real results require review. No automatic rewind or loss of history.
Verify the new copy structurally and separately test actual host/provider resumption when authorized. A clean structural report is not proof of provider acceptance. For other native event formats, use the host's documented adapter after inspecting the schema; do not feed it to the direct-message helper and pretend the formats match.
Provider diagnosis and cache identity checks use the retained optional provider-failover/telemetry modules and repository agents. A cache mismatch does not justify a force-push or broad cache deletion. Prepare an isolated cache copy and source comparison, then apply only the authorized repair. Escalation contains exact error types and redacted version/configuration evidence, not full private logs.
Limits and prerequisites
- The helper supports direct role/content JSONL only; live resume and provider acceptance are separate checks.
Your first useful run.
Work on a disposable copy first and identify the exact transcript format before requesting a repair.
The download contains the complete skill folder. Extract it into the skills directory supported by your agent, keeping its references and license together. Or use the source installer below. Python 3.11+ is required for that installer.
Start from the public source
git clone https://github.com/michaeljabbour/amplifier-skill-session-doctor.git
cd amplifier-skill-session-doctorpython3 scripts/capability.py install --dest ~/.agents/skillsKeep the complete skill folder together, including its references and license. The host applies the method in your context; the skill does not start a background service.
- Python 3.11 or later is required by the portable install/build helper. The installed method runs through your agent host.
- The portable direct-message helper is Python stdlib-only and requires no provider key.
- It reads at most the documented 16 MB limit; unsupported event envelopes are reported explicitly.
- Optional failover, cache and host adapters have separate setup and acceptance requirements.
Try this with your agent
Use Session Doctor to inspect a disposable direct role/content JSONL transcript. Diagnose before changing anything. If a missing tool result is unambiguous, prepare a new repair copy that marks the result unavailable, preserve the original and explain the remaining host-resume check.Use after installing in a host that loads skill folders. Supply your own task files and review the result.
Keep the guide nearby
Read the guide · License · Changes · Release metadata · CONSOLIDATION · ADAPTERS
Know what you can rely on.
Native and functional fixtures cover supported structure, ambiguous failures and copy-only repair. They do not establish successful resumption in every host or provider.
Read the checks and their scope
- Functional acceptance — passed
326 retained native tests and 3 substantive direct-message repair checks passed; no live provider or session resume performed.
- Native host acceptance — not-run
No live model, real desktop transaction, invitation, deployment or production data migration was performed by this functional baseline.
Source and conformance checks are separate from demonstrated benefit. Comparative effectiveness and outside-user outcomes are not established by this site.
Fictional examples explain the capability. Tests check the stated behavior. Outside-user outcomes need their own evidence.