@seanyao/roll 2026.522.2 → 2026.523.2

package/lib/i18n.sh

@@ -0,0 +1,113 @@
+#!/usr/bin/env bash
+# Roll i18n engine — US-I18N-001.
+#
+# Provides:
+#   _i18n_resolve_lang     — resolve user's language per precedence
+#   msg <key> [args...]    — look up message catalog with EN fallback
+#   _i18n_set <lang> <key> <value>  — fill the catalog (used by modules)
+#
+# Storage is bash 3.2-compatible (macOS default ships 3.2): each catalog entry
+# is held in a plain variable named `MSG_<LANG>_<key>`, looked up via indirect
+# reference. Bash 4 assoc arrays would be cleaner but break macOS default bash
+# (see AGENTS.md §4: single bash script, no runtime).
+#
+# Precedence: ROLL_LANG env > ~/.roll/config.yaml `lang` > LC_ALL > LANG
+#             > (macOS) AppleLanguages > 'en'.
+# Decision:   value starting with `zh` → "zh", everything else → "en".
+
+# Sanitize a free-form key into a variable-safe suffix. Anything that isn't a
+# letter, digit, or underscore becomes an underscore so callers can use natural
+# dotted keys like "loop.cycle_start" without exploding bash syntax.
+_i18n_safe_key() {
+  echo "${1//[^A-Za-z0-9_]/_}"
+}
+
+# Fill the catalog. Modules call this at source-time:
+#   _i18n_set en hello "Hello, %s!"
+#   _i18n_set zh hello "你好，%s！"
+_i18n_set() {
+  local lang="$1" key="$2" val="$3"
+  local upper safe varname
+  upper=$(echo "$lang" | tr '[:lower:]' '[:upper:]')
+  safe=$(_i18n_safe_key "$key")
+  varname="MSG_${upper}_${safe}"
+  printf -v "$varname" '%s' "$val"
+  export "$varname"
+}
+
+# Decide "zh" or "en" from a free-form locale string.
+_i18n_classify() {
+  case "${1:-}" in
+    zh*) echo zh ;;
+    *)   echo en ;;
+  esac
+}
+
+# Resolve the active language. Caches in ROLL_LANG_RESOLVED so later calls are
+# free.
+_i18n_resolve_lang() {
+  if [[ -n "${ROLL_LANG_RESOLVED:-}" ]]; then
+    echo "$ROLL_LANG_RESOLVED"
+    return
+  fi
+
+  local lang=""
+
+  if [[ -n "${ROLL_LANG:-}" ]]; then
+    lang=$(_i18n_classify "$ROLL_LANG")
+  fi
+
+  if [[ -z "$lang" && -n "${ROLL_CONFIG:-}" && -f "${ROLL_CONFIG}" ]]; then
+    local cfg
+    cfg=$(grep -E '^lang:' "$ROLL_CONFIG" 2>/dev/null | head -1 \
+            | sed 's/^lang:[[:space:]]*//' \
+            | sed 's/[[:space:]]*#.*$//' \
+            | sed 's/[[:space:]]*$//')
+    [[ -n "$cfg" ]] && lang=$(_i18n_classify "$cfg")
+  fi
+
+  if [[ -z "$lang" && -n "${LC_ALL:-}" ]]; then
+    lang=$(_i18n_classify "$LC_ALL")
+  fi
+
+  if [[ -z "$lang" && -n "${LANG:-}" ]]; then
+    lang=$(_i18n_classify "$LANG")
+  fi
+
+  if [[ -z "$lang" ]] && command -v defaults >/dev/null 2>&1; then
+    local apple
+    apple=$(defaults read -g AppleLanguages 2>/dev/null | head -2 | tail -1 \
+              | tr -d ' ",()' | head -1 || true)
+    [[ -n "$apple" ]] && lang=$(_i18n_classify "$apple")
+  fi
+
+  [[ -z "$lang" ]] && lang="en"
+
+  ROLL_LANG_RESOLVED="$lang"
+  echo "$lang"
+}
+
+# Look up message catalog entry. Falls back to EN, then to the key itself so
+# missing translations stay visible without crashing the caller.
+msg() {
+  local key="$1"; shift || true
+  local lang safe
+  lang=$(_i18n_resolve_lang)
+  safe=$(_i18n_safe_key "$key")
+
+  local zh_var="MSG_ZH_${safe}"
+  local en_var="MSG_EN_${safe}"
+  local tmpl=""
+
+  if [[ "$lang" == "zh" && -n "${!zh_var:-}" ]]; then
+    tmpl="${!zh_var}"
+  elif [[ -n "${!en_var:-}" ]]; then
+    tmpl="${!en_var}"
+  else
+    tmpl="$key"
+  fi
+
+  # shellcheck disable=SC2059 — template comes from our own catalog
+  printf "$tmpl" "$@"
+  echo
+}

