claude-multiacc 2.0.50 → 2.0.52

package/lib/codex_credit_local_scope.py

@@ -0,0 +1,35 @@
+"""Non-secret local actor identity for shared Codex wallet refusal receipts."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from selector_credit_scope import actor_email, actor_key, actor_refusals
+
+
+def pool_actor(directory: Path) -> str | None:
+    try:
+        document = json.loads((directory.parent / "accounts.json").read_text())
+        accounts = document.get("accounts") or []
+    except (OSError, ValueError, AttributeError):
+        return None
+    for account in accounts:
+        if isinstance(account, dict) and account.get("id") == directory.name:
+            return actor_email({"credit_actor_email": account.get("email")})
+    return None
+
+
+def merged_local_refusals(directories, read_json, refusal_view):
+    candidates = []
+    for item in directories:
+        directory = Path(item)
+        candidates.append({"credits": read_json(directory / "limits.json").get("credits"),
+                           "runner_id": str(directory.parent.resolve()), "account_id": directory.name,
+                           "credit_actor_email": pool_actor(directory), **refusal_view(directory)})
+    return actor_refusals(candidates)
+
+
+def local_refusal_key(directory, credits):
+    return actor_key({"credits": credits, "credit_actor_email": pool_actor(directory),
+                      "runner_id": str(directory.parent.resolve()), "account_id": directory.name})

package/lib/codex_credit_selection.py

@@ -0,0 +1,172 @@
+"""Local Codex shim credit fallback and durable paid-refusal receipts.
+
+Only reads telemetry already collected by codex-accounts; never calls a provider.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+import time
+from datetime import datetime, timezone
+from pathlib import Path
+
+from selector_credits import balance_value, normalize_credits, refusal_recovered
+from selector_funding import credit_rank, wallet_snapshots
+from selector_credit_scope import actor_observations, merge_actor, merge_wallet
+from codex_credit_local_scope import pool_actor, merged_local_refusals, local_refusal_key
+from selector_primitives import canonical_sha256, timestamp
+
+
+def read_json(path):
+    try:
+        value = json.loads(path.read_text())
+        return value if isinstance(value, dict) else {}
+    except (OSError, ValueError):
+        return {}
+
+
+def write_json(path, value):
+    path.parent.mkdir(parents=True, exist_ok=True)
+    temporary = path.with_name(f"{path.name}.{os.getpid()}.tmp")
+    with temporary.open("w") as target:
+        os.chmod(temporary, 0o600)
+        json.dump(value, target, separators=(",", ":"))
+    temporary.replace(path)
+
+
+def marker_allows(directory, now):
+    try:
+        lines = (directory / ".limited").read_text().splitlines()
+        if float(lines[0]) <= now:
+            return True
+        fields = dict(item.split("=", 1) for item in lines[1].split() if "=" in item)
+        reason = fields.get("reason")
+        return reason in {"limits", "client-rate-limit"} or (
+            reason == "credit-refused" and bool(credit_refusal_view(directory)))
+    except FileNotFoundError:
+        return True
+    except (OSError, ValueError, IndexError):
+        return False
+
+
+def candidate(directory, now, wallets, refusals, observations):
+    data = read_json(directory / "limits.json")
+    credits = normalize_credits(data.get("credits"), datetime.fromtimestamp(now, timezone.utc))
+    credits = merge_actor(credits, observations.get(local_refusal_key(directory, credits)))
+    credits = merge_wallet(credits, wallets.get(credits["account_id"]))
+    refusal = dict(credit_refusal_view(directory), **refusals.get(local_refusal_key(directory, credits), {}))
+    if not credits["available"] or not refusal_recovered(refusal, credits, datetime.fromtimestamp(now, timezone.utc)):
+        return None
+    if not marker_allows(directory, now):
+        return None
+    # A paid fallback needs evidence that the subscription is exhausted. At90-99%
+    # the ordinary reserve still takes precedence and its existing gate/band apply.
+    values = [data.get(key) for key in ("weekly_percent", "session_percent")]
+    exhausted = any(isinstance(v, (int, float)) and not isinstance(v, bool) and v >= 100 for v in values)
+    if not exhausted and credits["ordinary_usage_allowed"] is not False:
+        return None
+    return {"directory": str(directory), "credits": credits, "credit_active_holders": 0}
+
+
+def active_holders(root, now, cleanup=False):
+    holders = {}
+    for record in root.glob("acct-*/.credit-sessions/*.json"):
+        data = read_json(record)
+        try:
+            pid = int(record.stem)
+            if pid <= 0 or now - float(data["launched_at"]) > 86400:
+                continue
+            os.kill(pid, 0)
+        except (KeyError, ValueError, OSError):
+            if cleanup:
+                record.unlink(missing_ok=True)
+            continue
+        account = data.get("account_id")
+        holders[account] = holders.get(account, 0) + 1
+    return holders
+
+
+def pick(now, directories):
+    snapshots = [dict(read_json(Path(directory) / "limits.json"),
+                      credit_actor_email=pool_actor(Path(directory)),
+                      runner_id=str(Path(directory).parent.resolve()), account_id=Path(directory).name)
+                 for directory in directories]
+    observations = actor_observations(snapshots, datetime.fromtimestamp(now, timezone.utc), 900)
+    wallets = wallet_snapshots(snapshots, datetime.fromtimestamp(now, timezone.utc), 900)
+    refusals = merged_local_refusals(directories, read_json, credit_refusal_view)
+    rows = [row for directory in directories
+            if (row := candidate(Path(directory), now, wallets, refusals, observations))]
+    if not rows:
+        return ""
+    holders = active_holders(Path(directories[0]).parent, now)
+    for row in rows:
+        row["credit_active_holders"] = holders.get(row["credits"]["account_id"], 0)
+    best = min(credit_rank(row) for row in rows)
+    rows = [row for row in rows if credit_rank(row) == best]
+    root = Path(directories[0]).parent
+    try:
+        previous = (root / ".last-pick").read_text().strip()
+    except OSError:
+        previous = ""
+    peers = [row for row in rows if Path(row["directory"]).name != previous] or rows
+    return min(peers, key=lambda row: canonical_sha256(
+        [str(now), str(os.getppid()), row["credits"]["account_id"], row["directory"]]))["directory"]
+
+
+def record_launch(directory, pid, now):
+    active_holders(directory.parent, now, cleanup=True)
+    credits = read_json(directory / "limits.json").get("credits") or {}
+    write_json(directory / ".credit-sessions" / f"{pid}.json", {
+        "account_id": credits.get("account_id"), "balance": credits.get("balance"), "launched_at": now,
+        "credit_actor_email": pool_actor(directory)})
+
+
+def record_refusal(directory, pid, now):
+    launch = read_json(directory / ".credit-sessions" / f"{pid}.json")
+    current = (read_json(directory / "limits.json").get("credits") or {})
+    balance = launch.get("balance")
+    if not launch:
+        balance = current.get("balance")
+    write_json(directory / ".credit-refused.json", {
+        "credit_blocked_at": datetime.fromtimestamp(now, timezone.utc).isoformat(),
+        "credit_blocked_balance": balance, "limited_reason": "credits",
+        "account_id": launch.get("account_id") or current.get("account_id"),
+        "credit_actor_email": launch.get("credit_actor_email", pool_actor(directory))})
+    (directory / ".credit-sessions" / f"{pid}.json").unlink(missing_ok=True)
+
+
+def credit_refusal_view(directory):
+    directory = Path(directory)
+    refusal = read_json(directory / ".credit-refused.json")
+    account = (read_json(directory / "limits.json").get("credits") or {}).get("account_id")
+    if not account or refusal.get("account_id") != account:
+        return {}
+    actor = pool_actor(directory)
+    if refusal.get("credit_actor_email") and refusal["credit_actor_email"] != actor:
+        return {}
+    try:
+        _, blocked_at = timestamp(refusal.get("credit_blocked_at"))
+    except ValueError:
+        blocked_at = None
+    return {"credit_blocked_at": blocked_at,
+            "credit_blocked_balance": balance_value(refusal.get("credit_blocked_balance")),
+            "limited_reason": "credits"}
+
+
+def main(argv):
+    now = time.time()
+    if argv[0] == "pick":
+        print(pick(float(argv[1]), argv[2:]))
+    elif argv[0] == "record":
+        record_launch(Path(argv[1]), int(argv[2]), now)
+    elif argv[0] == "refuse":
+        record_refusal(Path(argv[1]), int(argv[2]), now)
+    else:
+        return 2
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))

