# Upgrade Guide — NEXT

<!-- bump: patch -->

## What Changed

- **Session resumption**: Sessions killed from the dashboard or via Telegram now resume with `--resume` when a new message arrives on the same topic. Fixes path hashing (`.` → `-`), proactive UUID saving (~8s after spawn), and `telegram-forward` endpoint now calls `registerTopicSession()` so `beforeSessionKill` can look up the topic ID.
- **Dashboard session management**: Create and kill sessions directly from the dashboard UI. New `POST /sessions/create` endpoint supports headless or Telegram-linked sessions. `DELETE /sessions/:id` now also accepts tmux session names.
- **Session auto-recovery hardening**: Recovery prompts now passed through to respawned sessions so they know what went wrong. JSONL file discovery hardened (lsof-only, no unsafe fallback). Backup files auto-cleaned after 24h. JSONL truncation uses tail-scan (256KB) instead of full file reads. Recovery state persists to disk across server restarts. Unicode sanitization added for prompt injection prevention.
- **Subagent-aware zombie cleanup**: Sessions waiting on subagent results are no longer killed as zombies. Instar session IDs bridged to Claude Code session IDs via hook events. 60-minute safety cap prevents stale subagent holds.

## What to Tell Your User

Sessions now resume where they left off. When you kill a session from the dashboard and send a new Telegram message, the new session picks up the prior conversation context instead of starting fresh. Session recovery is smarter — recovered sessions now know what went wrong and how to avoid repeating the failure. Sessions running subagents are no longer incorrectly killed as zombies.

## Summary of New Capabilities

- Session resume via `--resume` flag with TopicResumeMap persistence
- Proactive UUID saving (8s after spawn, 60s heartbeat, and on kill)
- Path hashing fix for hidden directories (`.instar` → `--instar`)
- `telegram-forward` now registers topic↔session mapping in memory
- Dashboard session creation modal with Telegram topic toggle
- Session kill by tmux name (fallback from UUID lookup)
- Input validation for session names (non-empty, max 128 chars)
- Recovery prompts for stall, crash, and error loop recovery
- Tail-scan JSONL truncation (no full file reads)
- Persistent recovery state (`.instar/recovery-state.json`)
- Subagent-aware zombie cleanup with safety cap
- Session ID bridging (Instar ↔ Claude Code) via hook events
- Post-update migration for hook URL session ID injection