package/lib/loop-fmt.py

@@ -344,6 +344,40 @@ class LoopFmt:
         # required env vars aren't set (e.g. running outside roll loop).
         self._emit_usage_event(ev, dur_ms, cost_usd)
 
+    @staticmethod
+    def _price_at_snapshot(model, totals):
+        """Resolve (cost_list_usd, prices_version) from the active price snapshot.
+
+        Returns (None, None) when model_prices isn't loadable or the snapshot
+        has no usable prices — callers still emit the event so token data and
+        duration aren't lost. When tokens are all zero, cost_list_usd is None.
+        """
+        try:
+            import importlib.util
+            lib_dir = os.path.dirname(os.path.abspath(__file__))
+            spec = importlib.util.spec_from_file_location(
+                "model_prices", os.path.join(lib_dir, "model_prices.py")
+            )
+            mp = importlib.util.module_from_spec(spec)
+            spec.loader.exec_module(mp)
+        except Exception:
+            return None, None
+        prices_version = getattr(mp, "VERSION", None)
+        has_tokens = any(int(totals.get(k) or 0) > 0 for k in totals)
+        if not has_tokens:
+            return None, prices_version
+        try:
+            cost = mp.compute_list_cost(
+                model,
+                input_tokens=int(totals.get("input_tokens") or 0),
+                output_tokens=int(totals.get("output_tokens") or 0),
+                cache_creation_tokens=int(totals.get("cache_creation_tokens") or 0),
+                cache_read_tokens=int(totals.get("cache_read_tokens") or 0),
+            )
+        except Exception:
+            return None, prices_version
+        return float(cost), prices_version
+
     def _emit_usage_event(self, result_ev, dur_ms, cost_usd):
         slug    = os.environ.get("LOOP_PROJECT_SLUG")
         cycle   = os.environ.get("LOOP_CYCLE_ID")
@@ -353,14 +387,39 @@ class LoopFmt:
         # Use the cumulative totals accumulated across all assistant turns;
         # result.usage is per-turn (last only) so it would under-count badly.
         model = result_ev.get("model") or self._last_model or ""