package/lib/codex_credits.py

@@ -0,0 +1,158 @@
+"""Spendable Codex credits from the existing usage read; never redeem or infer funds."""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from decimal import Decimal, InvalidOperation
+import json
+import os
+import re
+import time
+
+from codex_usage_fetch import TRANSPORT_ERRORS
+from codex_credit_controls import limit_type as _limit_type, usage_controls as _controls
+
+_DECIMAL = re.compile(r"(?:0|[1-9][0-9]*)(?:\.[0-9]+)?\Z")
+_IDENTITY = re.compile(r"[A-Za-z0-9][A-Za-z0-9_.:@/-]{0,199}\Z")
+_ERRORS = {
+    "missing_credits", "invalid_credits", "account_mismatch", "unauthenticated",
+    "usage_read_failed", "invalid_usage", "http_401", "http_403", "http_429", "http_error",
+    "usage_reset_pending",
+} | TRANSPORT_ERRORS
+
+
+def _iso(value: float) -> str:
+    return datetime.fromtimestamp(value, timezone.utc).isoformat().replace("+00:00", "Z")
+
+
+def _balance(value):
+    if value is None:
+        return None
+    if not isinstance(value, str) or len(value) > 128 or not _DECIMAL.fullmatch(value):
+        raise ValueError("invalid credit balance")
+    try:
+        number = Decimal(value)
+    except InvalidOperation as error:
+        raise ValueError("invalid credit balance") from error
+    result = format(number, "f")
+    return result.rstrip("0").rstrip(".") if "." in result else result
+
+
+def _identity(value):
+    return value if isinstance(value, str) and _IDENTITY.fullmatch(value) else None
+
+
+def _optional_bool(value):
+    return value if type(value) is bool else None
+
+
+def snapshot_from_usage(usage: dict, account_id: str, now: float) -> dict:
+    """Bind the provider's wallet and admission facts to the authenticated account."""
+    if not isinstance(usage, dict):
+        raise ValueError("invalid_usage")
+    root = usage.get("rateLimits")
+    root = root if isinstance(root, dict) else usage
+    response_id = usage.get("account_id", usage.get("accountId"))
+    expected, reported = _identity(account_id), _identity(response_id)
+    if response_id is not None and not reported:
+        raise ValueError("account_mismatch")
+    if expected and reported and expected != reported:
+        raise ValueError("account_mismatch")
+    raw = root.get("credits")
+    if not isinstance(raw, dict):
+        raise ValueError("missing_credits")
+    has_credits = raw.get("has_credits", raw.get("hasCredits"))
+    if type(has_credits) is not bool or type(raw.get("unlimited")) is not bool:
+        raise ValueError("invalid_credits")
+    try:
+        balance = _balance(raw.get("balance"))
+    except ValueError as error:
+        raise ValueError("invalid_credits") from error
+    return {
+        "has_credits": has_credits, "unlimited": raw["unlimited"], "balance": balance,
+        "fetched_at": _iso(now), "account_id": reported or expected,
+        **_controls(usage, root),
+    }
+
+
+def credit_view(value, now: float | None = None, stale_after: int = 900) -> dict | None:
+    """Sanitize the stored snapshot, preserving its own timestamp and unknown values."""
+    if not isinstance(value, dict):
+        return None
+    if type(value.get("has_credits")) is not bool or type(value.get("unlimited")) is not bool:
+        return None
+    try:
+        stamp = datetime.fromisoformat(value["fetched_at"].replace("Z", "+00:00"))
+        if stamp.tzinfo is None or stamp.timestamp() <= 0:
+            return None
+        age = (time.time() if now is None else now) - stamp.timestamp()
+        balance = _balance(value.get("balance"))
+    except (KeyError, ValueError, TypeError, AttributeError, OverflowError):
+        return None
+    reached = value.get("limit_reached_type")
+    out = {
+        "has_credits": value["has_credits"], "unlimited": value["unlimited"], "balance": balance,
+        "fetched_at": _iso(stamp.timestamp()), "account_id": _identity(value.get("account_id")),
+        "ordinary_usage_allowed": _optional_bool(value.get("ordinary_usage_allowed")),
+        "spend_control_reached": _optional_bool(value.get("spend_control_reached")),
+        "limit_reached_type": _limit_type(reached),
+        "age_seconds": max(0, int(age)), "stale": age > stale_after or age < -30,
+    }
+    error = value.get("last_error")
+    if error:
+        out["last_error"] = error if isinstance(error, str) and error in _ERRORS else "usage_read_failed"
+        out["stale"] = True
+        stamp = value.get("last_error_at")
+        if isinstance(stamp, str) and len(stamp) <= 64:
+            try:
+                parsed = datetime.fromisoformat(stamp.replace("Z", "+00:00"))
+                if parsed.tzinfo is not None and parsed.timestamp() > 0:
+                    out["last_error_at"] = _iso(parsed.timestamp())
+            except (ValueError, OverflowError):
+                pass
+    return out
+
+
+def failed_credits(previous, error: str, now: float) -> dict | None:
+    """Keep the last measured amount and its age when a telemetry read fails."""
+    out = credit_view(previous, now)
+    if out is not None:
+        if out.get("last_error") in ("account_mismatch", "unauthenticated"):
+            return out
+        out.update(last_error=error if error in _ERRORS else "usage_read_failed",
+                   last_error_at=_iso(now), stale=True)
+    return out
+
+
+def collect_credits(usage, account_id: str, now: float, previous=None) -> dict | None:
+    try:
+        result = snapshot_from_usage(usage, account_id, now)
+        if previous and result["has_credits"] and not result["unlimited"] and result["balance"] is None:
+            raise ValueError("invalid_credits")
+        return result
+    except ValueError as error:
+        result = failed_credits(previous, str(error), now)
+        if result is not None and str(error) in ("missing_credits", "invalid_credits"):
+            root = usage.get("rateLimits")
+            root = root if isinstance(root, dict) else usage
+            controls = _controls(usage, root)
+            if controls["spend_control_reached"] is True:
+                result["spend_control_reached"] = True
+            if controls["limit_reached_type"] not in (None, "rate_limit_reached"):
+                result["limit_reached_type"] = controls["limit_reached_type"]
+        return result
+
+
+def record_read_failure(path: str, previous: dict, error: str, now: float) -> None:
+    """Persist a bounded non-secret failure while retaining earlier usage observations."""
+    out = dict(previous)
+    out.update(last_error=error if error in _ERRORS else "usage_read_failed", last_error_at=int(now))
+    credits = failed_credits(out.get("credits"), error, now)
+    if credits is not None:
+        out["credits"] = credits
+    else:
+        out.pop("credits", None)
+    temporary = path + ".tmp"
+    with open(temporary, "w", encoding="utf-8") as handle:
+        json.dump(out, handle, indent=1)
+    os.replace(temporary, path)

