# Upgrade Guide — vNEXT

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

## What to Tell Your User

If you run your agent across more than one machine and move a conversation to another
one, the moved conversation now remembers what you were talking about — the receiving
machine pulls the recent history from the machine that was serving it. Only relevant
when the multi-machine session pool is on; single-machine agents are unaffected. Nothing
to configure.

If you run an agent with the mentor routine enabled, it will stop making things worse during AI rate-limit periods — it now waits for the provider to recover instead of repeatedly tripping the system-wide pause. Nothing to configure.

## Summary of New Capabilities

- New `formatForwardedTopicContext` helper formats relayed history into the standard
  thread-history block.
- `spawnSessionForTopic` accepts an optional pre-computed context, used verbatim when
  provided (skipping the empty-on-a-standby local sources); single-machine behavior is
  unchanged when it is absent.
- The owner-side resume fetches the router's recent topic messages and passes them, so a
  moved session continues the conversation.

- The mentor onboarding tick now gates on LLM availability (the shared rate-limit circuit breaker) in addition to budget and safe-window: when the provider is rate-limited it backs off with reason `llm-rate-limited` and resumes automatically when the breaker closes. A new read-only `llmCircuitAvailable()` helper exposes the breaker state without consuming its recovery probe.

## Evidence

- Confirmed in code: on a standby, a moved session was spawned with no TopicMemory and an
  empty local message history, so it started with no prior conversation context.
- Unit, `tests/unit/ForwardedTopicContext.test.ts`: the formatter over empty history,
  multi-message threads with attribution, sender/timestamp fallbacks, and the
  per-message length cap.
- Wiring, `tests/unit/session-pool-activation-wiring.test.ts`: the owner-side bridge
  still spawns and fails safe with the history fetch wrapped around it.
- 51 session-pool + adapter tests pass; tsc --noEmit clean.
- Note: unit-verified; the live confirmation that a moved session retains its context
  follows once the second machine's CLI is logged in.
- Spec, `docs/specs/moved-session-context-relay.md` plus the .eli16.md sibling.

- Found in the agent's own server log: the LLM circuit breaker opening repeatedly (trip #7) on the mentor's `claude -p` forensics call.
- The mentor tick gated on budget but not on the rate-limit circuit, so it ran LLM-backed Stage A + Stage B while the provider was throttled, re-tripping the breaker (which pauses all LLM-backed work ~900s per trip).
- Unit tests: the tick skips with reason `llm-rate-limited` BEFORE any spawn/forensics when the circuit is open; budget is still checked first; the existing gate-order and happy-path cases stay green.

## What Changed — a conversation moved to your other machine keeps its memory

A quality step for the multi-machine "move this conversation to my other machine"
feature. When a conversation moved to the backup machine, that machine started the
session fresh from its own records — which were empty for that conversation (it had
never been the one talking to you). So the moved conversation effectively forgot
everything that came before it.

This release has the receiving machine fetch the recent history from the machine that
was serving the conversation, and seed the moved session with it. So the conversation
picks up where it left off instead of resetting. It's best-effort: if the other machine
can't be reached, the session still starts (just without the prior history, as before),
so it never blocks the move.

## What Changed — The mentor routine no longer hammers a rate-limited provider and re-trips the pause

Agents can run a "mentor" routine that periodically studies a mentee agent using the AI model. There's also a safety breaker that pauses all AI work for a while when the provider says you're going too fast (rate-limited). The mentor checked its spending budget before running, but not whether the AI was currently rate-limited — so while the provider was throttled, the mentor kept firing off doomed analyses that failed and re-tripped the pause, restarting it again and again. The agent was effectively tripping itself.

Now the mentor also checks the breaker: if the AI is currently rate-limited, it skips this round and picks up on the next one, instead of throwing a doomed request at a throttled provider and re-pausing all the agent's other AI-backed monitors.
