@vibelord/lanes 1.0.0 → 1.0.2

package/payload/lanes/libexec/economy_poll.py

@@ -0,0 +1,685 @@
+"""Per-lane Throttle economy: the request-outcome log fold (file reads only) and the opt-in `economy.json` poller.
+
+This module folds the `request outcome` events the proxy logs for every request into per-trace day totals
+(requests, paid requests, the four token classes, failures, models) and joins them to lanes. Tokens and paid
+request counts are authoritative; dollars are never computed here (no lanes-side pricing table — the poller's
+`list_usd_estimate` comes from the daemon or stays null, plan Global Constraints).
+
+Log layout, MEASURED 2026-10-04 (read-only, ~/.local/share/throttle on this host):
+  * `proxy.log.<YYYY-MM-DD>` — the daily JSON appender's file, one `{"timestamp", "level", "fields": {...}}` object
+    per line. TODAY's file is written live all day; a day's file is complete once the next day's exists. Nine days
+    were retained.
+  * `proxy.log` — an ANSI-coloured `key=value` text copy of the same events (`<ts>  INFO request outcome
+    request_id=… account=… trace=… failure=None …`), beginning at the current day's first event.
+Both files carry every outcome, so a day is folded from exactly ONE source: its `proxy.log.<day>` when it exists,
+else `proxy.log` while that file's first line is of that day. Folding both would double count.
+
+The cursor is plain JSON (the poller persists it): `{"v": 1, "days": {day: {"src": [dev, ino], "offset": int,
+"totals": {...}, "done": bool}}}`. A source is followed by file identity, not by name, so a file renamed to
+`proxy.log.<day>` continues at its offset; the offset advances only through the last complete line, so a line the
+writer is still flushing is read next time. A day is frozen (`done`) once a later day's log exists — its totals then
+survive the retention prune of its file.
+
+Trace keys: `cc-session/<id>` and `codex-session/<id>` (first two segments of the harness trace), `lanes/<ws>/<id>`
+(the lane-stamped header, Task 7) and, for any other trace, its first segment; a request without a trace is
+`UNTRACED`, a key the proxy's trace charset (`[A-Za-z0-9._-/]`) cannot produce.
+
+The poller (plan Task 11, opt-in `lanes-economy.service`; enabling it is an operator gate because it reads the
+production daemon's loopback control port): every `--interval` seconds it GETs `/status` and `/sessions` (3 s
+timeout, optional bearer from `LANES_THROTTLE_TOKEN_FILE`), folds today's log through `day_totals`, and writes
+`STATE/economy.json` (schema `v: 1`, additive) only when the payload changed apart from `at` — or when the file's
+`at` is HEARTBEAT seconds old, so `at` is a liveness heartbeat the sidebar ages with its own clock (DEF-1447); the
+cursor lives in `STATE/economy.cursor.json`. `LANES_THROTTLE_CONTROL=none` disables every daemon request (the log fold still runs);
+`--status-file`/`--sessions-file` feed fixture documents instead. A failed `/status` keeps the previous `fleet` with
+`stale: true`; a failed `/sessions` keeps each lane's previous live figures with `stale: true`. GET requests only:
+nothing here can change the daemon.
+
+Where it runs: `lanes-economy.service` is a HOST user unit, while the daemon (its log and its control port) lives in a
+workspace container. `LANES_THROTTLE_CONTAINER=<name>` reads the log through that container's home volume
+(`lanes_lib.host_path` of `/home/coder/.local/share/throttle`, the home recorded in `STATE/containers.json` by
+`lanes sync`); an explicit `LANES_THROTTLE_LOG_DIR` wins. The control URL must be reachable from the HOST's network
+namespace — a daemon bound to the container's 127.0.0.1 is not (DEF-1444). Why a source is down (`connection
+refused`, `timed out`, `HTTP 401`, `log dir missing`, ...) goes to stderr — the journal — each time it changes, and
+on every `--once`; it is never written into economy.json.
+"""
+import argparse
+import copy
+import json
+import os
+import re
+import sys
+import time
+import urllib.error
+import urllib.request
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+import lanes_lib as L  # noqa: E402
+
+ANSI = re.compile(r'\x1b\[[0-9;]*m')
+TEXT_HEAD = re.compile(r'^(\d{4}-\d\d-\d\dT\S+)\s+([A-Z]+)\s+(.*)$')
+TEXT_FIELD = re.compile(r'([A-Za-z_][A-Za-z0-9_]*)=("(?:[^"\\]|\\.)*"|\S+)')
+OUTCOME = 'request outcome'
+UNTRACED = '(untraced)'
+LIVE = 'proxy.log'
+DAY_FILE = re.compile(r'^proxy\.log\.(\d{4}-\d\d-\d\d)$')
+SESSION_PREFIXES = ('cc-session', 'codex-session')
+INT_FIELDS = ('status', 'input_tokens', 'output_tokens', 'cache_read_tokens', 'cache_creation_tokens')
+TOKENS = (('input', 'input_tokens'), ('output', 'output_tokens'),
+          ('cache_read', 'cache_read_tokens'), ('cache_write', 'cache_creation_tokens'))
+CHUNK = 4 << 20
+CURSOR_VERSION = 1
+CURSOR_DAYS = 10                     # day entries kept in the cursor: the daemon retains nine days of logs
+SCHEMA = 1
+DEFAULT_CONTROL = 'http://127.0.0.1:19181'
+DEFAULT_LOG_DIR = '~/.local/share/throttle'
+CONTAINER_LOG_DIR = L.CONTAINER_HOME + '/.local/share/throttle'   # the daemon's log dir inside its container
+TIMEOUT = 3
+HEARTBEAT = 60                       # seconds: economy.json is rewritten at least this often (sidebar ECONOMY_STALE = 3x)
+ECONOMY = 'economy.json'
+CURSOR = 'economy.cursor.json'
+FLEET_KEYS = ('overflow_spend_today_usd', 'overflow_budget_usd', 'spent_fraction', 'alert_level_pct',
+              'pressure_phase', 'spill_fraction', 'effective_free', 'accounts', 'soonest_reset_5h',
+              'upstream_429_delta', 'paid_in_flight', 'sub_in_flight', 'fable_sustainable_rpm')
+LIVE_KEYS = ('model', 'requested_model', 'paid_share', 'usd_per_hour', 'tok_per_min', 'cache_read_ratio',
+             'downgraded_5m', 'status_429', 'last_request_age_s')
+
+
+def trace_key(trace):
+    if not trace:
+        return UNTRACED
+    segs = trace.split('/')
+    if segs[0] == 'lanes' and len(segs) >= 3:
+        return '/'.join(segs[:3])
+    if segs[0] in SESSION_PREFIXES and len(segs) >= 2:
+        return '/'.join(segs[:2])
+    return segs[0]
+
+
+def is_paid(account, paid_accounts=None):
+    """The overflow lane is the paid route. The daemon names its synthesized overflow account `<pool>/api-overflow`
+    (src/config.rs; `throttle accounts` filters on the same suffix); a configured name is passed as paid_accounts."""
+    if not account:
+        return False
+    if paid_accounts is not None:
+        return account in paid_accounts
+    return account.rsplit('/', 1)[-1] == 'api-overflow'
+
+
+def _int(v):
+    try:
+        return int(v)
+    except (TypeError, ValueError):
+        return 0
+
+
+def parse_line(line):
+    """(timestamp, fields) of one request-outcome line, JSON or tracing text, ANSI tolerated; else None."""
+    s = ANSI.sub('', line).strip()
+    if not s:
+        return None
+    if s.startswith('{'):
+        try:
+            o = json.loads(s)
+        except ValueError:
+            return None
+        f = o.get('fields') if isinstance(o, dict) else None
+        if not isinstance(f, dict) or f.get('message') != OUTCOME or not isinstance(o.get('timestamp'), str):
+            return None
+        return o['timestamp'], f
+    m = TEXT_HEAD.match(s)
+    if not m:
+        return None
+    rest = m.group(3)
+    if not rest.startswith(OUTCOME + ' ') and rest != OUTCOME:
+        return None
+    fields = {}
+    for k, v in TEXT_FIELD.findall(rest[len(OUTCOME):]):
+        if len(v) >= 2 and v[0] == '"' and v[-1] == '"':
+            v = v[1:-1]
+        fields[k] = _int(v) if k in INT_FIELDS else v
+    return m.group(1), fields
+
+
+def _record():
+    return {'req': 0, 'paid_req': 0, 'input': 0, 'output': 0, 'cache_read': 0, 'cache_write': 0, 'failures': 0,
+            'last_ts': None, 'models': {}}
+
+
+def fold_outcomes(lines, day, paid_accounts=None, into=None):
+    """Fold request-outcome lines of `day` (UTC, `YYYY-MM-DD`) into {trace_key: totals}; other lines are ignored."""
+    totals = {} if into is None else into
+    for line in lines:
+        parsed = parse_line(line)
+        if not parsed:
+            continue
+        ts, f = parsed
+        if not ts.startswith(day):
+            continue
+        r = totals.setdefault(trace_key(f.get('trace')), _record())
+        r['req'] += 1
+        if is_paid(f.get('account'), paid_accounts):
+            r['paid_req'] += 1
+        for key, field in TOKENS:
+            r[key] += _int(f.get(field))
+        if f.get('failure') not in (None, '', 'None'):
+            r['failures'] += 1
+        if r['last_ts'] is None or ts > r['last_ts']:
+            r['last_ts'] = ts
+        model = f.get('model')
+        if model:
+            r['models'][model] = r['models'].get(model, 0) + 1
+    return totals
+
+
+def _head_day(path):
+    try:
+        with open(path, 'rb') as fh:
+            first = fh.readline(65536)
+    except OSError:
+        return None
+    s = ANSI.sub('', first.decode('utf-8', 'replace')).strip()
+    if s.startswith('{'):
+        try:
+            ts = json.loads(s).get('timestamp')
+        except (ValueError, AttributeError):
+            return None
+        return ts[:10] if isinstance(ts, str) else None
+    m = TEXT_HEAD.match(s)
+    return m.group(1)[:10] if m else None
+
+
+def _scan(log_dir):
+    """({day: path} of the day files, live path or None)."""
+    days = {}
+    try:
+        names = os.listdir(log_dir)
+    except OSError:
+        return days, None
+    for name in names:
+        m = DAY_FILE.match(name)
+        if m:
+            days[m.group(1)] = Path(log_dir) / name
+    live = Path(log_dir) / LIVE
+    return days, (live if LIVE in names else None)
+
+
+def _fold_file(path, entry, day, paid_accounts, final):
+    """Fold bytes of `path` past entry['offset'] up to the last newline (to EOF when `final`); advance the offset."""
+    try:
+        fh = open(path, 'rb')
+    except OSError:
+        return
+    with fh:
+        fh.seek(entry['offset'])
+        pending = b''
+        while True:
+            chunk = fh.read(CHUNK)
+            if not chunk:
+                break
+            data = pending + chunk
+            cut = data.rfind(b'\n') + 1
+            if cut:
+                fold_outcomes(data[:cut].decode('utf-8', 'replace').splitlines(), day, paid_accounts,
+                              into=entry['totals'])
+                entry['offset'] += cut
+            pending = data[cut:]
+        if final and pending:
+            fold_outcomes([pending.decode('utf-8', 'replace')], day, paid_accounts, into=entry['totals'])
+            entry['offset'] += len(pending)
+
+
+def day_totals(log_dir, day, cursor, paid_accounts=None):
+    """(totals for `day`, new cursor). Reads only bytes appended since `cursor`; the input cursor is not mutated."""
+    cur = copy.deepcopy(cursor) if isinstance(cursor, dict) and cursor.get('v') == CURSOR_VERSION else {}
+    cur['v'] = CURSOR_VERSION
+    days = cur.setdefault('days', {})
+    entry = days.get(day)
+    if entry and entry.get('done'):
+        return copy.deepcopy(entry['totals']), cur
+    entry = entry or {'src': None, 'offset': 0, 'totals': {}, 'done': False}
+
+    day_files, live = _scan(log_dir)
+    live_day = _head_day(live) if live else None
+    later = any(d > day for d in day_files) or (live_day is not None and live_day > day)
+    src = day_files.get(day) or (live if live_day == day else None)
+    if src is not None:
+        try:
+            st = os.stat(src)
+        except OSError:
+            src = None
+    if src is not None:
+        ident = [st.st_dev, st.st_ino]
+        if entry['src'] == ident:
+            if st.st_size < entry['offset']:      # truncated in place: its earlier bytes are counted and gone
+                entry['offset'] = 0
+        else:
+            if src.name != LIVE:                   # a day file is the whole-day record: it replaces, never adds
+                entry['totals'] = {}
+            entry['src'], entry['offset'] = ident, 0
+        _fold_file(src, entry, day, paid_accounts, final=later)
+    if later:
+        entry['done'] = True
+    days[day] = entry
+    return copy.deepcopy(entry['totals']), cur
+
+
+def _add(acc, rec):
+    for k, v in rec.items():
+        if isinstance(v, bool) or v is None:
+            continue
+        if isinstance(v, (int, float)):
+            acc[k] = acc.get(k, 0) + v
+        elif isinstance(v, dict):
+            _add(acc.setdefault(k, {}), v)
+        elif isinstance(v, str):
+            if acc.get(k) is None or v > acc[k]:
+                acc[k] = v
+
+
+def join_to_lanes(totals, lanes_by_session, lanes_by_trace):
+    """{lane_id: summed totals} over every trace key whose session id (`agent.session_id`, Task 5) or lane-stamped
+    key (`lanes/<ws>/<id>`, Task 7) maps to a lane; keys that map to no lane are dropped."""
+    out = {}
+    for key, rec in totals.items():
+        prefix, _, rest = key.partition('/')
+        if prefix == 'lanes':
+            lane = lanes_by_trace.get(key)
+        elif prefix in SESSION_PREFIXES:
+            lane = lanes_by_session.get(rest)
+        else:
+            lane = None
+        if lane:
+            _add(out.setdefault(lane, {}), rec)
+    return out
+
+
+# ------------------------------------------------------------------ the poller (plan Task 11)
+
+def _num(value):
+    return value if isinstance(value, (int, float)) and not isinstance(value, bool) else None
+
+
+def _get(doc, *path):
+    for key in path:
+        if not isinstance(doc, dict):
+            return None
+        doc = doc.get(key)
+    return doc
+
+
+def fleet_strip(status_json, prev_429_total=None, now=None):
+    """The fleet strip from one `GET /status` body (src/proxy.rs `status_body`): exactly FLEET_KEYS, None for any
+    absent field. `overflow_budget_usd` is the ENFORCED cap (`effective_daily_budget_usd`, which an emergency ceiling
+    can only lower). `upstream_429_delta` is the growth of `pressure.upstream_429_total` since `prev_429_total` (None
+    without one, or when the total fell: a restarted daemon began counting again). `soonest_reset_5h` is the
+    earliest account 5 h reset (epoch seconds) after `now` (every reset when `now` is None). `sub_in_flight` is
+    `pressure.in_flight - pressure.overflow_in_flight` — INFERRED from src/proxy.rs (an overflow request holds a pool
+    permit as well as its overflow permit), not measured on a live daemon."""
+    s = status_json if isinstance(status_json, dict) else {}
+    accounts = s.get('accounts') if isinstance(s.get('accounts'), list) else None
+    resets = [r for r in (_num(_get(a, 'reset_5h')) for a in accounts or ()) if r is not None and (now is None or r > now)]
+    total = _num(_get(s, 'pressure', 'upstream_429_total'))
+    prev = _num(prev_429_total)
+    in_flight, paid = _num(_get(s, 'pressure', 'in_flight')), _num(_get(s, 'pressure', 'overflow_in_flight'))
+    phase = _get(s, 'pressure', 'phase')
+    return {
+        'overflow_spend_today_usd': _num(_get(s, 'overflow', 'spend_today_usd')),
+        'overflow_budget_usd': _num(_get(s, 'overflow', 'effective_daily_budget_usd')),
+        'spent_fraction': _num(_get(s, 'overflow', 'spent_fraction')),
+        'alert_level_pct': _num(_get(s, 'overflow', 'budget_alert_level_pct')),
+        'pressure_phase': phase if isinstance(phase, str) else None,
+        'spill_fraction': _num(_get(s, 'pressure', 'spill_fraction')),
+        'effective_free': _num(s.get('effective_free')),
+        'accounts': len(accounts) if accounts is not None else None,
+        'soonest_reset_5h': min(resets) if resets else None,
+        'upstream_429_delta': total - prev if total is not None and prev is not None and total >= prev else None,
+        'paid_in_flight': paid,
+        'sub_in_flight': max(0, in_flight - paid) if in_flight is not None and paid is not None else None,
+        'fable_sustainable_rpm': _num(_get(s, 'fable_governor', 'sustainable_rpm')),
+    }
+
+
+def lane_for(session_id, trace, lanes_by_session, lanes_by_trace):
+    """The lane a request row or session group belongs to: its lane-stamped trace (exact), else its session id,
+    else the session id inside a `cc-session/…`/`codex-session/…` trace; None when nothing maps."""
+    key = trace_key(trace if isinstance(trace, str) else '')
+    prefix, _, rest = key.partition('/')
+    if prefix == 'lanes' and key in lanes_by_trace:
+        return lanes_by_trace[key]
+    if isinstance(session_id, str) and session_id and session_id in lanes_by_session:
+        return lanes_by_session[session_id]
+    if prefix in SESSION_PREFIXES:
+        return lanes_by_session.get(rest)
+    return None
+
+
+def per_lane_live(sessions_json, status_json, lanes_by_session, lanes_by_trace):
+    """{lane_id: live figures} from the `GET /sessions` `SessionGroup` rows (src/proxy.rs) of every group that maps to
+    a lane, summed over a lane's groups (sub-agents are groups of their own); `model`/`requested_model` come from the
+    lane's newest group. `status_429` and `cache_read_ratio` (cache reads over all prompt tokens) come from
+    `status.recent_requests`, the same 200-request ring. Lanes without a group are absent."""
+    groups = _get(sessions_json, 'sessions')
+    if not isinstance(groups, list):
+        return {}
+    now_ms = _num(_get(sessions_json, 'now_ms'))
+    acc = {}
+    for g in groups:
+        if not isinstance(g, dict):
+            continue
+        lane = lane_for(g.get('session_id'), g.get('trace'), lanes_by_session, lanes_by_trace)
+        if not lane:
+            continue
+        a = acc.setdefault(lane, {'req': 0, 'paid': 0, 'usd': 0.0, 'tpm': 0.0, 'down': 0, 'newest': None,
+                                  'model': None, 'requested_model': None})
+        a['req'] += _num(g.get('req_count')) or 0
+        a['paid'] += _num(g.get('paid_count')) or 0
+        a['usd'] += _num(g.get('usd_per_hour')) or 0.0
+        a['tpm'] += _num(g.get('tok_per_min')) or 0.0
+        a['down'] += _num(g.get('downgraded_5m')) or 0
+        last = _num(g.get('last_ts_ms'))
+        if last is not None and (a['newest'] is None or last > a['newest']):
+            a['newest'] = last
+            a['model'] = g.get('model') if isinstance(g.get('model'), str) else None
+            a['requested_model'] = g.get('requested_model') if isinstance(g.get('requested_model'), str) else None
+    ring = {}
+    rows = _get(status_json, 'recent_requests')
+    for row in rows if isinstance(rows, list) else ():
+        if not isinstance(row, dict):
+            continue
+        lane = lane_for(row.get('session_id'), row.get('trace'), lanes_by_session, lanes_by_trace)
+        if lane not in acc:
+            continue
+        r = ring.setdefault(lane, {'429': 0, 'read': 0, 'prompt': 0})
+        if _num(row.get('status')) == 429:
+            r['429'] += 1
+        read = _num(row.get('cache_read_tokens')) or 0
+        r['read'] += read
+        r['prompt'] += read + (_num(row.get('input_tokens')) or 0) + (_num(row.get('cache_creation_tokens')) or 0)
+    out = {}
+    for lane, a in acc.items():
+        r = ring.get(lane, {'429': 0, 'read': 0, 'prompt': 0})
+        out[lane] = {
+            'model': a['model'], 'requested_model': a['requested_model'],
+            'paid_share': round(a['paid'] / a['req'], 4) if a['req'] else None,
+            'usd_per_hour': round(a['usd'], 4), 'tok_per_min': round(a['tpm'], 1),
+            'cache_read_ratio': round(r['read'] / r['prompt'], 4) if r['prompt'] else None,
+            'downgraded_5m': a['down'], 'status_429': r['429'],
+            'last_request_age_s': (max(0, round((now_ms - a['newest']) / 1000))
+                                   if now_ms is not None and a['newest'] is not None else None),
+            'ring_req': a['req'],
+        }
+    return out
+
+
+def lane_maps(status_doc, registry):
+    """(lanes_by_session, lanes_by_trace) from status.json (`agent.session_id`, or `agent.session` when a hook sidecar
+    supplied the agent) and the registry's workspaces (`lanes/<ws>/<id>`, lanes_lib.lane_trace)."""
+    by_session, by_trace = {}, {}
+    lanes = _get(status_doc, 'lanes')
+    for lane_id, entry in (lanes.items() if isinstance(lanes, dict) else ()):
+        agent = _get(entry, 'agent')
+        sid = _get(agent, 'session_id') or _get(agent, 'session')
+        if isinstance(sid, str) and sid:
+            by_session[sid] = lane_id
+    workspaces = _get(registry, 'workspaces')
+    for ws in workspaces if isinstance(workspaces, list) else ():
+        for lane in _get(ws, 'lanes') or ():
+            trace = L.lane_trace(_get(lane, 'id'), _get(ws, 'id'))
+            if trace:
+                by_trace[trace] = lane['id']
+    return by_session, by_trace
+
+
+def control_url(env):
+    """The control base URL, or None when LANES_THROTTLE_CONTROL is `none`/`off`/empty."""
+    value = str(env.get('LANES_THROTTLE_CONTROL', DEFAULT_CONTROL)).strip()
+    if value.lower() in ('', 'none', 'off'):
+        return None
+    if not value.startswith(('http://', 'https://')):
+        raise L.LanesError(f'LANES_THROTTLE_CONTROL must be an http(s) URL or none, not {value!r}')
+    return value.rstrip('/')
+
+
+def read_token(env):
+    """The optional bearer (loopback without `remote_key` needs none). Never logged, never written anywhere."""
+    path = env.get('LANES_THROTTLE_TOKEN_FILE')
+    if not path:
+        return None
+    try:
+        return Path(os.path.expanduser(path)).read_text().strip() or None
+    except OSError as error:
+        print(f'economy_poll: token file unreadable ({error.strerror}); polling without a bearer', file=sys.stderr)
+        return None
+
+
+class _NoRedirect(urllib.request.HTTPRedirectHandler):
+    def redirect_request(self, *_args, **_kwargs):   # a redirect would carry the bearer elsewhere: refuse it
+        return None
+
+
+def default_opener():
+    """urllib without environment proxies (a loopback poll must never go through http_proxy) and without redirects."""
+    return urllib.request.build_opener(urllib.request.ProxyHandler({}), _NoRedirect()).open
+
+
+MAX_BODY = 32 << 20
+
+
+def fetch(control, path, token=None, opener=None, timeout=TIMEOUT):
+    """GET `<control>/<path>` → (the decoded JSON object, None), or (None, why) on any failure. `why` names the failure
+    class (`connection refused`, `timed out`, `HTTP 401`, `not JSON`, ...) and the URL — never the bearer."""
+    url = f'{control}/{path}'
+    request = urllib.request.Request(url, headers={'Accept': 'application/json'})
+    if token:
+        request.add_header('Authorization', f'Bearer {token}')
+    try:
+        with (opener or default_opener())(request, timeout=timeout) as response:
+            body = response.read(MAX_BODY + 1)
+        if len(body) > MAX_BODY:
+            return None, f'body over {MAX_BODY >> 20} MiB ({url})'
+        doc = json.loads(body)
+    except Exception as error:   # the daemon may be down, restarting or slow: the poll degrades, never dies
+        return None, f'{failure_class(error)} ({url})'
+    return (doc, None) if isinstance(doc, dict) else (None, f'not a JSON object ({url})')
+
+
+def failure_class(error):
+    """A short, secret-free name for why a GET failed."""
+    if isinstance(error, urllib.error.HTTPError):
+        return f'HTTP {error.code}'          # a refused redirect lands here too (3xx)
+    if isinstance(error, urllib.error.URLError):
+        reason = error.reason
+        return failure_class(reason) if isinstance(reason, BaseException) else f'unreachable: {reason}'
+    if isinstance(error, ConnectionRefusedError):
+        return 'connection refused'
+    if isinstance(error, TimeoutError):
+        return 'timed out'
+    if isinstance(error, ValueError):        # JSONDecodeError and UnicodeDecodeError are ValueErrors
+        return 'not JSON'
+    if isinstance(error, OSError):
+        return f'unreachable: {error.strerror or type(error).__name__}'
+    return type(error).__name__
+
+
+def fetch_json(control, path, token=None, opener=None, timeout=TIMEOUT):
+    """GET `<control>/<path>` → the decoded JSON object, or None on any failure (refused, timeout, HTTP error,
+    oversize, not an object)."""
+    return fetch(control, path, token, opener, timeout)[0]
+
+
+def fetch_status(control, token=None, opener=None):
+    return fetch_json(control, 'status', token, opener)
+
+
+def fetch_sessions(control, token=None, opener=None):
+    return fetch_json(control, 'sessions', token, opener)
+
+
+def _canonical(doc):
+    return json.dumps(doc, sort_keys=True, separators=(',', ':'))
+
+
+def _without_at(doc):
+    return {k: v for k, v in doc.items() if k != 'at'} if isinstance(doc, dict) else None
+
+
+def log_dir(env, state_dir):
+    """(the directory to fold, None) or (the directory or None, why it cannot be folded).
+
+    `LANES_THROTTLE_LOG_DIR` wins; else `LANES_THROTTLE_CONTAINER=<name>` maps the daemon's in-container log directory
+    through that container's home volume as `lanes sync` recorded it in STATE/containers.json (the host unit's own
+    `~/.local/share/throttle` is not the daemon's); else DEFAULT_LOG_DIR in this user's home."""
+    explicit = env.get('LANES_THROTTLE_LOG_DIR')
+    container = env.get('LANES_THROTTLE_CONTAINER')
+    if explicit:
+        path = Path(os.path.expanduser(str(explicit)))
+    elif container:
+        recorded = L.read_json(Path(state_dir) / 'containers.json')
+        info = recorded.get(container) if isinstance(recorded, dict) else None
+        if not isinstance(info, dict):
+            return None, f'container {container} is not in containers.json (lanes sync records board containers)'
+        try:
+            path = L.host_path(info, CONTAINER_LOG_DIR)
+        except L.LanesError as error:
+            return None, f'container {container}: {error}'
+    else:
+        path = Path(os.path.expanduser(DEFAULT_LOG_DIR))
+    try:
+        is_dir = path.is_dir()          # re-raises EACCES from an untraversable parent (a root-only docker volume)
+    except OSError as error:
+        return path, f'log dir unreadable: {path} ({error.strerror or type(error).__name__})'
+    if not is_dir:
+        return path, f'log dir missing: {path}'
+    if not os.access(path, os.R_OK | os.X_OK):
+        return path, f'log dir unreadable: {path}'
+    return path, None
+
+
+def report(diagnostics, last, stream=None, always=False):
+    """Print each source's failure class (or its recovery) to `stream` when it differs from `last` — or every one when
+    `always`; returns the new `last`. The journal says why `source` is false; economy.json never carries it."""
+    stream = stream or sys.stderr
+    last = last or {}
+    for name in ('status', 'sessions', 'log'):
+        why = diagnostics.get(name)
+        if why if always else why != last.get(name):
+            print(f'economy_poll: {name}: {why or "ok"}', file=stream, flush=True)
+    return dict(diagnostics)
+
+
+def poll_once(state_dir, env, opener=None, now=None, write=True, status_file=None, sessions_file=None,
+              diagnostics=None):
+    """One poll: the daemon (or fixture files), today's log fold and the lane maps → the economy.json v1 payload.
+    With `write`, economy.json is replaced only when the payload changed apart from `at` or its `at` is HEARTBEAT
+    seconds old (the liveness heartbeat, DEF-1447), and the cursor only when it changed. Never raises for a down daemon or a missing log; raises LanesError for a malformed control URL. A
+    `diagnostics` dict receives why each of status, sessions and log is unavailable (None when it answered)."""
+    state_dir = Path(state_dir)
+    now = int(time.time() if now is None else now)
+    day = time.strftime('%Y-%m-%d', time.gmtime(now))
+    control = control_url(env)
+    token = read_token(env) if control else None
+    previous = L.read_json(state_dir / ECONOMY)
+    previous = previous if isinstance(previous, dict) and previous.get('v') == SCHEMA else {}
+    cursor = L.read_json(state_dir / CURSOR)
+    cursor = cursor if isinstance(cursor, dict) and cursor.get('v') == CURSOR_VERSION else {'v': CURSOR_VERSION}
+
+    def load(path, name):
+        if path:
+            doc = L.read_json(path)
+            return (doc, None) if isinstance(doc, dict) else (None, f'fixture is not a JSON object: {path}')
+        if not control:
+            return None, 'not requested (LANES_THROTTLE_CONTROL=none)'
+        return fetch(control, name, token, opener)
+
+    status, status_why = load(status_file, 'status')
+    sessions, sessions_why = load(sessions_file, 'sessions')
+
+    folded_dir, log_why = log_dir(env, state_dir)
+    log_ok = log_why is None
+    if diagnostics is not None:
+        diagnostics.update(status=status_why, sessions=sessions_why, log=log_why)
+    if log_ok:
+        totals, new_cursor = day_totals(folded_dir, day, cursor)
+    else:
+        totals, new_cursor = {}, copy.deepcopy(cursor)
+    days = new_cursor.setdefault('days', {})
+    for old in sorted(days)[:-CURSOR_DAYS]:
+        del days[old]
+
+    if status is not None:
+        fleet = fleet_strip(status, cursor.get('upstream_429_total'), now)
+        total = _num(_get(status, 'pressure', 'upstream_429_total'))
+        if total is not None:
+            new_cursor['upstream_429_total'] = total
+    elif isinstance(previous.get('fleet'), dict) and any(
+            previous['fleet'].get(k) is not None for k in FLEET_KEYS):   # an all-unknown strip is not stale data
+        fleet = dict(previous['fleet'], stale=True)
+    else:
+        fleet = {k: None for k in FLEET_KEYS}
+
+    by_session, by_trace = lane_maps(L.read_json(state_dir / 'status.json'), L.read_json(state_dir / 'registry.json'))
+    lanes = {}
+    if sessions is not None:
+        lanes = per_lane_live(sessions, status, by_session, by_trace)
+    else:
+        for lane, rec in (previous.get('lanes') or {}).items():
+            if not isinstance(rec, dict):
+                continue
+            kept = {k: v for k, v in rec.items() if k not in ('day', 'stale')}
+            if any(v is not None for v in kept.values()):
+                lanes[lane] = dict(kept, stale=True)
+    for lane, record in join_to_lanes(totals, by_session, by_trace).items():
+        lanes.setdefault(lane, {})['day'] = dict(record, list_usd_estimate=None)
+    for record in lanes.values():
+        for key in LIVE_KEYS + ('ring_req',):
+            record.setdefault(key, None)
+
+    payload = {'v': SCHEMA, 'at': now,
+               'source': {'status_ok': status is not None, 'sessions_ok': sessions is not None, 'log_ok': log_ok},
+               'fleet': fleet, 'lanes': lanes}
+    if write:
+        written = previous.get('at')
+        beat = not isinstance(written, (int, float)) or isinstance(written, bool) or now - written >= HEARTBEAT
+        if beat or _canonical(_without_at(previous)) != _canonical(_without_at(payload)):
+            L.atomic_write(state_dir / ECONOMY, _canonical(payload) + '\n')
+        if _canonical(new_cursor) != _canonical(cursor):
+            L.atomic_write(state_dir / CURSOR, _canonical(new_cursor) + '\n')
+    return payload
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(prog='economy_poll', description='Throttle economy projection → economy.json')
+    parser.add_argument('--interval', type=float, default=10.0, help='seconds between polls (the unit uses 10)')
+    parser.add_argument('--once', action='store_true', help='poll once and print the projection')
+    parser.add_argument('--dry-run', action='store_true', help='with --once: write neither economy.json nor the cursor')
+    parser.add_argument('--status-file', help='read this /status fixture instead of the daemon')
+    parser.add_argument('--sessions-file', help='read this /sessions fixture instead of the daemon')
+    args = parser.parse_args(argv)
+    state = Path(os.environ.get('LANES_STATE') or L.STATE)
+    env = dict(os.environ)
+    if args.once or args.dry_run:
+        diagnostics = {}
+        payload = poll_once(state, env, write=not args.dry_run, status_file=args.status_file,
+                            sessions_file=args.sessions_file, diagnostics=diagnostics)
+        print(json.dumps(payload, indent=2, sort_keys=True))
+        report(diagnostics, None, always=True)
+        return 0
+    control_url(env)   # a malformed URL stops the unit at start, not once per tick
+    last = None
+    while True:
+        diagnostics = {}
+        try:
+            poll_once(state, env, status_file=args.status_file, sessions_file=args.sessions_file,
+                      diagnostics=diagnostics)
+            last = report(diagnostics, last)
+        except Exception as error:   # one bad tick is a journal line; the next tick tries again
+            print(f'economy_poll: {type(error).__name__}: {error}', file=sys.stderr, flush=True)
+        time.sleep(max(1.0, args.interval))
+
+
+if __name__ == '__main__':
+    try:
+        sys.exit(main())
+    except L.LanesError as error:
+        sys.exit(f'economy_poll: {error}')