package/lib/codex_limits_lock.py

@@ -0,0 +1,56 @@
+"""Keep a live Codex usage collector's lock even when a slow pass exceeds two minutes."""
+
+from __future__ import annotations
+
+import fcntl
+import json
+import os
+from pathlib import Path
+import shutil
+import subprocess
+import sys
+import time
+
+
+def process_birth(pid: int) -> str:
+    try:
+        os.kill(pid, 0)
+        result = subprocess.run(["ps", "-p", str(pid), "-o", "lstart="],
+                                capture_output=True, text=True, timeout=5, check=False)
+        return result.stdout.strip() if result.returncode == 0 else ""
+    except (OSError, subprocess.TimeoutExpired):
+        return ""
+
+
+def change_lock(path: Path, pid: int, release: bool = False) -> bool:
+    """Serialize ownership changes; the owner process lifetime governs the lease."""
+    birth = process_birth(pid)
+    if not birth:
+        return False
+    with path.with_suffix(".guard").open("a") as guard:
+        fcntl.flock(guard, fcntl.LOCK_EX)
+        owner = {}
+        try:
+            owner = json.loads((path / "owner.json").read_text())
+        except (OSError, ValueError):
+            pass
+        ours = owner == {"pid": pid, "birth": birth}
+        if release:
+            if ours:
+                shutil.rmtree(path)
+            return ours
+        if path.exists():
+            owner_pid = owner.get("pid") if isinstance(owner, dict) else None
+            if isinstance(owner_pid, int) and owner_pid > 0:
+                if owner.get("birth") and process_birth(owner_pid) == owner["birth"]:
+                    return False
+            elif time.time() - path.stat().st_mtime < 120:
+                return False
+            shutil.rmtree(path)
+        path.mkdir()
+        (path / "owner.json").write_text(json.dumps({"pid": pid, "birth": birth}))
+        return True
+
+
+if __name__ == "__main__":
+    sys.exit(0 if change_lock(Path(sys.argv[2]), int(sys.argv[3]), sys.argv[1] == "release") else 1)

