claude-finops 0.7.2 → 0.9.0

package/finops/etl.py

@@ -5,6 +5,7 @@ Entities: account -> billing_period -> project -> session -> prompt -> request
 transcripts are stored as NULL and rendered as "Unavailable from connected Claude
 data" by the UI.
 """
+import hashlib
 import json
 import os
 import re
@@ -15,9 +16,23 @@ from datetime import datetime, timezone
 from .classify import classify
 from .pricing import Pricing
 
-from .paths import ROOT, DB_PATH
+from .paths import ROOT, DB_PATH, DESKTOP_SESSIONS
 DEFAULT_SOURCE = os.path.expanduser("~/.claude/projects")
 
+SCHEMA_VERSION = 3   # 3: cross-session request_id dedup (resumed sessions copy history)
+
+
+def needs_rebuild(db_path):
+    if not os.path.exists(db_path):
+        return True
+    try:
+        con = sqlite3.connect(db_path)
+        row = con.execute("SELECT value FROM meta WHERE key='schema_version'").fetchone()
+        con.close()
+    except sqlite3.Error:
+        return True
+    return not row or row[0] != str(SCHEMA_VERSION)
+
 SCHEMA = """
 PRAGMA journal_mode=WAL;
 
@@ -88,6 +103,8 @@ CREATE TABLE requests (
   context_tokens INTEGER,    -- input + cache read + cache write  (prompt side)
   est_cost_usd REAL,
   est_cost_no_cache_usd REAL,
+  priced_as TEXT,            -- price list used; differs from model for long context
+  unpriced_long_context INTEGER DEFAULT 0,  -- over the window with no [1m] price to use
   latency_ms REAL,
   tool_call_count INTEGER DEFAULT 0,
   is_sidechain INTEGER DEFAULT 0,
@@ -134,6 +151,9 @@ SLASH = re.compile(r"^\s*/([a-z0-9][\w:-]*)(?=\s|$)", re.I)
 CMD_NAME = re.compile(r"<command-name>/?([\w:-]+)</command-name>")
 WS = re.compile(r"\s+")
 
+INJECTED_PREFIXES = ("<task-notification", "<local-command-stdout", "<local-command-caveat",
+                     "<bash-input", "<bash-stdout", "<bash-stderr", "<system-reminder")
+
 
 def _ts(s):
     if not s:
@@ -183,14 +203,23 @@ def _slug_to_name(slug):
 
 
 class Loader:
-    def __init__(self, db_path=DB_PATH, source=DEFAULT_SOURCE, pricing=None, other_agents=True):
+    def __init__(self, db_path=DB_PATH, source=DEFAULT_SOURCE, pricing=None, other_agents=True,
+                 desktop_roots=None):
         self.other_agents = other_agents
+        # An explicit source means "load exactly this"; only the default also picks up
+        # the desktop app's Cowork sessions (same JSONL format, different config dir).
+        self.desktop_roots = (desktop_roots if desktop_roots is not None
+                              else [DESKTOP_SESSIONS] if source == DEFAULT_SOURCE else [])
+        self.cowork = False
         self.db_path = db_path
         self.source = source
         self.pricing = pricing or Pricing()
         self.projects = {}
         self.agent = None
         self.pending_skill = None
+        self.pending_results = {}
+        self.group = None
+        self.seen_request_ids = set()   # dedup request_id across sessions (resumed sessions)
 
     # ---------- infrastructure ----------
     def build(self, verbose=True):
@@ -209,13 +238,19 @@ class Loader:
                 if n.endswith(".jsonl"):
                     files.append(os.path.join(dirpath, n))
         files.sort()
-        for i, fp in enumerate(files, 1):
+        marker = os.sep + os.path.join(".claude", "projects") + os.sep
+        desktop = sorted(os.path.join(d, n) for root in self.desktop_roots
+                         for d, _, names in os.walk(root) for n in names
+                         if n.endswith(".jsonl") and marker in d + os.sep)
+        for i, fp in enumerate(files + desktop, 1):
             if verbose and i % 20 == 0:
-                print(f"  ...{i}/{len(files)} transcripts", file=sys.stderr)
+                print(f"  ...{i}/{len(files) + len(desktop)} transcripts", file=sys.stderr)
+            self.cowork = i > len(files)
             try:
                 self.load_file(fp)
             except Exception as exc:  # a corrupt transcript must not kill the load
                 print(f"  ! skipped {os.path.basename(fp)}: {exc}", file=sys.stderr)
+        self.cowork = False
         if self.other_agents:
             from .agents import AgentLoader
             counts = AgentLoader(self, log=lambda m: print(m, file=sys.stderr)).run()
@@ -230,13 +265,15 @@ class Loader:
         for k, v in (
             ("source_dir", self.source),
             ("transcript_files", str(len(files))),
+            ("desktop_transcript_files", str(len(desktop))),
             ("pricing_updated", str(self.pricing.updated)),
             ("pricing_source", str(self.pricing.source)),
             ("cost_basis", "estimated"),
+            ("schema_version", str(SCHEMA_VERSION)),
         ):
             self.db.execute("INSERT INTO meta VALUES (?,?)", (k, v))
         self.db.commit()
-        return len(files)
+        return len(files) + len(desktop)
 
     def project_id(self, slug, cwd):
         if slug in self.projects:
@@ -247,6 +284,8 @@ class Loader:
             return pid
         is_sandbox = 1 if ("sandbox" in slug or slug.startswith("-private")) else 0
         name = os.path.basename(cwd) if cwd else _slug_to_name(slug)
+        if self.cowork:
+            name = f"Cowork · {name or 'session'}"
         cur = self.db.execute(
             "INSERT INTO projects (slug, path, name, is_sandbox) VALUES (?,?,?,?)",
             (slug, cwd, name or slug, is_sandbox))
@@ -287,6 +326,8 @@ class Loader:
         session_id = agent["parent"] if agent else os.path.splitext(os.path.basename(path))[0]
         self.agent = agent
         self.pending_skill = None
+        self.pending_results = {}     # tool_use_id -> result chars, applied once the row exists
+        self.group = None
         cwd = next((r.get("cwd") for r in rows if r.get("cwd")), None)
         pid = self.project_id(slug, cwd)
         title = next((r.get("aiTitle") for r in rows if r.get("type") == "ai-title"), None)
@@ -301,37 +342,64 @@ class Loader:
 
         cur_prompt = None
         prev_time = None
-
-        for r in rows:
-            typ = r.get("type")
-            ts = r.get("timestamp")
-            t = _ts(ts)
-
-            if typ == "user":
-                msg = r.get("message") or {}
-                self.record_results(r, msg)
-                # tool results and meta lines are not human prompts
-                if r.get("toolUseResult") is not None or r.get("isMeta"):
+        self.group = None          # {"key", "lines": [...], "prev_time", "prompt_id"}
+
+        def flush():
+            if self.group:
+                self.insert_request(self.group["lines"], session_id, pid, self.group["prompt_id"],
+                                    self.group["prev_time"])
+                self.group = None
+
+        try:
+            for r in rows:
+                typ = r.get("type")
+                ts = r.get("timestamp")
+                t = _ts(ts)
+
+                if typ == "user":
+                    msg = r.get("message") or {}
+                    self.record_results(r, msg)
+                    # tool results and meta lines are not human prompts, and must not
+                    # split a request that is still waiting on its tool results
+                    if r.get("toolUseResult") is not None or r.get("isMeta"):
+                        prev_time = t or prev_time
+                        continue
+                    text = _text_of(msg.get("content"))
+                    if text.lstrip().startswith(INJECTED_PREFIXES):
+                        prev_time = t or prev_time
+                        continue
+                    if agent:
+                        prev_time = t or prev_time
+                        continue
+                    if not text.strip():
+                        prev_time = t or prev_time
+                        continue
+                    flush()
+                    cur_prompt = self.insert_prompt(r, text, session_id, pid)
                     prev_time = t or prev_time
-                    continue
-                text = _text_of(msg.get("content"))
-                if agent:
-                    prev_time = t or prev_time
-                    continue
-                if not text.strip():
-                    prev_time = t or prev_time
-                    continue
-                cur_prompt = self.insert_prompt(r, text, session_id, pid)
-                prev_time = t or prev_time
 
-            elif typ == "assistant":
-                if agent and cur_prompt is None:
-                    cur_prompt = self.parent_prompt(session_id, r.get("timestamp"))
-                self.insert_request(r, session_id, pid, cur_prompt, prev_time)
-                prev_time = t or prev_time
+                elif typ == "assistant":
+                    if agent and cur_prompt is None:
+                        cur_prompt = self.parent_prompt(session_id, r.get("timestamp"))
+                    key = (r.get("requestId") or (r.get("message") or {}).get("id") or r.get("uuid"))
+                    if self.group and self.group["key"] == key:
+                        self.group["lines"].append(r)
+                    else:
+                        flush()
+                        self.pending_skill = None   # never apply a stale skill id to a new group
+                        self.group = {"key": key, "lines": [r], "prev_time": prev_time,
+                                      "prompt_id": cur_prompt}
+                    prev_time = t or prev_time
 
-            elif typ in ("attachment", "system"):
-                prev_time = t or prev_time
+                elif typ in ("attachment", "system"):
+                    prev_time = t or prev_time
+        finally:
+            flush()
+            # any result whose tool_calls row was inserted by an earlier flush
+            for tool_use_id, n in self.pending_results.items():
+                self.db.execute("UPDATE tool_calls SET result_chars=? WHERE tool_use_id=?",
+                                (n, tool_use_id))
+            self.pending_results = {}
 
     def parent_prompt(self, session_id, ts):
         row = self.db.execute("SELECT id FROM prompts WHERE session_id=? AND ts<=? "
@@ -341,19 +409,34 @@ class Loader:
     def record_results(self, r, msg):
         """Size of tool results, and of skill bodies injected as meta messages."""
         content = msg.get("content")
-        if r.get("isMeta") and getattr(self, "pending_skill", None):
-            self.db.execute("UPDATE tool_calls SET result_chars=result_chars+? WHERE id=?",
-                            (len(_text_of(content)), self.pending_skill))
-            self.pending_skill = None
-            return
+        if r.get("isMeta"):
+            if self.group:
+                # the Skill's body can arrive before the group holding its tool_use
+                # flushes; stash it under that block's tool_use_id so insert_request
+                # applies it once the tool_calls row exists.
+                tool_use_id = None
+                for ln in self.group["lines"]:
+                    for c in ((ln.get("message") or {}).get("content") or []):
+                        if isinstance(c, dict) and c.get("type") == "tool_use" and c.get("name") == "Skill":
+                            tool_use_id = c.get("id")
+                if tool_use_id:
+                    n = len(_text_of(content))
+                    self.pending_results[tool_use_id] = self.pending_results.get(tool_use_id, 0) + n
+                return
+            if getattr(self, "pending_skill", None):
+                self.db.execute("UPDATE tool_calls SET result_chars=result_chars+? WHERE id=?",
+                                (len(_text_of(content)), self.pending_skill))
+                self.pending_skill = None
+                return
         if not isinstance(content, list):
             return
         for c in content:
             if isinstance(c, dict) and c.get("type") == "tool_result":
                 body = c.get("content")
                 n = len(body) if isinstance(body, str) else _result_chars(body)
-                self.db.execute("UPDATE tool_calls SET result_chars=? WHERE tool_use_id=?",
-                                (n, c.get("tool_use_id")))
+                # the tool_calls row for this id may not exist yet: its request is
+                # still an open group and is only inserted when it flushes
+                self.pending_results[c.get("tool_use_id")] = n
 
     def insert_prompt(self, r, text, session_id, pid):
         cat, conf, ev = classify(text)
@@ -363,19 +446,23 @@ class Loader:
             src = f"slash:/{m.group(1)}"
             cat = cat if cat != "other" else "automation"
         ts = r.get("timestamp")
-        norm = WS.sub(" ", text.strip().lower())[:500]
+        norm = WS.sub(" ", text.strip().lower())
+        norm_hash = hashlib.sha1(norm.encode("utf-8")).hexdigest()[:16]
         cur = self.db.execute(
             "INSERT INTO prompts (uuid, session_id, project_id, ts, day, text, char_len,"
             " word_len, category, category_confidence, category_evidence, source, norm_hash)"
             " VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?)",
             (r.get("uuid"), session_id, pid, ts, (ts or "")[:10], text, len(text),
-             len(text.split()), cat, conf, json.dumps(ev), src, str(hash(norm))))
+             len(text.split()), cat, conf, json.dumps(ev), src, norm_hash))
         return cur.lastrowid
 
