thoughtleaders-cli 0.9.0__tar.gz → 0.9.1__tar.gz

{thoughtleaders_cli-0.9.0 → thoughtleaders_cli-0.9.1}/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "tl-cli",
-  "version": "0.9.0",
+  "version": "0.9.1",
   "description": "ThoughtLeaders CLI — query sponsorship deals, channels, brands, uploads, and intelligence from the terminal",
   "author": {
     "name": "ThoughtLeaders",

{thoughtleaders_cli-0.9.0 → thoughtleaders_cli-0.9.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: thoughtleaders-cli
-Version: 0.9.0
+Version: 0.9.1
 Summary: ThoughtLeaders CLI — query sponsorship data, channels, brands, and intelligence
 Project-URL: Homepage, https://thoughtleaders.io
 Project-URL: Repository, https://github.com/ThoughtLeaders-io/thoughtleaders-cli

{thoughtleaders_cli-0.9.0 → thoughtleaders_cli-0.9.1}/hooks/scripts/pre-check.sh

@@ -20,11 +20,9 @@ if ! tl auth status --quiet 2>/dev/null; then
   exit 0  # Don't block, just warn
 fi
 
-# For list commands without explicit limit, suggest adding one
-if [[ "$COMMAND" =~ ^tl[[:space:]]+(deals|uploads|channels|brands)[[:space:]] ]]; then
-  if [[ ! "$COMMAND" =~ limit: ]] && [[ ! "$COMMAND" =~ --limit ]]; then
-    echo "HINT: Consider adding a limit to control credit usage (e.g., limit:50)" >&2
-  fi
-fi
+# NOTE: no "add a limit" hint here. List commands are server-limited by
+# default and typically cost far below the warning-worthy range, so the
+# hint was pure noise for agents (it fired on every unlimited list call
+# regardless of cost).
 
 exit 0

{thoughtleaders_cli-0.9.0 → thoughtleaders_cli-0.9.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "thoughtleaders-cli"
-version = "0.9.0"
+version = "0.9.1"
 description = "ThoughtLeaders CLI — query sponsorship data, channels, brands, and intelligence"
 readme = "README.md"
 license = "MIT"

{thoughtleaders_cli-0.9.0 → thoughtleaders_cli-0.9.1}/skills/tl/SKILL.md

@@ -229,12 +229,15 @@ tl <entity> comment-edit <comment-id> "msg"  # Edit own comment (author or super
 ```bash
 tl sponsorships update <id> '<json>'   # Edit a sponsorship (adlink)
 tl channels update <id> '<json>'       # Edit a channel
+tl profiles update <id> '<json>'       # Edit a brand/publisher profile (superuser only)
 ```
 
 Examples:
 ```bash
 tl sponsorships update 98765 '{"publish_status": "sold"}'
 tl sponsorships update 98765 '{"publish_status": 3}'
+tl profiles update 8871 '{"superuser_notes": "VIP account — always cc the AM lead"}'
+tl profiles update 8871 '{"superuser_notes": null}'
 tl channels update 12345 '{"demographic_male_share": 62}'
 tl channels update 12345 '{"demographic_geo": {"US": 60, "UK": 12, "CA": 8}}'
 tl channels update 12345 '{"demographic_male_share": 55, "demographic_usa_share": 70}'
@@ -260,6 +263,13 @@ the date the channel joined the Media Selling Network, as a `YYYY-MM-DD` string.
 itself the membership flag: set it to add the channel to MSN (it then reads as `is_msn` and
 appears in MSN-filtered queries), or send `null` to remove the channel from the network.
 
+**Profile notes.** `tl profiles update` (superuser only) edits a brand/publisher profile's
+**`superuser_notes`** — the internal free-text notes field on the customer record
+(`thoughtleaders_profile.superuser_notes`, max 2500 chars). Send a string to set, `null` to
+clear. This is currently the only editable profile field; anything else returns a 400 listing
+the editable surface. Use it for account-handling notes meant for the internal team — it is
+never shown to the customer.
+
 ### Creating and vetting sponsorships
 
 This is the end-to-end workflow for proposing a sponsorship, then moving it through the funnel as the two sides respond. Three create commands plus `tl sponsorships update` cover every state transition the CLI exposes.

{thoughtleaders_cli-0.9.0 → thoughtleaders_cli-0.9.1}/skills/tl/references/business-glossary.md

@@ -69,6 +69,7 @@ Maps business terms to database concepts.
 | `owner_advertiser_id` | `profile` | **Account owner.** Who owns the brand relationship overall. Often same person as owner_sales on adlinks, but not always. |
 | `owner_publisher_id` | `profile` | Channel relationship owner on the profile level |
 | `owner_sales_id` | `profile` | Sales owner at profile level |
+| `superuser_notes` | `profile` | Internal free-text account-handling notes on the customer record (max 2500 chars). Team-facing only — never shown to the customer. Superusers can edit it through the CLI (see SKILL.md → "Updating records"). |
 
 **Key insight:** Ownership exists on both `profile` (account-level) and `adlink` (deal-level). For revenue attribution, always use `adlink.owner_sales_id`.
 

{thoughtleaders_cli-0.9.0 → thoughtleaders_cli-0.9.1}/skills/tl/references/firebolt-schema.md

@@ -33,10 +33,12 @@ Drop to `tl db fb` only when you need a shape `tl snapshots` doesn't produce (cu
 - **SELECT only.** No DDL/DML/transactions/SET/locks.
 - **Single table.** No JOIN, CTE (`WITH`), subquery, set operation, or `LATERAL`.
 - **Only known tables:** `article_metrics`, `channel_metrics`. Other names return `UNKNOWN_TABLE`.
+- **Constant-only probes are allowed:** `SELECT 1` (no FROM, no column references) works as a connectivity check. Anything naming a column or `*` still needs a FROM.
 - **WHERE/HAVING may only reference indexed columns** (`channel_id`/`id` for `article_metrics`; `id` for `channel_metrics`). Filtering by `age`, `publication_date`, `view_count`, `duration`, `scrape_date`, etc. in WHERE returns `NON_INDEXED_FILTER:<col>`. Apply those constraints client-side after fetching.
 - **Leading index column must be equality-or-IN-filtered with literals** (`channel_id = 1` or `channel_id IN (1,2,3)`). Without it: `MISSING_INDEXED_FILTER`.
 - **Trivial-aggregation exception:** a SELECT whose projected expressions are all aggregates and which has no GROUP BY / HAVING may omit WHERE entirely. Use only for tiny sanity checks.
 - **No mandatory LIMIT/OFFSET** — but Firebolt will time out on bad plans, so keep the leading-index filter selective.
+- **Errors carry the real diagnostic.** A query that Firebolt itself rejects (unknown column, syntax error) comes back as a 400 with Firebolt's own error description, plus a rename hint where one is known. Common trap: `channel_metrics` has `subscribers`, not the older `reach`.
 
 ## Tables
 

{thoughtleaders_cli-0.9.0 → thoughtleaders_cli-0.9.1}/skills/tl/references/postgres-schema.md

@@ -275,6 +275,7 @@ JOIN thoughtleaders_profile_brands pb ON p.id = pb.profile_id
 JOIN thoughtleaders_brand b ON pb.brand_id = b.id
 -- NEVER: JOIN brand b ON b.id = a.advertiser_profile_id (different ID spaces, returns wrong data)
 ```
+This 3-table join is the one brand path that works in every session — use it in anything reusable.
 
 **Adlink → Organization:**
 ```sql

{thoughtleaders_cli-0.9.0 → thoughtleaders_cli-0.9.1}/skills/tl-save-report/SKILL.md

@@ -41,7 +41,7 @@ This skill is self-contained. Every reference it needs is in [`references/`](ref
 | **3** | CHANNELS | one YouTube channel (or podcast) | intelligence |
 | **8** | SPONSORSHIPS / Deals | one sponsorship record (AdLink — brand × channel × dates × status × price) | sponsorship |
 
-Types 1 / 2 / 3 share the intelligence FilterSet and widget schemas (different rows, same predicate fields). Type 8 has its own schemas (disjoint fields, different aggregators, different data plane — Postgres against `v_adspot_brand_profiles` rather than Elasticsearch).
+Types 1 / 2 / 3 share the intelligence FilterSet and widget schemas (different rows, same predicate fields). Type 8 has its own schemas (disjoint fields, different aggregators, different data plane — a denormalized sponsorship dataset in Postgres rather than Elasticsearch).
 
 ## When to invoke
 

{thoughtleaders_cli-0.9.0 → thoughtleaders_cli-0.9.1}/skills/tl-save-report/references/sponsorship_filterset_schema.json

@@ -10,7 +10,7 @@
     "django_model": "dashboard.models.FilterSet",
     "django_enums_module": "dashboard.enums",
     "applies_to_report_types": [8],
-    "report_type_meaning": "CAMPAIGN_MANAGEMENT — sponsorship/AdLink-level reporting. Filters are evaluated against the denormalized view v_adspot_brand_profiles, which already joins adlink, brand, channel, and organization. Direct joins from thoughtleaders_adlink to thoughtleaders_brand or thoughtleaders_channel are NOT possible — those FKs do not exist on the adlink table. See SKILL.md Step 2.V1 (Sponsorship reports section) for the canonical query shape.",
+    "report_type_meaning": "CAMPAIGN_MANAGEMENT — sponsorship/AdLink-level reporting. Filters are evaluated against a denormalized sponsorship dataset that already joins adlink, brand, channel, and organization. Direct joins from thoughtleaders_adlink to thoughtleaders_brand or thoughtleaders_channel are NOT possible — those FKs do not exist on the adlink table. See SKILL.md Step 2.V1 (Sponsorship reports section) for the canonical query shape.",
     "note": "Same Django model as the intelligence schema, but only a subset of fields is meaningful for sponsorship reporting. Fields not listed here exist on the model but are inert for type 8."
   },
 

{thoughtleaders_cli-0.9.0 → thoughtleaders_cli-0.9.1}/src/tl_cli/__init__.py

@@ -1,3 +1,3 @@
 """ThoughtLeaders CLI — query sponsorship data, channels, brands, and intelligence."""
 
-__version__ = "0.9.0"
+__version__ = "0.9.1"

{thoughtleaders_cli-0.9.0 → thoughtleaders_cli-0.9.1}/src/tl_cli/client/errors.py

@@ -68,6 +68,17 @@ def handle_api_error(error: ApiError) -> None:
         _print_debug(error)
         sys.exit(3)
     else:
-        err.print(f"[red]Error ({error.status_code}):[/red] {error.detail}")
+        detail = error.detail or ""
+        hint = (error.raw or {}).get("hint") if isinstance(error.raw, dict) else None
+        if isinstance(hint, str) and hint:
+            # The server sends the remediation both concatenated into
+            # `detail` (for older clients) and as a separate `hint` key —
+            # render it on its own line so it can't get lost in the error.
+            if detail.endswith(hint):
+                detail = detail[: -len(hint)].rstrip()
+            err.print(f"[red]Error ({error.status_code}):[/red] {detail}")
+            err.print(f"[bold yellow]Hint:[/bold yellow] [yellow]{hint}[/yellow]")
+        else:
+            err.print(f"[red]Error ({error.status_code}):[/red] {detail}")
         _print_debug(error)
         sys.exit(1)

{thoughtleaders_cli-0.9.0 → thoughtleaders_cli-0.9.1}/src/tl_cli/commands/db.py

@@ -5,12 +5,12 @@ import sys
 
 import typer
 from rich.console import Console
-from tl_cli._typer_utils import AlphaSortedTyperGroup
 
+from tl_cli._typer_utils import AlphaSortedTyperGroup
 from tl_cli.client.errors import ApiError, handle_api_error
 from tl_cli.client.http import get_client
 from tl_cli.output.formatter import detect_format, output, output_pricing_estimate
-from tl_cli.query_history import query_hash, record_and_check
+from tl_cli.query_history import note_charge, query_hash, record_and_check
 
 app = typer.Typer(cls=AlphaSortedTyperGroup, help="Raw read-only queries against PostgreSQL, Firebolt, or Elasticsearch (full-access only)")
 
@@ -18,7 +18,10 @@ _err = Console(stderr=True)
 
 _NO_REPEAT_WARNING_OPTION = typer.Option(
     False, "--no-repeat-warning",
-    help="Suppress the warning shown when the same query is re-run repeatedly (also: TL_NO_REPEAT_WARNING=1).",
+    help=(
+        "Suppress the warning shown when the same query is re-run repeatedly after "
+        "burning 1000+ credits (also: TL_NO_REPEAT_WARNING=1)."
+    ),
 )
 
 
@@ -30,28 +33,37 @@ def _read_query(query: str | None) -> str:
     return sys.stdin.read()
 
 
-def _warn_if_repeat(engine: str, query: str, pricing: bool, suppressed: bool) -> None:
-    """Nudge (on stderr) when this exact query keeps being re-run.
+def _warn_if_repeat(digest: str, suppressed: bool) -> None:
+    """Nudge (on stderr) when this exact query keeps being re-run AND the
+    repeats have already burned a material amount of credits.
 
-    Detection is local and best-effort; the query always executes.
+    Detection is local and best-effort; the query always executes. Cheap
+    repeats stay silent — the warning only fires once the window's runs
+    have been billed SPEND_THRESHOLD_CREDITS in total.
     """
     if suppressed:
         return
-    count = record_and_check(query_hash(engine, query, pricing))
-    if count is None:
+    due = record_and_check(digest)
+    if due is None:
         return
+    count, spent = due
     _err.print(
         f"[yellow]Repeat query:[/yellow] this exact query has now run {count} times "
-        "in the last 5 minutes. Each run is billed and the results are unlikely to "
-        "differ — reuse the earlier output (e.g. save it with `--json > file.json`). "
-        "Pass --no-repeat-warning if the repeats are deliberate."
+        f"in the last 5 minutes ({spent:g} credits so far). Each run is billed and "
+        "the results are unlikely to differ — reuse the earlier output (e.g. save it "
+        "with `--json > file.json`). Pass --no-repeat-warning if the repeats are "
+        "deliberate."
     )
 
 
-def _run(path: str, body: dict, fmt: str, title: str, pricing: bool = False) -> None:
+def _run(path: str, body: dict, fmt: str, title: str, pricing: bool = False,
+         digest: str | None = None) -> None:
     client = get_client()
     try:
         data = client.post(path, json_body=body)
+        if digest:
+            usage = data.get("usage") or {}
+            note_charge(digest, usage.get("credits_charged"))
         if pricing:
             output_pricing_estimate(data, fmt)
             return
@@ -84,9 +96,19 @@ def pg_cmd(
 ) -> None:
     """Run a raw PostgreSQL SELECT query.
 
-    Column names follow the current schema (e.g. subscribers, projected_views,
-    scheduled_date — not the older reach / impression / send_date). Run
-    `tl schema pg <table>` to see the exact columns your role can query.
+    Common traps — check before writing SQL:
+
+    - Column names follow the current schema: subscribers, projected_views,
+      scheduled_date, is_tpp, advertiser_profile_id, views_guarantee — NOT the
+      older reach / impression / send_date / is_tl_channel / creator_profile_id
+      / impressions_guarantee.
+    - The sponsorship table (thoughtleaders_adlink) hides its relations behind
+      joins: no channel_id/channel_name (join thoughtleaders_adspot via
+      ad_spot_id, then thoughtleaders_channel) and no brand_id (join
+      thoughtleaders_profile via advertiser_profile_id, then
+      thoughtleaders_profile_brands).
+    - Run `tl schema pg <table>` first — it lists the exact columns your role
+      can query plus each table's common traps.
 
     Examples:
         tl db pg "SELECT channel_name, subscribers, projected_views FROM thoughtleaders_channel ORDER BY subscribers DESC LIMIT 10"
@@ -96,11 +118,12 @@ def pg_cmd(
     """
     fmt = detect_format(json_output, csv_output, md_output, toon_output)
     sql = _read_query(query)
-    _warn_if_repeat("pg", sql, pricing, no_repeat_warning)
+    digest = query_hash("pg", sql, pricing)
+    _warn_if_repeat(digest, no_repeat_warning)
     body: dict = {"query": sql}
     if pricing:
         body["pricing"] = True
-    _run("/raw/pg", body, fmt, "Postgres results", pricing=pricing)
+    _run("/raw/pg", body, fmt, "Postgres results", pricing=pricing, digest=digest)
 
 
 @app.command("fb")
@@ -118,19 +141,28 @@ def fb_cmd(
 ) -> None:
     """Run a raw Firebolt SELECT query.
 
-    The query must filter the leading index column of the table (channel_id
-    for article_metrics, id for channel_metrics) — see the Firebolt schema.
+    Two tables: article_metrics (per-video daily metrics) and channel_metrics
+    (per-channel history). Single-table SELECTs only (no JOINs), and WHERE
+    must equality- or IN-filter the leading index column — channel_id for
+    article_metrics, id (the channel id) for channel_metrics. Other columns
+    can't be filtered server-side: fetch by the indexed key, then narrow
+    client-side. Column names follow the current schema (subscribers, not
+    the older reach) — run `tl schema fb` to see them.
 
     Examples:
+        tl db fb "SELECT 1"   # connectivity check — the only no-FROM query allowed
         tl db fb "SELECT scrape_date, view_count FROM article_metrics WHERE channel_id = 5607 AND id = 'EjeGzoQI3gQ'"
+        tl db fb "SELECT scrape_date, subscribers, total_views FROM channel_metrics WHERE id = 736006 ORDER BY scrape_date"
+        tl db fb "SELECT publication_date, view_count FROM article_metrics WHERE channel_id IN (5607, 5608)"
     """
     fmt = detect_format(json_output, csv_output, md_output, toon_output)
     sql = _read_query(query)
-    _warn_if_repeat("fb", sql, pricing, no_repeat_warning)
+    digest = query_hash("fb", sql, pricing)
+    _warn_if_repeat(digest, no_repeat_warning)
     body: dict = {"query": sql}
     if pricing:
         body["pricing"] = True
-    _run("/raw/fb", body, fmt, "Firebolt results", pricing=pricing)
+    _run("/raw/fb", body, fmt, "Firebolt results", pricing=pricing, digest=digest)
 
 
 @app.command("es")
@@ -166,10 +198,11 @@ def es_cmd(
     except json.JSONDecodeError as exc:
         raise typer.BadParameter(f"Query is not valid JSON: {exc}") from exc
 
-    _warn_if_repeat("es", raw, pricing, no_repeat_warning)
+    digest = query_hash("es", raw, pricing)
+    _warn_if_repeat(digest, no_repeat_warning)
     body: dict = {"query": body_query}
     if pricing:
         body["pricing"] = True
     if highlight:
         body["include_highlight"] = True
-    _run("/raw/es", body, fmt, "Elasticsearch results", pricing=pricing)
+    _run("/raw/es", body, fmt, "Elasticsearch results", pricing=pricing, digest=digest)

thoughtleaders_cli-0.9.1/src/tl_cli/commands/profiles.py

@@ -0,0 +1,59 @@
+"""tl profiles — Brand/publisher profile operations."""
+
+import json as _json
+
+import typer
+from rich.console import Console
+
+from tl_cli._typer_utils import AlphaSortedTyperGroup
+from tl_cli.client.errors import ApiError, handle_api_error
+from tl_cli.client.http import get_client
+from tl_cli.output.formatter import detect_format, output_single
+
+app = typer.Typer(cls=AlphaSortedTyperGroup, help="Brand/publisher profiles (update; full-access only)")
+
+
+@app.callback()
+def _profiles() -> None:
+    """Brand/publisher profiles.
+
+    The callback keeps `update` an explicit subcommand — without it Typer
+    collapses a single-command group into the group itself.
+    """
+
+
+@app.command("update")
+def update_cmd(
+    profile_id: int = typer.Argument(..., help="Profile ID (numeric)"),
+    fields: str = typer.Argument(..., help="JSON object of fields to update"),
+    json_output: bool = typer.Option(False, "--json", help="JSON output"),
+    toon_output: bool = typer.Option(False, "--toon", help="TOON output (token-efficient for LLMs)"),
+) -> None:
+    """Update a profile. Full-access only.
+
+    Editable fields: superuser_notes (free-text, max 2500 chars; send null
+    to clear). Unknown fields are rejected with a 400 listing the
+    offending key.
+
+    Examples:
+        tl profiles update 8871 '{"superuser_notes": "VIP account — always cc the AM lead"}'
+        tl profiles update 8871 '{"superuser_notes": null}'
+    """
+    fmt = detect_format(json_output, False, False, toon_output)
+    try:
+        body = _json.loads(fields)
+    except _json.JSONDecodeError as exc:
+        Console(stderr=True).print(f"[red]Error:[/red] fields argument must be a JSON object: {exc}")
+        raise typer.Exit(1)
+    if not isinstance(body, dict):
+        Console(stderr=True).print("[red]Error:[/red] fields argument must be a JSON object.")
+        raise typer.Exit(1)
+
+    client = get_client()
+    try:
+        data = client.post(f"/profiles/{profile_id}/edit", json_body=body)
+        output_single(data, fmt)
+    except ApiError as e:
+        handle_api_error(e)
+    finally:
+        client.close()

{thoughtleaders_cli-0.9.0 → thoughtleaders_cli-0.9.1}/src/tl_cli/main.py

@@ -22,6 +22,7 @@ from tl_cli.commands.channels import app as channels_app
 from tl_cli.commands.db import app as db_app
 from tl_cli.commands.deals import app as deals_app
 from tl_cli.commands.matches import app as matches_app
+from tl_cli.commands.profiles import app as profiles_app
 from tl_cli.commands.proposals import app as proposals_app
 from tl_cli.commands.recommender import app as recommender_app
 from tl_cli.commands.sponsorships import app as sponsorships_app
@@ -93,6 +94,7 @@ app.add_typer(deals_app, name="deals")
 app.add_typer(uploads_app, name="uploads")
 app.add_typer(channels_app, name="channels")
 app.add_typer(brands_app, name="brands")
+app.add_typer(profiles_app, name="profiles")
 app.add_typer(recommender_app, name="recommender")
 app.add_typer(snapshots_app, name="snapshots")
 app.add_typer(reports_app, name="reports")

{thoughtleaders_cli-0.9.0 → thoughtleaders_cli-0.9.1}/src/tl_cli/query_history.py

@@ -25,6 +25,12 @@ WINDOW_S = 300
 REPEAT_THRESHOLD = 3
 WARN_INTERVAL_S = 60
 
+# Materiality floor: repeats only warn once the credits they have already
+# burned inside the window reach this amount. Cheap queries re-run in a loop
+# are noise to warn about — the warning exists to stop material wasted spend,
+# not to nag an agent that is legitimately polling an inexpensive count.
+SPEND_THRESHOLD_CREDITS = 1000
+
 ENV_SUPPRESS = "TL_NO_REPEAT_WARNING"
 
 
@@ -40,11 +46,16 @@ def query_hash(engine: str, query: str, pricing: bool = False) -> str:
     return hashlib.sha256(basis.encode("utf-8")).hexdigest()
 
 
-def record_and_check(digest: str) -> int | None:
-    """Record one run of ``digest``; return the run count when a warning is due.
+def record_and_check(digest: str) -> tuple[int, float] | None:
+    """Record one run of ``digest``; return ``(run_count, credits_spent)``
+    when a warning is due.
 
-    Returns None below the threshold, while a warning from the last
-    WARN_INTERVAL_S is still fresh, or when TL_NO_REPEAT_WARNING is set.
+    A warning is due when the run count reaches REPEAT_THRESHOLD inside the
+    window AND the previous runs have already been billed at least
+    SPEND_THRESHOLD_CREDITS in total (charges are attached post-flight via
+    ``note_charge``). Returns None below either threshold, while a warning
+    from the last WARN_INTERVAL_S is still fresh, or when
+    TL_NO_REPEAT_WARNING is set.
     """
     if os.environ.get(ENV_SUPPRESS):
         return None
@@ -53,20 +64,69 @@ def record_and_check(digest: str) -> int | None:
     entry = state.get(digest)
     entry = entry if isinstance(entry, dict) else {}
     runs = _recent_runs(entry, now)
-    runs.append(now)
+    spent = sum(charged for _, charged in runs)
+    runs.append([now, 0.0])
     warned_at = entry.get("warned_at")
     warning_fresh = isinstance(warned_at, int | float) and now - warned_at < WARN_INTERVAL_S
-    due = len(runs) >= REPEAT_THRESHOLD and not warning_fresh
+    due = (
+        len(runs) >= REPEAT_THRESHOLD
+        and spent >= SPEND_THRESHOLD_CREDITS
+        and not warning_fresh
+    )
     state[digest] = {"runs": runs, "warned_at": now if due else warned_at}
     _save(state, now)
-    return len(runs) if due else None
+    return (len(runs), spent) if due else None
+
 
+def note_charge(digest: str, charged: object) -> None:
+    """Attach the billed charge to ``digest``'s most recent run.
 
-def _recent_runs(entry: dict, now: float) -> list[float]:
+    Called post-flight with ``usage.credits_charged`` from the response
+    envelope — the pre-flight ``record_and_check`` can't know what the run
+    will cost. Missing/zero/bogus charges are ignored (the run then counts
+    as free, which only makes the warning more conservative).
+    """
+    try:
+        amount = float(charged)  # type: ignore[arg-type]
+    except (TypeError, ValueError):
+        return
+    if amount <= 0:
+        return
+    now = time.time()
+    state = _load()
+    entry = state.get(digest)
+    if not isinstance(entry, dict):
+        return
+    runs = _recent_runs(entry, now)
+    if not runs:
+        return
+    runs[-1][1] = amount
+    state[digest] = {"runs": runs, "warned_at": entry.get("warned_at")}
+    _save(state, now)
+
+
+def _recent_runs(entry: dict, now: float) -> list[list[float]]:
+    """Window-fresh ``[timestamp, credits_charged]`` pairs from ``entry``.
+
+    Pre-charge-tracking state files stored bare timestamps; those are read
+    as charge-0 runs rather than resetting the user's history.
+    """
     raw = entry.get("runs")
     if not isinstance(raw, list):
         return []
-    return [t for t in raw if isinstance(t, int | float) and now - t < WINDOW_S]
+    runs: list[list[float]] = []
+    for item in raw:
+        if isinstance(item, int | float):
+            item = [item, 0.0]
+        if (
+            isinstance(item, list)
+            and len(item) == 2
+            and isinstance(item[0], int | float)
+            and isinstance(item[1], int | float)
+            and now - item[0] < WINDOW_S
+        ):
+            runs.append([float(item[0]), float(item[1])])
+    return runs
 
 
 def _load() -> dict: