# Upgrade Guide — vNEXT

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

## What Changed

First increment (the pure engine) of the **Gemini multi-turn loop-driver**
(`need-gem-002`) — the mechanism that will let a Gemini mentee sustain a
multi-turn task instead of being bounded to one-shots (the #1 program-need from
the codey-to-gemini apprenticeship retro).

A new `GeminiLoopDriver` (`src/monitoring/GeminiLoopDriver.ts`) drives a goal
across turns. Unlike Claude/codex — which run as persistent hook-capable sessions
and re-prompt via the autonomous Stop hook — gemini runs as one-shots, so the loop
is driven EXTERNALLY: turn 1 is a one-shot that establishes a session, and each
later turn re-spawns gemini with the proven native resume path. Because gemini
restores the session's context itself, the driver re-prompts with only the next
instruction — never the accumulated transcript — which is the quota-efficient
design that respects the subscription-auth / no-overspend rule.

The engine is fully dependency-injected (the gemini spawn, an optional budget
gate, the session-handle capture, sleep, clock), so its loop logic is exercised
by 14 unit tests with zero real gemini calls and zero quota. It terminates on a
done-sentinel, a turn cap, a budget-gate halt, a spawn failure, or a
handle-capture failure (it ABORTS rather than resuming a foreign session). A
companion transport helper `buildGeminiResumeArgv` adds the `-r <handle>` resume
argv (keeping the explicit `-m` that bypasses gemini-cli's flaky pre-turn
model-router classifier).

This increment is **dark and unwired**: nothing invokes the engine yet. Lifecycle
invocation (a budget-gated route + the apprenticeship machinery calling it, the
real `--list-sessions` handle parser, and a config flag) is the next increment,
which is where the §6 budget-guardrail defaults are finalized. Spec:
`docs/specs/gemini-multi-turn-loop-driver.md`.

**Your agent can now see what all its hands are doing across topics at once.** A new
cross-topic Activity Index reads your existing per-topic intent and presents one view:
every topic, its current focus, high-specificity tags, and whether a session is live on
it. This is the antidote to self-blindness — starting work in one topic that another topic
already finished (the exact thing that happened in the resource-tracking workstream, where
one topic re-specced CPU work another had already shipped).

Crucially, this does NOT add a new store. The design review found that the per-topic focus
data already exists (the Topic-Intent layer, updated structurally on every turn), so this is
a thin read-aggregator over it — no duplication, no new write path to remember.

This is Phase A (the read surface). The proactive overlap councilor — a sentinel that
notices "two of your topics are working on the same thing" and tells you — is Phase B and
ships separately (and dark, because a false-positive nudge is worse than silence).

## What to Tell Your User

Nothing is live to announce yet. This is internal groundwork — a tested engine
that, once wired up in a following change, will let the Gemini agent work through
a multi-step task on its own (on subscription login, never an API key) instead of
stopping after one reply. It ships turned off and disconnected, so it changes
nothing about how I work today. I will only surface it as a real capability once
it is wired, budget-guarded, and verified.

Your agent is now less likely to duplicate work across different conversations. It can list
what each of its topics is working on in one place, so before it starts something big it can
notice another topic already has it covered. Nothing to configure; it reads data the agent
already keeps.

## Summary of New Capabilities

- `GET /parallel-work/activities` — read-only cross-topic index: per topic, its current focus,
  high-specificity tags, freshness, and whether a session is live on it.
- A specificity-aware tag extractor that ignores generic boilerplate (so two topics that both
  say "fix the test" don't look like the same work) and keeps genuine shared entities.

## Evidence

- Converged spec (2-reviewer adversarial + integration pass that RESHAPED the design — from a
  new store to a thin index over the existing Topic-Intent layer, with a distinct
  /parallel-work prefix to avoid the existing Coherence-Gate naming collision):
  docs/specs/parallel-activity-coherence.md.
- All three test tiers green: 7 unit (extractTags specificity boundary incl. cpu vs
  cpu-sampling; focus derivation goal>decision>purpose; empty-dir ⇒ []), 2 integration
  (200/503), 3 e2e (feature-alive on the real AgentServer init path + Bearer-auth + read-only).
  tsc clean.
