Reconstruct a session log from a Claude Code or Grok transcript when a session crashed or was closed before `/save`.

- Claude Code: `~/.claude/projects/<slug>/<uuid>.jsonl`
- Grok: `~/.grok/sessions/<slug>/<uuid>/` (chat_history.jsonl + events + terminal/call-*.log etc.)

`/recover` distills the transcript back into a normal ClaudeTools session log (the format used by `/save`). This is the **manual, reviewed** path. The driver is auto-detected or can be forced.

---

## Usage

| Invocation | Action |
|---|---|
| `/recover <uuid>` | Reconstruct the session with that transcript uuid |
| `/recover latest` | Reconstruct the newest transcript by mtime |
| `/recover --list` | Show candidate orphans (runs the detector `--dry-run`) |

---

## Flow: `/recover --list`

Run the detector in scan-only mode and present the table to the user:

```bash
py .claude/scripts/detect_orphaned_sessions.py --dry-run
```

The table shows every past-idle, not-yet-processed transcript with its uuid, mtime, `substantive`/`saved`/`orphan` verdicts, classified scope, and the path a recovery would write to. Point the user at the rows where `orphan` is `YES` — those are unsaved substantive sessions. Nothing is written.

---

## Flow: `/recover <uuid>` or `/recover latest`

This is a **reviewed** recovery. Claude is the editor, not a passive writer.

1. **Generate the draft** (prints to stdout, writes nothing):

   ```bash
   py .claude/scripts/recover_session.py --uuid <uuid> --print
   ```

   (or `--latest`). The draft contains:
   - Ollama-drafted prose: Session Summary, Key Decisions, Problems Encountered, Pending / Incomplete Tasks.
   - Python-extracted verbatim evidence: Configuration Changes, Commands & Outputs, Reference Information, Infrastructure & Servers, Credentials & Secrets.
   - A `[RECOVERED -- UNVERIFIED]` banner and the canonical User block (from `whoami-block.sh`).

2. **Review the draft.** This is the point of the manual path:
   - Verify the **Commands / Config / Reference** appendix matches what actually happened and what the user intended. These are machine-extracted verbatim — confirm they are complete and not misleading.
   - Correct the **scope and slug**: the classifier is conservative and may land on `general` (or the wrong project/client) when work spanned several areas. Fix the target `session-logs/` directory accordingly.
   - Tighten the **topic** in the filename and the title.
   - Correct or rewrite the **Ollama prose** where it is imprecise. If Ollama was unreachable, write the prose sections yourself from the verbatim evidence.

3. **Write the final log.** Once verified, write the corrected markdown to the correct `session-logs/` path (client -> `clients/<slug>/session-logs/`, project -> `projects/<project>/session-logs/`, general -> root `session-logs/`), using the transcript's first-timestamp date: `YYYY-MM-DD-recovered-<topic>.md`. **Drop the UNVERIFIED banner** — by writing it yourself you have verified it.

4. **Sync:**

   ```bash
   bash .claude/scripts/sync.sh
   ```

5. **Unseeded wiki check.** If the scope is a client or project with no `wiki/<type>/<slug>.md` article yet, suggest:

   ```
   [INFO] No wiki article for '<slug>' yet. Run /wiki-compile <type>:<slug> to seed it.
   ```

---

## Difference from the automatic detector

| | `/recover` (this command) | `detect_orphaned_sessions.py` (background) |
|---|---|---|
| Trigger | Manual, on demand | Scheduled task (every few hours + at logon) |
| Review | Claude reviews and corrects before writing | None — auto-writes unreviewed |
| Banner | Removed once verified | Kept (`[RECOVERED -- UNVERIFIED]`) until a human reviews |
| Scope/topic | Corrected by Claude | Whatever the classifier decided |
| Output | Final, clean session log | Banner-marked draft committed for later review |

Use `/recover` when you know a specific session was lost and want a clean log. Let the detector catch the ones you forget.

---

## Notes

- `--auto` and `--json` modes on `recover_session.py` exist for the detector and for scripting; `/recover` uses `--print` so Claude always reviews before anything lands on disk.
- The prose is Ollama-drafted from the transcript; the Commands/Config/Reference sections are extracted verbatim by Python. Never trust the prose for exact commands, IPs, credentials, paths, SHAs, or ticket IDs — read those from the verbatim sections.
- Transcripts are per-machine. You can only recover sessions that ran on the machine you are on.

## Grok sessions

Grok stores richer per-session artifacts (separate chat_history, events, per-tool terminal logs with full output, summary, etc.) under `~/.grok/sessions/<slug>/<uuid>/`.

The companion script is `.claude/scripts/recover_grok_session.py`.

Current support (MVP):
- `--list`, `--latest`, `--uuid <id>` work and locate the right dir using the same slug rules Grok uses.
- Extracts terminal command logs (highest value verbatim evidence) + basic metadata.
- `--print` and `--auto` (writes under `session-logs/grok-session-....md`).

Full parity with the Claude recover (conversation reconstruction + Ollama prose for Summary/Decisions + exact file-edit extraction) is planned; the two scripts can share helpers later.

In `/recover` flows, if the chosen orphan or explicit id lives under a Grok sessions tree, the Grok script is used automatically (future enhancement to the dispatcher in recover_session.py or a thin wrapper).

Example (manual):
```bash
py .claude/scripts/recover_grok_session.py --latest --print
py .claude/scripts/recover_grok_session.py --uuid 019e8b67-f97e-7b33-9c45-ec34b342d3eb --auto
```