package/lib/codex_usage_fetch.py

@@ -0,0 +1,85 @@
+"""Read-only usage transport with bounded retries and non-secret failure categories."""
+
+from __future__ import annotations
+
+from email.utils import parsedate_to_datetime
+import errno
+import json
+import socket
+import ssl
+import time
+import urllib.error
+import urllib.request
+
+TRANSPORT_ERRORS = {
+    "network_unreachable", "dns_unavailable", "usage_timeout", "connection_reset",
+    "tls_error", "edge_challenge",
+}
+
+
+def failure_kind(error: Exception) -> str:
+    """Classify the exception without retaining URLs, headers, bodies, or tokens."""
+    if isinstance(error, urllib.error.HTTPError):
+        if ((error.headers or {}).get("cf-mitigated") or "").lower() == "challenge":
+            return "edge_challenge"
+        return f"http_{error.code}" if error.code in (401, 403, 429) else "http_error"
+    reason = error.reason if isinstance(error, urllib.error.URLError) else error
+    if isinstance(reason, socket.gaierror):
+        return "dns_unavailable"
+    if isinstance(reason, (socket.timeout, TimeoutError)):
+        return "usage_timeout"
+    if isinstance(reason, ssl.SSLError):
+        return "tls_error"
+    if isinstance(reason, OSError):
+        if reason.errno in (errno.EHOSTUNREACH, errno.ENETUNREACH, errno.ENETDOWN):
+            return "network_unreachable"
+        if reason.errno in (errno.ECONNRESET, errno.ECONNREFUSED, errno.EPIPE):
+            return "connection_reset"
+    if isinstance(error, (ValueError, UnicodeError)):
+        return "invalid_usage"
+    return "usage_read_failed"
+
+
+def retryable(error: Exception) -> bool:
+    if isinstance(error, urllib.error.HTTPError):
+        return error.code in (500, 502, 503, 504) and not (error.headers or {}).get("Retry-After")
+    return failure_kind(error) in TRANSPORT_ERRORS - {"tls_error", "edge_challenge"}
+
+
+def fetch_usage(request, budget: float = 15):
+    """Retry once within a monotonic budget; OS DNS/socket operations retain their own timeouts."""
+    deadline = time.monotonic() + budget
+    for attempt in range(2):
+        remaining = max(0.1, deadline - time.monotonic())
+        try:
+            with urllib.request.urlopen(request, timeout=min(10, remaining)) as response:
+                result = json.loads(response.read().decode())
+            if not isinstance(result, dict):
+                raise ValueError("invalid usage object")
+            return result
+        except Exception as error:
+            if isinstance(error, urllib.error.HTTPError):
+                error.close()
+            if attempt or not retryable(error) or time.monotonic() >= deadline:
+                raise
+
+
+def retry_delay(error: Exception, previous: dict, now: float) -> int:
+    """Honor Retry-After; otherwise back off transient failures without hammering an account."""
+    header = (error.headers or {}).get("Retry-After") if isinstance(error, urllib.error.HTTPError) else None
+    if header:
+        try:
+            delay = int(header)
+        except (TypeError, ValueError):
+            try:
+                delay = int(parsedate_to_datetime(header).timestamp() - now)
+            except (TypeError, ValueError, OverflowError):
+                delay = 0
+        if delay > 0:
+            return delay
+    try:
+        prior = int(previous.get("backoff", 60))
+    except (TypeError, ValueError):
+        prior = 60
+    ceiling = 1800 if failure_kind(error) == "http_429" else 900
+    return min(ceiling, max(120, prior * 2))