+
+        # FIX-099: skip writing the usage event when claude returned no real
+        # usage data (model empty AND cost/duration both zero). This prevents
+        # stale/placeholder values from leaking into the events stream and
+        # showing up as "cost=$1.24 dur=372s" in three consecutive cycles when
+        # the real cycle had no token data (the default-value fallback).
+        # The dashboard can render "n/a" for missing usage rather than false data.
+        has_model   = bool(model)
+        has_tokens  = any(self._usage_totals[k] > 0 for k in self._usage_totals)
+        has_cost    = bool(cost_usd)
+        has_dur     = bool(dur_ms)
+        if not has_model and not has_tokens and not has_cost and not has_dur:
+            return  # nothing real to report — skip rather than persist zeros
+
+        # US-VIEW-014: freeze cost at the current snapshot's list price so a
+        # later prices refresh (or roll upgrade) never rewrites history. The
+        # dashboard reads cost_list_usd first; only legacy events without it
+        # fall back to recomputing and get tagged [legacy].
+        cost_list_usd, prices_version = self._price_at_snapshot(
+            model if has_model else None,
+            self._usage_totals,
+        )
+
         payload = {
-            "model":                 model,
+            "model":                 model if has_model else None,
             "input_tokens":          self._usage_totals["input_tokens"],
             "output_tokens":         self._usage_totals["output_tokens"],
             "cache_creation_tokens": self._usage_totals["cache_creation_tokens"],
             "cache_read_tokens":     self._usage_totals["cache_read_tokens"],
-            "cost_reported_usd":     float(cost_usd or 0),
-            "duration_ms":           int(dur_ms or 0),
+            "cost_reported_usd":     float(cost_usd) if has_cost else None,
+            "duration_ms":           int(dur_ms) if has_dur else None,
+            "cost_list_usd":         cost_list_usd,
+            "prices_version":        prices_version,
         }
         evfile = os.path.join(shared, "loop", f"events-{slug}.ndjson")
         line = json.dumps({

package/lib/model_prices.py

@@ -5,68 +5,108 @@ Pricing is per million tokens (MTok), USD. These are the public list rates;
 discounts (Pro subscription, prepay credits, etc.) are intentionally not
 modeled — IDEA-025 is about cross-account / cross-project comparable cost.
 
-Update this table when Anthropic changes pricing. Unknown models fall back
-to sonnet rates with a stderr warning so dashboards don't blank out.
+US-VIEW-013: prices are no longer hardcoded here. They live in versioned
+snapshot files under ``lib/prices/snapshot-YYYY-MM-DD.json`` and are loaded
+at module import time. ``roll prices refresh`` produces new snapshots; this
+module never writes — it only loads the latest one.
+
+Unknown models fall back to the snapshot's ``default_model`` with a stderr
+warning so dashboards don't blank out.
 """
 
+import json
+import os
 import sys
-from typing import Dict, Optional
-
-# Rates per million tokens (USD). cache_create = 5-minute cache write (1.25x
-# input). 1-hour cache writes (2x input) are not modeled — Roll loop uses the
-# default 5m caching only.
-# Source: https://platform.claude.com/docs/en/about-claude/pricing
-PRICES: Dict[str, Dict[str, float]] = {
-    # Claude 4.x Opus family — 2026-05 repricing: Opus 4.5+ moved to
-    # $5/$25 base, 3x cheaper than Opus 4 / 4.1.
-    "claude-opus-4-7":    {"in":  5.00, "out": 25.00, "cache_create":  6.25, "cache_read": 0.50},
-    "claude-opus-4-6":    {"in":  5.00, "out": 25.00, "cache_create":  6.25, "cache_read": 0.50},
-    "claude-opus-4-5":    {"in":  5.00, "out": 25.00, "cache_create":  6.25, "cache_read": 0.50},
-    "claude-opus-4-1":    {"in": 15.00, "out": 75.00, "cache_create": 18.75, "cache_read": 1.50},
-    "claude-opus-4":      {"in": 15.00, "out": 75.00, "cache_create": 18.75, "cache_read": 1.50},
-    # Claude 4.x Sonnet family.
-    "claude-sonnet-4-6":  {"in":  3.00, "out": 15.00, "cache_create":  3.75, "cache_read": 0.30},
-    "claude-sonnet-4-5":  {"in":  3.00, "out": 15.00, "cache_create":  3.75, "cache_read": 0.30},
-    "claude-sonnet-4":    {"in":  3.00, "out": 15.00, "cache_create":  3.75, "cache_read": 0.30},
-    # Claude 4.x Haiku family.
-    "claude-haiku-4-5":   {"in":  1.00, "out":  5.00, "cache_create":  1.25, "cache_read": 0.10},
-    # Older / retired models (Bedrock & Vertex only for 3.5 Haiku).
-    "claude-haiku-3-5":   {"in":  0.80, "out":  4.00, "cache_create":  1.00, "cache_read": 0.08},
-    "claude-3-5-sonnet":  {"in":  3.00, "out": 15.00, "cache_create":  3.75, "cache_read": 0.30},
-}
-
-DEFAULT = "claude-sonnet-4-6"
+from typing import Any, Dict, List, Optional, Tuple
+
+_LIB_DIR = os.path.dirname(os.path.abspath(__file__))
+SNAPSHOT_DIR = os.path.join(_LIB_DIR, "prices")
+
+
+def list_snapshots(snapshot_dir: str = SNAPSHOT_DIR) -> List[str]:
+    """Return absolute paths of all snapshot files, sorted oldest → newest by filename."""
+    if not os.path.isdir(snapshot_dir):
+        return []
+    entries = [
+        os.path.join(snapshot_dir, name)
+        for name in os.listdir(snapshot_dir)
+        if name.startswith("snapshot-") and name.endswith(".json")
+    ]
+    return sorted(entries)
+
+
+def load_snapshot(path: str) -> Dict[str, Any]:
+    """Load a snapshot file and validate its shape."""
+    with open(path, "r", encoding="utf-8") as f:
+        data = json.load(f)
+    for key in ("version", "effective_at", "source_url", "prices"):
+        if key not in data:
+            raise ValueError(f"snapshot {path!r} missing required key {key!r}")
+    if not isinstance(data["prices"], dict) or not data["prices"]:
+        raise ValueError(f"snapshot {path!r} has empty or invalid prices map")
+    data.setdefault("default_model", next(iter(data["prices"])))
+    return data
+
+
+def load_latest_snapshot(snapshot_dir: str = SNAPSHOT_DIR) -> Dict[str, Any]:
+    """Load the newest snapshot by filename. Raises FileNotFoundError if none exist."""
+    snaps = list_snapshots(snapshot_dir)
+    if not snaps:
+        raise FileNotFoundError(
+            f"no price snapshots found in {snapshot_dir}; run `roll prices refresh`"
+        )
+    return load_snapshot(snaps[-1])
+
+
+_SNAPSHOT: Dict[str, Any] = load_latest_snapshot()
+PRICES: Dict[str, Dict[str, float]] = _SNAPSHOT["prices"]
+DEFAULT: str = _SNAPSHOT["default_model"]
+VERSION: str = _SNAPSHOT["version"]
+EFFECTIVE_AT: str = _SNAPSHOT["effective_at"]
+SOURCE_URL: str = _SNAPSHOT["source_url"]
+
 _warned: set = set()
 
-def _resolve(model: Optional[str]) -> Dict[str, float]:
+
+def snapshot_meta() -> Tuple[str, str, str]:
+    """Return (version, effective_at, source_url) of the active snapshot."""
+    return VERSION, EFFECTIVE_AT, SOURCE_URL
+
+
+def _resolve(model: Optional[str], prices: Optional[Dict[str, Dict[str, float]]] = None,
+             default: Optional[str] = None) -> Dict[str, float]:
+    table = prices if prices is not None else PRICES
+    fallback = default if default is not None else DEFAULT
     if not model:
-        return PRICES[DEFAULT]
-    # Strip date suffixes like '-20251001' or '[1m]' context tags.
+        return table[fallback]
     base = model.split("[")[0].rstrip("0123456789-")
-    # Try a prefix match against the table; longest match wins.
-    candidates = [k for k in PRICES if model.startswith(k) or base.startswith(k)]
+    candidates = [k for k in table if model.startswith(k) or base.startswith(k)]
     if candidates:
-        return PRICES[max(candidates, key=len)]
+        return table[max(candidates, key=len)]
     if model not in _warned:
         _warned.add(model)
-        print(f"[model_prices] warn: unknown model {model!r}, falling back to {DEFAULT}",
+        print(f"[model_prices] warn: unknown model {model!r}, falling back to {fallback}",
               file=sys.stderr)
-    return PRICES[DEFAULT]
+    return table[fallback]
+
 
 def compute_list_cost(model: Optional[str],
                       *,
                       input_tokens: int = 0,
                       output_tokens: int = 0,
                       cache_creation_tokens: int = 0,
-                      cache_read_tokens: int = 0) -> float:
+                      cache_read_tokens: int = 0,
+                      prices: Optional[Dict[str, Dict[str, float]]] = None,
+                      default: Optional[str] = None) -> float:
     """Return USD cost at list price for one cycle's token usage."""
-    p = _resolve(model)
+    p = _resolve(model, prices=prices, default=default)
     total = (input_tokens         * p["in"]
            + output_tokens        * p["out"]
            + cache_creation_tokens * p["cache_create"]
            + cache_read_tokens    * p["cache_read"]) / 1_000_000
     return round(total, 4)
 
+
 def total_tokens(*,
                  input_tokens: int = 0,
                  output_tokens: int = 0,

package/lib/prices/snapshot-2026-05-22.json

@@ -0,0 +1,20 @@
+{
+  "version": "2026-05-22",
+  "effective_at": "2026-05-22",
+  "source_url": "https://platform.claude.com/docs/en/about-claude/pricing",
+  "default_model": "claude-sonnet-4-6",
+  "notes": "Rates per million tokens (USD). cache_create = 5-minute cache write (1.25x input). 1-hour cache writes (2x input) are not modeled — Roll loop uses the default 5m caching only. 2026-05 repricing: Opus 4.5+ moved to $5/$25 base (3x cheaper than Opus 4/4.1).",
+  "prices": {
+    "claude-opus-4-7":   {"in":  5.00, "out": 25.00, "cache_create":  6.25, "cache_read": 0.50},
+    "claude-opus-4-6":   {"in":  5.00, "out": 25.00, "cache_create":  6.25, "cache_read": 0.50},
+    "claude-opus-4-5":   {"in":  5.00, "out": 25.00, "cache_create":  6.25, "cache_read": 0.50},
+    "claude-opus-4-1":   {"in": 15.00, "out": 75.00, "cache_create": 18.75, "cache_read": 1.50},
+    "claude-opus-4":     {"in": 15.00, "out": 75.00, "cache_create": 18.75, "cache_read": 1.50},
+    "claude-sonnet-4-6": {"in":  3.00, "out": 15.00, "cache_create":  3.75, "cache_read": 0.30},
+    "claude-sonnet-4-5": {"in":  3.00, "out": 15.00, "cache_create":  3.75, "cache_read": 0.30},
+    "claude-sonnet-4":   {"in":  3.00, "out": 15.00, "cache_create":  3.75, "cache_read": 0.30},
+    "claude-haiku-4-5":  {"in":  1.00, "out":  5.00, "cache_create":  1.25, "cache_read": 0.10},
+    "claude-haiku-3-5":  {"in":  0.80, "out":  4.00, "cache_create":  1.00, "cache_read": 0.08},
+    "claude-3-5-sonnet": {"in":  3.00, "out": 15.00, "cache_create":  3.75, "cache_read": 0.30}
+  }
+}

package/lib/prices_fetcher.py

@@ -0,0 +1,285 @@
+"""
+prices_fetcher — fetch + parse + diff + write Claude API pricing snapshots.
+
+US-VIEW-013: replaces the hardcoded PRICES table in ``model_prices.py`` with
+versioned JSON snapshots under ``lib/prices/``. The fetcher pulls the live
+pricing docs page, extracts the model rate rows, and writes a new snapshot
+only when the rates differ from the most recent one on disk.
+
+Design:
+  * ``fetch_pricing_html(url, timeout)`` — pure I/O, raises ``FetchError``
+  * ``parse_pricing_html(html)`` — pure parser, raises ``ParseError``
+  * ``diff_prices(old, new)`` — pure diff, returns list of changes
+  * ``write_snapshot(prices, ...)`` — pure I/O, returns the path written
+  * ``refresh(...)`` — orchestrator; the only function with side effects on
+                       both network and disk
+"""
+
+from __future__ import annotations
+
+import datetime as _dt
+import json
+import os
+import re
+import sys
+from html.parser import HTMLParser
+from typing import Any, Dict, List, Optional, Tuple
+from urllib.error import URLError
+from urllib.request import Request, urlopen
+
+DEFAULT_SOURCE_URL = "https://platform.claude.com/docs/en/about-claude/pricing"
+DEFAULT_TIMEOUT = 15
+
+_MODEL_RE = re.compile(r"claude-(?:opus|sonnet|haiku)-[0-9](?:-[0-9])?")
+_DOLLAR_RE = re.compile(r"\$\s*([0-9]+(?:\.[0-9]+)?)")
+
+
+class FetchError(RuntimeError):
+    """Raised when fetching the pricing page fails."""
+
+
+class ParseError(ValueError):
+    """Raised when the pricing HTML cannot be parsed into a prices map."""
+
+
+def fetch_pricing_html(url: str = DEFAULT_SOURCE_URL,
+                       timeout: float = DEFAULT_TIMEOUT) -> str:
+    """Fetch the pricing docs page and return its raw HTML."""
+    req = Request(url, headers={"User-Agent": "roll/prices_fetcher"})
+    try:
+        with urlopen(req, timeout=timeout) as resp:
+            data = resp.read()
+            charset = resp.headers.get_content_charset() or "utf-8"
+            return data.decode(charset, errors="replace")
+    except (URLError, OSError, TimeoutError) as exc:
+        raise FetchError(f"could not fetch {url}: {exc}") from exc
+
+
+class _TableTextExtractor(HTMLParser):
+    """Walk an HTML document and yield <tr> cell-text lists per row."""
+
+    def __init__(self) -> None:
+        super().__init__()
+        self.rows: List[List[str]] = []
+        self._in_row = False
+        self._in_cell = False
+        self._cells: List[str] = []
+        self._cur: List[str] = []
+
+    def handle_starttag(self, tag: str, attrs):  # noqa: ANN001
+        if tag == "tr":
+            self._in_row = True
+            self._cells = []
+        elif tag in ("td", "th") and self._in_row:
+            self._in_cell = True
+            self._cur = []
+
+    def handle_endtag(self, tag: str) -> None:
+        if tag in ("td", "th") and self._in_cell:
+            self._cells.append(" ".join(self._cur).strip())
+            self._in_cell = False
+        elif tag == "tr" and self._in_row:
+            if self._cells:
+                self.rows.append(self._cells)
+            self._in_row = False
+
+    def handle_data(self, data: str) -> None:
+        if self._in_cell:
+            self._cur.append(data)
+
+
+def parse_pricing_html(html: str) -> Dict[str, Dict[str, float]]:
+    """Parse pricing docs HTML into a {model: rates} map.
+
+    The parser is intentionally tolerant: it scans every table row, looks for
+    one ``claude-*`` model identifier and four dollar amounts on that row, and
+    treats them as ``in / cache_create / cache_read / out`` in the order they
+    appear. (Anthropic's table renders columns in that order.)
+    """
+    parser = _TableTextExtractor()
+    parser.feed(html)
+
+    prices: Dict[str, Dict[str, float]] = {}
+    for row in parser.rows:
+        text = " ".join(row)
+        model_match = _MODEL_RE.search(text)
+        if not model_match:
+            continue
+        model = model_match.group(0)
+        amounts = [float(m.group(1)) for m in _DOLLAR_RE.finditer(text)]
+        if len(amounts) < 4:
+            continue
+        in_rate, cache_create, cache_read, out_rate = amounts[:4]
+        prices[model] = {
+            "in": in_rate,
+            "out": out_rate,
+            "cache_create": cache_create,
+            "cache_read": cache_read,
+        }
+
+    if not prices:
+        raise ParseError("no price rows found in HTML; page layout may have changed")
+    return prices
+
+
+def diff_prices(old: Dict[str, Dict[str, float]],
+                new: Dict[str, Dict[str, float]]
+                ) -> List[Tuple[str, str, str, Optional[float], Optional[float]]]:
+    """Return a list of (kind, model, field, old_val, new_val) tuples.
+
+    kind is one of: ``added``, ``removed``, ``changed``. For added rows the
+    old_val is None; for removed, the new_val is None.
+    """
+    changes: List[Tuple[str, str, str, Optional[float], Optional[float]]] = []
+    for model in sorted(set(old) | set(new)):
+        if model not in old:
+            for field, val in new[model].items():
+                changes.append(("added", model, field, None, val))
+            continue
+        if model not in new:
+            for field, val in old[model].items():
+                changes.append(("removed", model, field, val, None))
+            continue
+        for field in sorted(set(old[model]) | set(new[model])):
+            old_val = old[model].get(field)
+            new_val = new[model].get(field)
+            if old_val != new_val:
+                changes.append(("changed", model, field, old_val, new_val))
+    return changes
+
+
+def format_diff(changes: List[Tuple[str, str, str, Optional[float], Optional[float]]],
+                colored: bool = True) -> str:
+    """Render diff_prices output as red-/green-coded lines."""
+    if not changes:
+        return ""
+    red = "\033[31m" if colored else ""
+    green = "\033[32m" if colored else ""
+    dim = "\033[2m" if colored else ""
+    reset = "\033[0m" if colored else ""
+    lines: List[str] = []
+    for kind, model, field, old, new in changes:
+        if kind == "added":
+            lines.append(f"{green}+ {model} {field} = {new}{reset}")
+        elif kind == "removed":
+            lines.append(f"{red}- {model} {field} = {old}{reset}")
+        else:
+            lines.append(f"{dim}~ {model} {field}{reset} {red}{old}{reset} → {green}{new}{reset}")
+    return "\n".join(lines)
+
+
+def write_snapshot(prices: Dict[str, Dict[str, float]],
+                   *,
+                   snapshot_dir: str,
+                   source_url: str = DEFAULT_SOURCE_URL,
+                   effective_at: Optional[str] = None,
+                   default_model: Optional[str] = None,
+                   notes: Optional[str] = None) -> str:
+    """Write a new snapshot JSON and return its path."""
+    os.makedirs(snapshot_dir, exist_ok=True)
+    today = effective_at or _dt.date.today().isoformat()
+    payload: Dict[str, Any] = {
+        "version": today,
+        "effective_at": today,
+        "source_url": source_url,
+        "default_model": default_model or _pick_default(prices),
+        "prices": prices,
+    }
+    if notes:
+        payload["notes"] = notes
+    dest = os.path.join(snapshot_dir, f"snapshot-{today}.json")
+    with open(dest, "w", encoding="utf-8") as f:
+        json.dump(payload, f, indent=2, sort_keys=False)
+        f.write("\n")
+    return dest
+
+
+def _pick_default(prices: Dict[str, Dict[str, float]]) -> str:
+    """Pick a sensible fallback model: prefer the cheapest sonnet, else first key."""
+    for k in prices:
+        if "sonnet" in k:
+            return k
+    return next(iter(prices))
+
+
+def refresh(*,
+            snapshot_dir: str,
+            url: str = DEFAULT_SOURCE_URL,
+            timeout: float = DEFAULT_TIMEOUT,
+            html: Optional[str] = None,
+            ) -> Tuple[str, List[Tuple[str, str, str, Optional[float], Optional[float]]]]:
+    """Fetch (or accept fixture HTML), parse, diff against latest snapshot, write.
+
+    Returns (action, changes) where action is one of:
+      ``"unchanged"`` — no diff vs latest snapshot, nothing written
+      ``"written:<path>"`` — new snapshot written at <path>
+      ``"first:<path>"`` — no prior snapshot existed; baseline written
+    """
+    if html is None:
+        html = fetch_pricing_html(url, timeout=timeout)
+    new_prices = parse_pricing_html(html)
+
+    # Load latest if any
+    latest = _latest_snapshot_path(snapshot_dir)
+    if latest is None:
+        dest = write_snapshot(new_prices, snapshot_dir=snapshot_dir, source_url=url)
+        return f"first:{dest}", diff_prices({}, new_prices)
+
+    with open(latest, "r", encoding="utf-8") as f:
+        old = json.load(f).get("prices", {})
+    changes = diff_prices(old, new_prices)
+    if not changes:
+        return "unchanged", []
+    dest = write_snapshot(new_prices, snapshot_dir=snapshot_dir, source_url=url)
+    return f"written:{dest}", changes
+
+
+def _latest_snapshot_path(snapshot_dir: str) -> Optional[str]:
+    if not os.path.isdir(snapshot_dir):
+        return None
+    snaps = sorted(
+        os.path.join(snapshot_dir, n)
+        for n in os.listdir(snapshot_dir)
+        if n.startswith("snapshot-") and n.endswith(".json")
+    )
+    return snaps[-1] if snaps else None
+
+
+# CLI entry — `python3 lib/prices_fetcher.py refresh|show` is the fallback when
+# bin/roll is unavailable (e.g. running tests directly).
+def _main(argv: List[str]) -> int:
+    snapshot_dir = os.path.join(os.path.dirname(os.path.abspath(__file__)), "prices")
+    if not argv or argv[0] in ("-h", "--help", "help"):
+        print("usage: prices_fetcher.py refresh|show [--url URL]")
+        return 0
+    cmd = argv[0]
+    url = DEFAULT_SOURCE_URL
+    if "--url" in argv:
+        url = argv[argv.index("--url") + 1]
+    if cmd == "show":
+        latest = _latest_snapshot_path(snapshot_dir)
+        if not latest:
+            print("no snapshot found", file=sys.stderr)
+            return 1
+        with open(latest) as f:
+            print(f.read())
+        return 0
+    if cmd == "refresh":
+        try:
+            action, changes = refresh(snapshot_dir=snapshot_dir, url=url)
+        except FetchError as exc:
+            print(f"fetch failed: {exc}", file=sys.stderr)
+            return 2
+        except ParseError as exc:
+            print(f"parse failed: {exc}", file=sys.stderr)
+            return 3
+        print(action)
+        if changes:
+            print(format_diff(changes, colored=sys.stdout.isatty()))
+        return 0
+    print(f"unknown command: {cmd}", file=sys.stderr)
+    return 1
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(_main(sys.argv[1:]))