-    def insert_request(self, r, session_id, pid, prompt_id, prev_time):
+    def insert_request(self, lines, session_id, pid, prompt_id, prev_time):
+        first, last = lines[0], lines[-1]
+        r = last                                  # stop_reason / usage from the final line
         msg = r.get("message") or {}
         u = msg.get("usage") or {}
         model = msg.get("model") or "unknown"
+        speed = u.get("speed")
         inp = int(u.get("input_tokens") or 0)
         out = int(u.get("output_tokens") or 0)
         think = int((u.get("output_tokens_details") or {}).get("thinking_tokens") or 0)
@@ -389,11 +476,33 @@ class Loader:
         billable = inp + out + cr + cw
         context = inp + cr + cw
 
-        cost = self.pricing.estimate(model, inp, out, cr, c5, c1)
-        no_cache_part, cache_part = self.pricing.uncached_baseline(model, cr, c5, c1)
+        # Price against the variant the context proves was used, not just the name in
+        # the transcript: anything above the standard window was the long-context
+        # variant and is billed at a premium.
+        priced_as, unpriced_long = self.pricing.effective_model(model, context, speed=speed)
+        cost = self.pricing.estimate(priced_as, inp, out, cr, c5, c1)
+        no_cache_part, cache_part = self.pricing.uncached_baseline(priced_as, cr, c5, c1)
         cost_no_cache = cost - cache_part + no_cache_part
 
