# Upgrade Guide — vNEXT

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

## What Changed

When a conversation (topic) moves from one machine to another in the
multi-machine session pool, the OLD machine's session for that topic is now
closed automatically — previously it lingered indefinitely, doing duplicate
work alongside the new machine's session (the operator-named duplicate-sessions
issue).

Two layers:

1. **Immediate** — an explicit "move this to X" closes the local session the
   moment the move executes (the user's command is the authority; protected
   sessions are never auto-closed; the close is silent since the user already
   got the "Moving…" confirmation).
2. **Standing invariant** — the SessionReaper closes any topic-bound session
   whose topic the ownership registry shows owned by ANOTHER machine, after a
   2-tick (~4 min) dwell that absorbs in-progress transfers. This covers
   failovers and automatic re-placements. The close goes through the existing
   guarded terminate authority: a KEEP-guard veto is audited and retried, never
   forced. Works even when the duplicate is BUSY — busy-on-a-duplicate is the
   bug.

Every close (and every refusal) lands in the reap-log with reason "topic moved
to <machine>". Config: `monitoring.sessionReaper.topicMovedCloseout` (default
true; inert on single-machine installs) + `topicMovedConfirmTicks` (default 2).

## What to Tell Your User

When you move a conversation to another machine, the machine you left now
cleans up after itself — no more duplicate sessions quietly doing the same
work twice. If you ever wonder where a session went, the reap-log says exactly
why ("topic moved to Laptop").

## Summary of New Capabilities

- Explicit topic moves immediately close the old machine's session.
- A reaper rule guarantees eventual closeout for failover/re-placement paths.
- `monitoring.sessionReaper.topicMovedCloseout` / `topicMovedConfirmTicks` config.
- Reap-log + audit rows (`rule: 'topic-moved-away'`) for full traceability.
- CLAUDE.md template + migration so agents explain auto-closed sessions correctly.

## Evidence

`tests/unit/session-reaper-topic-moved.test.ts` (9 — including closing a BUSY
duplicate, churn-resets-dwell, guard-veto-retry, dry-run, budgets, all inert
paths) + 3 migration tests; full reaper family regression 65/65 green; tsc +
lint clean.
