# Upgrade Guide — vNEXT

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

## What to Tell Your User

If you run your agent on more than one machine and move a conversation between them,
the move now actually takes effect instead of the original machine continuing to
answer alongside the new one. This is one step in a larger effort to make moving live
conversations between your machines reliable. It only applies when the multi-machine
session pool is turned on; single-machine agents are unaffected. Nothing to configure.

## Summary of New Capabilities

- New exported `isRemotelyHandled(outcome, selfMachineId)` in `SessionRouter` — the
  pure, unit-tested rule for whether a routed message was handled on another machine
  (forwarded/duplicate always; spawned/owner-dead-replaced only when the owner isn't
  this machine). Fail-safe: an unknown self with an unknown owner falls through to
  local handling, never dropping a message.
- The inbound dispatcher uses it (instead of a forwarded/duplicate-only check), so a
  freshly-placed remote session is no longer also dispatched locally.
- A new per-message routing-decision log line for session-pool observability.

## Evidence

- Found live on 2026-05-31 running the real "move this to the Mac mini" test on a
  throwaway topic: the move command was recognized and pinned to the mini, but the
  next message was injected into the existing local session instead of forwarding —
  because the dispatcher's "spawned on the target" answer was not treated as remote.
- Unit, `tests/unit/SessionRouter.test.ts`: isRemotelyHandled across forwarded,
  duplicate, remote vs self spawned, remote vs self owner-dead-replaced,
  local/queued/blocked fall-through, and the null-self fail-safe.
- Wiring, `tests/unit/session-pool-activation-wiring.test.ts`: the dispatcher uses
  the helper and still falls back to local dispatch on any routing error.
- 50 session-pool tests pass; tsc --noEmit clean.
- Spec, `docs/specs/session-pool-route-shortcircuit.md` plus the .eli16.md sibling.
- Side-effects, `upgrades/side-effects/session-pool-route-shortcircuit.md`.

## What Changed — moving a conversation between machines no longer double-handles it

Part of bringing the multi-machine "move this conversation to my other machine"
feature to life. When the feature is on and you move a conversation, an incoming
message is routed by a dispatcher that decides whether to keep it on this machine or
send it to the machine that now owns the conversation. The code reading that
dispatcher's decision only recognized two of its "it went to the other machine"
answers — it missed the answer the dispatcher gives when it freshly starts a moved
conversation on the target machine. So a just-moved conversation was started on the
target AND still answered on the original machine, which made the move look like it
did nothing.

This release teaches the reader the full set of "handled on another machine" answers
via a small, well-tested helper, and adds a log line that records every routing
decision so the live path is no longer a black box.
