# Upgrade Guide — vNEXT

<!-- assembled-by: assemble-next-md -->
<!-- bump: patch -->

## What Changed

The autonomous-mode stop hook was being registered in `settings.json` at
`.instar/hooks/instar/autonomous-stop-hook.sh` — a path where the hook is **never
deployed**. The hook ships only in the skill directory
(`.claude/skills/autonomous/hooks/autonomous-stop-hook.sh`). So on every `Stop`
event the hook command hit a missing file, failed silently, and the autonomous
loop never re-injected the task list. The session stayed alive but stopped
self-continuing between turns — it only advanced when the user sent a message.

Three coordinated fixes:

1. **`.claude/skills/autonomous/SKILL.md` (Step 2a)** now registers the deployed
   skill path and self-heals: it strips any prior (including wrong-path)
   autonomous stop-hook entry and writes exactly one correct-path entry.
2. **`PostUpdateMigrator.ensureAutonomousStopHook()`** gained a repair pass that
   rewrites any existing wrong-path registration in `settings.json` to the skill
   path. Without it, the "already registered?" presence check treated the
   wrong-path entry as present and never corrected it — so existing agents would
   stay broken forever.
3. **`PostUpdateMigrator.migrateAutonomousStopHookTopicKeyed()`** re-deploys the
   fixed `SKILL.md` to existing agents, gated on a marker unique to the corrected
   prompt (stock prompts upgrade; customized prompts are left untouched).

## What to Tell Your User

If you ran an autonomous session and noticed it went quiet between turns —
continuing only when you messaged it, rather than driving itself forward — this
fixes the cause. The loop's re-engagement step was pointed at a file that was
never installed, so it silently did nothing each time the session tried to
continue. After this update the autonomous loop re-engages on its own as
intended, and any agent that already had the broken registration is repaired
automatically on update. No action is needed on your side.

## Summary of New Capabilities

- Autonomous sessions reliably self-continue between turns (the stop hook now
  resolves to a file that actually exists).
- Existing agents with the broken registration are healed in place on update —
  both the `settings.json` entry and the deployed skill prompt.
- The skill registration is now self-healing: activating autonomous mode always
  ends with exactly one correct-path stop-hook entry, regardless of prior state.

## Evidence

- New unit suite `tests/unit/PostUpdateMigrator-autonomousHookPath.test.ts`
  (9 tests): wrong-path → repaired; no duplicate added; siblings untouched;
  already-correct → no-op; missing → registered; idempotent; SKILL.md content
  asserts the corrected path + marker; topic-keyed migration re-deploys a stock
  SKILL.md and skips a customized one.
- Empirical check of the SKILL.md Step 2a snippet against a settings file
  carrying the wrong-path entry plus sibling hooks: the wrong entry is rewritten
  to `bash ${CLAUDE_PROJECT_DIR}/.claude/skills/autonomous/hooks/autonomous-stop-hook.sh`,
  siblings are preserved, and a second run is a no-op (idempotent).
- Existing autonomous/migration suites stay green
  (`autonomous-skill-deployment`, `PostUpdateMigrator-buildStopHook`,
  `autonomous-stop-hook-notify`, `installCodexHooks`, `emit-session-clock` —
  50 tests). `tsc --noEmit` clean.