-        ts = r.get("timestamp")
+        tools, seen = [], set()
+        for ln in lines:
+            for c in ((ln.get("message") or {}).get("content") or []):
+                if isinstance(c, dict) and c.get("type") == "tool_use" and c.get("id") not in seen:
+                    seen.add(c.get("id"))
+                    tools.append(c)
+
+        if billable == 0 and not tools:
+            return
+
+        request_id = first.get("requestId") or msg.get("id")
+        if request_id and request_id in self.seen_request_ids:
+            # resumed sessions copy earlier history verbatim, including request_ids
+            # already inserted from another session; keep only the first occurrence.
+            return
+        if request_id:
+            self.seen_request_ids.add(request_id)
+
+        ts = first.get("timestamp")               # the request started at its first line
         t = _ts(ts)
         latency = None
         if t and prev_time:
@@ -401,25 +510,24 @@ class Loader:
             if 0 <= d <= 900_000:    # ignore idle gaps > 15 min, they are not latency
                 latency = d
 
-        tools = [c for c in (msg.get("content") or [])
-                 if isinstance(c, dict) and c.get("type") == "tool_use"]
-
         cur = self.db.execute(
             "INSERT INTO requests (uuid, request_id, session_id, project_id, prompt_id,"
             " ts, day, hour, model, model_known, effort, service_tier, stop_reason,"
             " input_tokens, output_tokens, thinking_tokens, cache_read_tokens,"
             " cache_write_5m, cache_write_1h, cache_write_tokens, billable_tokens,"
-            " context_tokens, est_cost_usd, est_cost_no_cache_usd, latency_ms,"
+            " context_tokens, est_cost_usd, est_cost_no_cache_usd,"
+            " priced_as, unpriced_long_context, latency_ms,"
             " tool_call_count, is_sidechain, agent_id, agent_type, agent_desc)"
-            " VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)",
-            (r.get("uuid"), r.get("requestId"), session_id, pid, prompt_id, ts,
-             (ts or "")[:10], (t.hour if t else None), model,
-             1 if self.pricing.is_known(model) else 0, r.get("effort"),
+            " VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)",
+            (first.get("uuid"), request_id, session_id, pid,
+             prompt_id, ts, (ts or "")[:10], (t.hour if t else None), model,
+             1 if self.pricing.is_known(model) else 0, first.get("effort"),
              u.get("service_tier"), msg.get("stop_reason"), inp, out, think, cr,
-             c5, c1, cw, billable, context, cost, cost_no_cache, latency,
-             len(tools), 1 if (r.get("isSidechain") or self.agent) else 0,
+             c5, c1, cw, billable, context, cost, cost_no_cache,
+             priced_as, 1 if unpriced_long else 0, latency,
+             len(tools), 1 if (first.get("isSidechain") or self.agent) else 0,
              *((self.agent["id"], self.agent["type"], self.agent["desc"]) if self.agent
-               else (None, "inline" if r.get("isSidechain") else None, None))))
+               else (None, "inline" if first.get("isSidechain") else None, None))))
         rpk = cur.lastrowid
 
         day = (ts or "")[:10]
