# Upgrade Guide — v0.24.31

<!-- bump: patch -->

## What Changed

**Autonomous mode structural enforcement fix.** The `/autonomous` skill's stop hook — the mechanism that prevents Claude from exiting and forces it to keep working through the task list — was never being deployed or registered for agents.

The skill.md and setup script were installed correctly, but the `hooks/` directory (containing `autonomous-stop-hook.sh` and `hooks.json`) was missing, and the hook was never registered in `.claude/settings.json`. This meant autonomous sessions had zero structural enforcement: Claude would work based on prompt instructions, finish a response, and stop normally. The zombie detector would then kill the idle session after 15 minutes.

**Sleep/wake crash loop fix.** The supervisor was killing the server on every wake because health checks failed briefly during the system transition. Three fixes:

1. **Wake-tolerant supervisor** (`ServerSupervisor.ts`) — Added a 60-second wake transition window. During this window, if health checks fail but the server tmux session is still alive, the supervisor waits instead of killing. Also lowered SleepWakeDetector drift threshold from 10s to 5s to catch shorter sleeps.

2. **Caffeinate leak fix** (`CaffeinateManager.ts`) — `cleanupStale()` now kills ALL orphaned caffeinate processes via `pgrep -x caffeinate`, not just the single PID from the PID file. Orphans accumulated from crash restarts where `stop()` never ran.

3. **Session server restart prevention** (`cli.ts`) — `instar server start/stop/restart` now rejects calls from inside sessions (checks `INSTAR_SESSION_ID` env var). Also fixed the `fix restart` command writing `restart-requested.json` to the wrong directory.

**Autonomous mode changes (three changes):**

1. **PostUpdateMigrator: `ensureAutonomousStopHook()`** — New migration that deploys the stop hook files to `.claude/skills/autonomous/hooks/` and registers the hook in `settings.json` Stop chain (first position). Runs automatically on server startup when version changes. Idempotent.

2. **init.ts: `installAutonomousSkill()`** — New agents now get the full autonomous skill deployed during init, including hooks directory and scripts. The hook is also registered in `installClaudeSettings()`.

3. **Tests** — 17 new tests across 3 files:
   - `autonomous-skill-deployment.test.ts` (14 tests) — Full skill deployment verification
   - `fresh-install.test.ts` (+2 tests) — New project autonomous hook verification
   - `migration-parity.test.ts` (+1 test) — Ensures migration includes autonomous hook deployment

## What to Tell Your User

- **Sleep/wake fix**: "Your agent should no longer crash-loop when your laptop wakes from sleep. The supervisor now waits for the server to recover instead of killing it during the transition."
- **Caffeinate cleanup**: "Cleaned up orphaned caffeinate processes. They were accumulating from server crash restarts — this won't happen anymore."
- **Autonomous mode fix**: "I found why autonomous sessions were dying after 30 minutes instead of running for hours. The stop hook that keeps me working through the task list was never actually installed. It's fixed now — autonomous sessions should properly loop until all tasks are done or the timer runs out."

## Summary of New Capabilities

| Capability | How to Use |
|-----------|-----------|
| Wake-tolerant supervisor | Automatic — 60s grace window after sleep/wake detection |
| Caffeinate orphan cleanup | Automatic — kills all orphaned caffeinate on startup |
| Session server restart guard | Automatic — blocks `instar server start/stop/restart` from sessions |
| Autonomous stop hook deployment | Automatic — deployed during migration on update |
| Autonomous stop hook registration | Automatic — registered in settings.json Stop chain |
| New agent autonomous skill | Automatic — full skill deployed during `instar init` |
