feat: carbon-aware codecarbon wait (forecast + greenest-window selection)

[davidberenstein1957]

A deliberately narrow first slice of carbon-aware scheduling (#1356).

Stacks on #1358: wait reuses that PR's cached, backed-off Electricity Maps client instead of opening a second HTTP path. Review #1358 first; this PR targets feat/intensity-providers and its diff here is only the wait feature.

What is in it

• codecarbon/core/intensity_forecast.py — IntensityPoint / Forecast dataclasses, get_forecast() against the Electricity Maps /carbon-intensity/forecast endpoint (going through feat: cache and back off Electricity Maps carbon intensity #1358's shared request(), so a failing location backs off once for the whole process rather than once per caller), and best_window(), a pure sliding-mean window search with no I/O.
• codecarbon/cli/wait.py + a wait command in codecarbon/cli/main.py:

# print the recommendation and exit
$ codecarbon wait --dry-run --deadline 24h --duration 90m
🌱 Best start: 2026-08-13 03:00 UTC  (112 gCO2e/kWh, now: 341)  -> saves ~67%

# block until the greenest window, then run under measurement
$ codecarbon wait --deadline 12h --duration 2h -- python train.py

# the job must be *finished* within 8 hours, and takes about 2
$ codecarbon wait --finish-by 8h --duration 2h -- python train.py

--deadline is the latest acceptable start, so --deadline 12h --duration 2h may leave the job running 14 hours from now. --finish-by is the complement most people actually mean: it bounds the end, and is implemented as finish_by - duration feeding the same search. A --finish-by shorter than --duration is rejected.

One API call. wait fetches the forecast and nothing else. The "now" figure printed, and the value --threshold compares against, is the first forecast point — the current period as the forecast sees it. An earlier revision also hit /carbon-intensity/latest for a live reading, which was a second network round trip in service of a percentage.

The blocking form delegates to the existing run_and_monitor, so measurement, CSV output and exit-code propagation are unchanged. The tracker only starts after the sleep, so a waiting process holds no lock. Ctrl-C during the wait starts the job immediately rather than aborting.

get_forecast never raises: no token, a non-200, a malformed payload or an empty forecast all return None, and every caller degrades to running now. A job is never blocked on a missing credential.

What is deliberately not in it

• The @carbon_aware decorator / wait_for_green_window context manager. The CLI is the smaller surface and validates whether anyone wants the sleeping behaviour before we own a second one.
• deferred_seconds / avoided_emissions on EmissionsData. Worth having, but they should ship with a proven blocking path — two always-zero CSV columns are a schema change for no reader.
• A static fallback diurnal profile for users without a token. It would broaden reach a lot but risks systematically wrong advice: solar-heavy zones trough at midday, wind-heavy zones at night.
• Mid-wait re-evaluation as the forecast updates, and region shifting.

What is blocked on the intensity-provider work

Electricity Maps is currently the only source that can serve a forecast, and only for users holding a paid token. That caps how much of the audience this feature can reach, and it is why this is a narrow slice rather than the full design in #1356.

get_forecast is written to be absorbed: once pluggable intensity providers land it should become an optional forecast() method on the provider protocol rather than a second HTTP client, and the HTTP lives in one place (#1358's request()) so that move is mechanical.

Tests

tests/test_intensity_forecast.py (14) and tests/cli/test_wait.py (22), all passing, no network — HTTP is stubbed with responses as in tests/test_electricitymaps_api.py, and geolocation, config and time.sleep are monkeypatched in the CLI tests. Coverage includes payload parsing, lat/lon vs countryCode selection, naive-vs-aware timestamps, horizon truncation, every failure mode returning None, the shared cooldown skipping the request, the window search (trough, flat, monotonic, deadline shorter than duration, duration longer than horizon), --finish-by bounding the end and its rejection when shorter than --duration, the duration parser, the threshold short-circuit taking no second API call, and delegation to run_and_monitor with the residual command.

uv run pytest tests/cli/test_wait.py tests/test_intensity_forecast.py -q   # 36 passed

Docs: a codecarbon wait section in docs/reference/cli.md and a pointer from docs/tutorials/cli.md.

Refs #1356

🤖 Generated with Claude Code

[codecov]

Codecov Report

❌ Patch coverage is 98.46154% with 2 lines in your changes missing coverage. Please review.
✅ Project coverage is 91.77%. Comparing base (70bbd45) to head (7fd8003).

Files with missing lines	Patch %	Lines
codecarbon/cli/main.py	50.00%	2 Missing ⚠️

Additional details and impacted files

@@                     Coverage Diff                      @@
##           feat/intensity-providers    #1363      +/-   ##
============================================================
+ Coverage                     91.54%   91.77%   +0.22%     
============================================================
  Files                            49       51       +2     
  Lines                          5122     5253     +131     
============================================================
+ Hits                           4689     4821     +132     
+ Misses                          433      432       -1     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.