@@ -449,6 +557,10 @@ class Loader:
                 " VALUES (?,?,?,?,?,?,?,?,?,?,?)",
                 (rpk, session_id, pid, prompt_id, ts, day, name, target, c.get("id"),
                  kind, server))
+            tool_use_id = c.get("id")
+            if tool_use_id in self.pending_results:
+                self.db.execute("UPDATE tool_calls SET result_chars=? WHERE tool_use_id=?",
+                                (self.pending_results.pop(tool_use_id), tool_use_id))
             if kind == "skill":
                 self.pending_skill = self.db.execute("SELECT last_insert_rowid()").fetchone()[0]
             if name in FILE_TOOLS and isinstance(args, dict) and args.get("file_path"):

package/finops/integrate.py

@@ -1,16 +1,14 @@
-"""Live advice inside Claude Code itself: a prompt hook and a statusline.
+"""A statusline inside Claude Code itself, showing model and context usage.
 
-The dashboard can only advise you if you are looking at it. These two run where
-the decision is actually made — the terminal you are typing in.
+  claude-finops --statusline    reads a statusline payload on stdin, prints model + context %
+  claude-finops --install-statusline   wire it into settings
+  claude-finops --hook          retired no-op, kept so existing installs do not error
+  claude-finops --install-hook  prints that the hook is retired and does nothing else
 