package/lib/report.py

@@ -49,6 +49,8 @@ import keychain  # noqa: E402
 from audit import creds_doc_state, token_verified  # noqa: E402
 from claude_client_error import org_access_verified_at  # noqa: E402
 from claude_reset import marker_superseded, record_from  # noqa: E402
+from codex_credits import credit_view  # noqa: E402
+from codex_credit_selection import credit_refusal_view  # noqa: E402
 
 SCHEMA = 'claude-multiacc/pool.v1'
 
@@ -262,6 +264,10 @@ def _usage(d, stale_after):
     out = {'fetched_at': _iso(fetched), 'source': lim.get('source'),
            'max_percent': lim.get('max_percent'), 'weekly_percent': lim.get('weekly_percent'),
            'session_percent': lim.get('session_percent'), 'buckets': buckets}
+    credits = credit_view(lim.get('credits'), stale_after=stale_after)
+    if credits is not None:
+        out['credits'] = credits
+        out.update(credit_refusal_view(d))
     reset_count = lim.get('reset_credits_available')
     reset_stamp = _iso(lim.get('reset_credits_fetched_at'))
     if type(reset_count) is int and 0 <= reset_count <= 1_000_000 and reset_stamp:

package/lib/selector_credit_scope.py

@@ -0,0 +1,85 @@
+"""Wallet finances are shared; actor permissions, authentication and refusals are not."""
+
+from __future__ import annotations
+
+from decimal import Decimal
+
+from selector_primitives import timestamp
+from selector_credits import HARD_CREDIT_ERRORS, normalize_credits
+
+FINANCIAL_FIELDS = ("has_credits", "unlimited", "balance", "account_id")
+
+
+def actor_email(raw: dict) -> str | None:
+    value = raw.get("credit_actor_email")
+    return value.strip().lower() or None if isinstance(value, str) else None
+
+
+def wallet_available(credits: dict) -> bool:
+    balance = credits.get("balance")
+    funds = credits["unlimited"] or (credits["has_credits"] and balance is not None and Decimal(balance) > 0)
+    return bool(credits["account_id"] and credits["fetched_at"]
+                and credits["last_error"] not in HARD_CREDIT_ERRORS and funds)
+
+
+def merge_wallet(local: dict, wallet: dict | None) -> dict:
+    if wallet is None:
+        return local
+    merged = dict(local)
+    merged.update({key: wallet[key] for key in FINANCIAL_FIELDS})
+    merged["available"] = bool(local["fetched_at"] and local["last_error"] not in HARD_CREDIT_ERRORS
+                               and not local["spend_control_reached"] and wallet["available"])
+    return merged
+
+
+def actor_key(raw: dict) -> tuple:
+    credits = raw.get("credits") or {}
+    account, actor = credits.get("account_id"), actor_email(raw)
+    if actor:
+        return account, actor
+    return account, None, raw.get("runner_id"), raw.get("account_id")
+
+
+def actor_refusals(candidates: list[dict]) -> dict:
+    refusals = {}
+    for raw in candidates:
+        if not raw.get("credit_blocked_at") or (raw.get("credits") or {}).get("last_error") == "account_mismatch":
+            continue
+        try:
+            _, blocked = timestamp(raw["credit_blocked_at"])
+        except ValueError:
+            continue
+        key = actor_key(raw)
+        previous = refusals.get(key)
+        if key[0] and (previous is None or blocked > previous["credit_blocked_at"]):
+            refusals[key] = {"credit_blocked_at": blocked,
+                             "credit_blocked_balance": raw.get("credit_blocked_balance")}
+    return refusals
+
+
+def actor_observations(candidates: list[dict], now, max_age: int) -> dict:
+    observations = {}
+    for raw in candidates:
+        credits = normalize_credits(raw.get("credits"), now, max_age)
+        if not credits["fetched_at"] or credits["last_error"] == "account_mismatch":
+            continue
+        key = actor_key(raw)
+        sticky = bool(credits["last_error"] and credits["spend_control_reached"])
+        rank = (sticky, credits["fetched_at"], credits["spend_control_reached"],
+                credits["ordinary_usage_allowed"] is False)
+        previous = observations.get(key)
+        if previous is None or rank > previous[0]:
+            observations[key] = rank, credits
+    return {key: value[1] for key, value in observations.items()}
+
+
+def merge_actor(local: dict, observation: dict | None) -> dict:
+    # A partial response can confirm a new restriction while retaining old money's
+    # timestamp. A peer's newer money is not proof that this local restriction lifted.
+    if observation is None or (local["last_error"] and local["spend_control_reached"]):
+        return local
+    merged = dict(local)
+    for key in ("ordinary_usage_allowed", "spend_control_reached", "limit_reached_type"):
+        merged[key] = observation[key]
+    merged["available"] = wallet_available(local) and not merged["spend_control_reached"]
+    return merged