# Upgrade Guide — vNEXT

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

## What Changed

- **`GET /jobs?scope=pool`** merges every online machine's scheduled jobs into one
  view, each tagged with the machine that runs it — mirroring the proven
  `sessions?scope=pool` / `attention?scope=pool` family: per-peer 5s timeout with a
  `pool.failed[]` marker on a dark/offline peer (never a 500), a 3s short-TTL cache,
  non-recursive peer calls. Plain `GET /jobs` is byte-for-byte unchanged.
- **F8 placement-divergence detector** (observe-only, `pool.divergences[]`): flags a
  machine that DECLARES jobs (N>0) but RUNS none of them locally — "config says jobs
  here, this machine isn't running them." Derived honestly from each machine's own
  `/jobs` reply; no fabricated counts; never gates. A machine with zero jobs is NOT
  flagged (legitimate scheduler-less/dispatcher machine).
- CLAUDE.md template + idempotent PostUpdateMigrator bullet (Agent Awareness +
  Migration Parity).

This is the READ half of WS4.3. The role-guard-at-spawn (refuse state-writing jobs on
a read-only standby → re-route or attention) and the journal-lease claim cutover are
SEPARATE follow-up slices. <!-- tracked: CMT-1416 -->

## What to Tell Your User

On a multi-machine setup, "what jobs are running where?" now answers across all your
machines at once — each scheduled job tagged with the machine running it, a machine
that's offline noted rather than dropped, and a heads-up if a machine is configured to
run jobs but isn't actually running any.

## Summary of New Capabilities

- One pooled view of scheduled jobs across the fleet (`GET /jobs?scope=pool`),
  machine-tagged, dark peers surfaced as `failed`, plus an observe-only placement-
  divergence signal.

## Evidence

- `tests/integration/jobs-pool-scope.test.ts` (9, new): plain GET self-tags identity;
  scope=pool merges a REAL peer server's jobs; offline peer → failed without waiting;
  unreachable peer → failed, local still answers; no-peers → local-only; divergence
  flags declares-N-runs-0; a zero-jobs peer is NOT flagged; scheduler-less shape.
- `tests/unit/PostUpdateMigrator-jobsPoolScope.test.ts` (4, new): migration + template
  parity, idempotent. `tsc --noEmit` clean. Existing jobs-endpoints-auth (15) +
  guardian-jobs (11) + attention-pool-scope (7) all still green.