-  claude-finops --hook          reads a UserPromptSubmit payload on stdin
-  claude-finops --statusline    reads a statusline payload on stdin
-  claude-finops --install-hook / --install-statusline   wire them into settings
-
-Both are on the path of every prompt, so both are built to be boring: fail
-silent, never block, never take long. A hook that erases someone's prompt
-because a database was locked is a far worse bug than missing advice, so the
-hook never returns a blocking exit code — it exits 0 whatever happens.
+The prompt hook that used to "suggest a cheaper model" is retired: that
+suggestion had no basis — it would have meant repricing work that never ran.
+The statusline is on the path of every prompt, so it is built to be boring:
+fail silent, never block, never take long.
 """
 import json
 import os
@@ -47,49 +45,28 @@ def _dig(d, *paths, default=None):
     return default
 
 
-def _payload_common(d):
-    return (_dig(d, "model", "session.model", "model.id", "model.display_name"),
-            _dig(d, "transcript_path", "session.transcript_path", "transcriptPath"))
-
-
 # -------------------------------------------------------------------- hook ----
 
 def hook():
-    """UserPromptSubmit: judge the prompt in hand, before it is paid for.
-
-    Advice goes to the user as `systemMessage`, not into Claude's context: it is
-    for the person deciding which model to use, and feeding it to the model
-    would just spend tokens telling it about its own price.
-    """
+    """UserPromptSubmit: kept as a no-op so existing installed hooks do not error."""
     try:
-        d = _stdin_json()
-        prompt = _dig(d, "user_prompt", "prompt", default="")
-        model, transcript = _payload_common(d)
-        from .advisor import advise
-        a = advise(model=model, transcript=transcript, prompt=prompt)
-        if a:
-            print(json.dumps({"systemMessage": f"finops: {a['line']}  →  {a['command']}"}))
+        _stdin_json()
     except Exception:
-        pass          # never let advice interfere with the prompt
+        pass
     return 0
 
 
 # -------------------------------------------------------------- statusline ----
 
 def statusline():
-    """One line, refreshed constantly, so: what you are on, and what to try."""
+    """One line, refreshed constantly: model and context usage."""
     try:
         d = _stdin_json()
-        model, transcript = _payload_common(d)
         pct = _dig(d, "context.percentUsed", "context.percent_used")
         name = _dig(d, "model.display_name", "session.model", "model") or "claude"
         bits = [str(name)]
         if isinstance(pct, (int, float)):
             bits.append(f"{pct:.0f}% ctx")
-        from .advisor import advise
-        a = advise(model=model, transcript=transcript)
-        if a:
-            bits.append(a["short"])
         print(" · ".join(bits))
     except Exception:
         print("")     # an empty statusline beats a stack trace under the prompt
@@ -126,26 +103,14 @@ def _save_settings(data):
 
 
 def install_hook(remove=False):
-    cmd = f"{_command()} --hook"
-    s = _load_settings()
-    hooks = s.setdefault("hooks", {}).setdefault("UserPromptSubmit", [])
-    for group in hooks:                       # drop any earlier copy of ours
-        group["hooks"] = [h for h in group.get("hooks", [])
-                          if "--hook" not in str(h.get("command", ""))
-                          or "finops" not in str(h.get("command", ""))]
-    hooks[:] = [g for g in hooks if g.get("hooks")]
-    if not remove:
-        hooks.append({"matcher": "", "hooks": [{"type": "command", "command": cmd,
-                                                "timeout": 10}]})
-    if not hooks:
-        s["hooks"].pop("UserPromptSubmit", None)
-        if not s["hooks"]:
-            s.pop("hooks")
-    _save_settings(s)
-    print(("Removed" if remove else "Installed") + f" the prompt hook in {SETTINGS}")
-    if not remove:
-        print("  It suggests a cheaper model when your own history backs one, before the turn runs.")
-        print("  Start a new Claude Code session to pick it up.  Undo: claude-finops --uninstall-hook")
+    """The prompt hook is retired: it never had a basis for its "cheaper model"
+    suggestion (that would mean repricing work that had not run yet). It is kept
+    as a no-op (see hook() above) so existing installs do not error, but nothing
+    new is installed here.
+    """
+    print("The finops prompt hook has been retired — it made suggestions with no "
+          "basis in your data. Nothing was installed or changed.")
+    print("The statusline (claude-finops --install-statusline) still shows model and context %.")
 
 
 def install_statusline(remove=False):
@@ -164,5 +129,5 @@ def install_statusline(remove=False):
     _save_settings(s)
     print(("Removed" if remove else "Installed") + f" the statusline in {SETTINGS}")
     if not remove:
-        print("  Shows the model, context pressure, and a cheaper model when one is warranted.")
+        print("  Shows the model and context usage percentage.")
         print("  Undo: claude-finops --uninstall-statusline")

package/finops/paths.py

@@ -109,3 +109,15 @@ def migrate(log=print):
     with open(_MARKER, "w") as fh:
         fh.write("state dir in use; delete this file to re-run migration\n")
     return bool(moved)
+
+
+# The Claude desktop app's data dir. Read-only: Cowork transcripts and the plan
+# usage history live here.
+if os.name == "nt":
+    DESKTOP_DIR = os.path.join(os.environ.get("APPDATA", ""), "Claude")
+elif os.uname().sysname == "Darwin":
+    DESKTOP_DIR = os.path.join(os.path.expanduser("~"), "Library", "Application Support", "Claude")
+else:
+    DESKTOP_DIR = os.path.join(os.path.expanduser("~"), ".config", "Claude")
+DESKTOP_SESSIONS = os.path.join(DESKTOP_DIR, "local-agent-mode-sessions")
+PLAN_HISTORY_PATH = os.path.join(DESKTOP_DIR, "plan-usage-history.json")

package/finops/plan_history.py

@@ -0,0 +1,80 @@
+"""Plan-limit history, as the Claude desktop app records it.
+
+The desktop app samples plan usage every few minutes into plan-usage-history.json:
+`fh` is the 5-hour window and `sd` the weekly (seven-day) window, both percent used.
+The format is undocumented, so anything unexpected returns {"ok": False, "reason"}
+instead of raising. Read on request, cached on the file's mtime.
+"""
+import json
+import os
+from datetime import datetime, timezone
+
+from .paths import PLAN_HISTORY_PATH
+
+KNOWN_VERSIONS = {2}
+_cache = {}
+
+
+def _num(v):
+    return float(v) if isinstance(v, (int, float)) and not isinstance(v, bool) else None
+
+
+def _runs(values, threshold):
+    """Separate stretches at or above the threshold, not raw sample counts."""
+    n, above = 0, False
+    for v in values:
+        hit = v is not None and v >= threshold
+        n += hit and not above
+        above = hit
+    return n
+
+
+def _peak(values):
+    return max((v for v in values if v is not None), default=None)
+
+
+def history(path=None):
+    path = path or PLAN_HISTORY_PATH
+    try:
+        mtime = os.path.getmtime(path)
+    except OSError:
+        return {"ok": False, "reason": "No plan history on this machine. The Claude desktop "
+                                       "app records it; it is not installed or has not saved any yet."}
+    hit = _cache.get(path)
+    if hit and hit[0] == mtime:
+        return hit[1]
+    res = _read(path)
+    _cache[path] = (mtime, res)
+    return res
+
+
+def _read(path):
+    try:
+        with open(path) as fh:
+            raw = json.load(fh)
+    except (OSError, ValueError):
+        return {"ok": False, "reason": "The plan history file could not be read."}
+    version = raw.get("version") if isinstance(raw, dict) else None
+    if version not in KNOWN_VERSIONS:
+        return {"ok": False, "reason": f"Unrecognised plan history format (version {version})."}
+    samples = [x for x in raw.get("samples") or []
+               if isinstance(x, dict) and _num(x.get("t")) is not None]
+    if not samples:
+        return {"ok": False, "reason": "The plan history file has no samples yet."}
+    samples.sort(key=lambda x: x["t"])
+    orgs = {x.get("org") for x in samples}
+    org = samples[-1].get("org")
+    series = []
+    for x in samples:
+        if x.get("org") != org:
+            continue
+        u = x.get("u") if isinstance(x.get("u"), dict) else {}
+        t = datetime.fromtimestamp(x["t"] / 1000, timezone.utc).isoformat().replace("+00:00", "Z")
+        series.append({"t": t, "five_hour": _num(u.get("fh")), "weekly": _num(u.get("sd"))})
+    fh = [r["five_hour"] for r in series]
+    sd = [r["weekly"] for r in series]
+    return {"ok": True, "source": path, "org_count": len(orgs), "series": series,
+            "summary": {"five_hour_peak": _peak(fh), "weekly_peak": _peak(sd),
+                        "five_hour_ge90": _runs(fh, 90), "five_hour_hit100": _runs(fh, 100),
+                        "weekly_ge90": _runs(sd, 90), "weekly_hit100": _runs(sd, 100),
+                        "first": series[0]["t"], "last": series[-1]["t"]}}