interlatch 0.22.0__py3-none-any.whl

chronicle/bob_parser.py

@@ -0,0 +1,259 @@
+"""Parse IBM Bob tasks (~/.bob/db/bob.db) into the same model as Claude Code sessions.
+
+bob.db holds `tasks` (directory, title, git info, costs JSON, status) and `messages` (one chat message per row in
+`data`). Tool calls come in two shapes: OpenAI-style `tool_calls[].function` answered by a `tool_call_id`, and Bob's
+own `toolCalls[]` ({id, name, arguments}) answered by a tool message whose `toolUsage.signature` names the call.
+A subagent's whole conversation rides inside its spawn_subagent result (`messages`, `_meta.subagentId`). Each
+assistant message reports its own spend in `_meta.spend` (cost, contextTokens). The database also stores login
+state elsewhere in ~/.bob; only these two tables are read, read-only.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import posixpath
+import re
+import sqlite3
+from pathlib import Path
+
+from .copilot_parser import _Builder, _args, estimate_cost, finish_session, ms_to_iso, uri_path
+from .parser import ApiCall, FileStat, ParsedSession, Subagent
+from .pricing import normalize_model
+from .util import one_line, safe_text
+
+log = logging.getLogger("chronicle.bob")
+
+BOB_PARSER_VERSION = 2  # 2: Bob's own toolCalls shape, subagents, per-message spend, relative paths
+_ENV_RE = re.compile(r"<environment_details>.*?</environment_details>", re.S)
+_TASK_RE = re.compile(r"^\s*<(?:task|user_message)>(.*?)</(?:task|user_message)>\s*$", re.S)
+
+
+def bob_db(home: Path) -> Path:
+    return home / "db" / "bob.db"
+
+
+def load_tasks(home: Path) -> list[dict]:
+    """Tasks with their messages, oldest message first. Read-only; returns [] if the database is unreadable."""
+    db = bob_db(home)
+    if not db.exists():
+        return []
+    try:
+        conn = sqlite3.connect(f"file:{db}?mode=ro", uri=True, timeout=5)
+        conn.row_factory = sqlite3.Row
+        tasks = [dict(r) for r in conn.execute("SELECT * FROM tasks ORDER BY created_at")]
+        msgs: dict[str, list[dict]] = {}
+        for r in conn.execute("SELECT id, task_id, role, data, created_at FROM messages ORDER BY created_at, id"):
+            msgs.setdefault(r["task_id"], []).append(dict(r))
+        conn.close()
+    except sqlite3.Error as exc:
+        log.warning("bob.db unreadable: %s", exc)
+        return []
+    for t in tasks:
+        t["messages"] = msgs.get(t["id"], [])
+    return tasks
+
+
+def task_folder(task: dict) -> str | None:
+    """The folder a task ran in: its directory, else its project (a file: URI)."""
+    return uri_path(task.get("directory") or task.get("project_id") or "") or None
+
+
+def task_signature(task: dict) -> str:
+    last = task["messages"][-1] if task["messages"] else {}
+    return f"{task.get('updated_at')}:{len(task['messages'])}:{last.get('id')}:{task.get('status')}"
+
+
+def _text(content) -> str:
+    if isinstance(content, str):
+        return content
+    if isinstance(content, list):
+        return "\n".join(p.get("text", "") for p in content if isinstance(p, dict) and p.get("type") in ("text", "input_text", "output_text"))
+    return ""
+
+
+def _user_text(content) -> str:
+    text = _ENV_RE.sub("", _text(content)).strip()
+    m = _TASK_RE.match(text)
+    return m.group(1).strip() if m else text
+
+
+def _calls(d: dict) -> list[tuple[str | None, str, dict]]:
+    """(call id, tool name, arguments) for each tool call in an assistant message, in either shape."""
+    out = []
+    for tc in d.get("tool_calls") or []:
+        fn = tc.get("function") if isinstance(tc, dict) else None
+        if isinstance(fn, dict):
+            out.append((tc.get("id"), fn.get("name") or "tool", _args(fn.get("arguments"))))
+    for tc in d.get("toolCalls") or []:
+        if isinstance(tc, dict):
+            out.append((tc.get("id"), tc.get("name") or "tool", _args(tc.get("arguments"))))
+    return out
+
+
+def _signature(d: dict) -> dict:
+    usage = d.get("toolUsage")
+    sig = usage.get("signature") if isinstance(usage, dict) else None
+    return sig if isinstance(sig, dict) else {}
+
+
+def _meta(d: dict) -> dict:
+    return d["_meta"] if isinstance(d.get("_meta"), dict) else {}
+
+
+def _absolute(args: dict, cwd: str | None) -> dict:
+    """Bob passes workspace-relative paths (docs/x.html); resolve them against the task's directory."""
+    if not cwd or not cwd.startswith("/"):
+        return args
+    out = dict(args)
+    for key in ("path", "file_path", "filePath"):
+        v = out.get(key)
+        if isinstance(v, str) and v and not v.startswith(("/", "~")) and ":" not in v:
+            out[key] = posixpath.normpath(posixpath.join(cwd, v))
+    return out
+
+
+def _patch_lines(patch: str) -> tuple[int, int]:
+    """Lines added and removed in a unified diff (the ---/+++ file headers before the first hunk aren't lines)."""
+    added = removed = 0
+    in_hunk = False
+    for line in patch.splitlines():
+        if line.startswith("@@"):
+            in_hunk = True
+        elif in_hunk and line.startswith("+"):
+            added += 1
+        elif in_hunk and line.startswith("-"):
+            removed += 1
+    return added, removed
+
+
+def _count_changes(ps: ParsedSession, changes: dict, counted: str | None) -> None:
+    """A tool result's `_meta.changes` ({file URI: {before, after, patch}}): what the call did to each file on disk."""
+    for uri, change in changes.items():
+        path = uri_path(uri)
+        if not path or not isinstance(change, dict):
+            continue
+        fs = ps.files.setdefault(path, FileStat())
+        if path != counted:  # the call's own file was already counted as a write or an edit
+            fs.edits += 1
+        if isinstance(change.get("patch"), str):
+            added, removed = _patch_lines(change["patch"])
+            fs.lines_added += added
+            fs.lines_removed += removed
+
+
+def _feed(b: _Builder, msgs: list[tuple[str | None, dict]], cwd: str | None) -> None:
+    """Replay one thread's messages (the task's, or a subagent's) into `b`."""
+    ps = b.ps
+    results: dict[str, dict] = {}
+    for _, d in msgs:
+        if d.get("role") != "tool":
+            continue
+        sig = _signature(d)
+        cid = d.get("tool_call_id") or sig.get("id")
+        if cid:
+            results[cid] = d
+    for ts, d in msgs:
+        role = d.get("role")
+        if role == "system":
+            b.event(ts, "system", "meta", f"[system prompt, {len(_text(d.get('content'))):,} chars]")
+        elif role == "user":
+            if b.agent_id:  # a subagent's brief, not a prompt the user typed
+                b.event(ts, "user", "prompt", _user_text(d.get("content")))
+            else:
+                b.prompt(ts, _user_text(d.get("content")))
+        elif role == "assistant":
+            reasoning = d.get("reasoning") or d.get("reasoning_content")
+            if isinstance(reasoning, str) and reasoning.strip():
+                b.event(ts, "assistant", "thinking", reasoning)
+            text = _text(d.get("content"))
+            if text.strip():
+                b.event(ts, "assistant", "text", text)
+            spend = _meta(d).get("spend")
+            if isinstance(spend, dict) and (spend.get("cost") or spend.get("contextTokens")):
+                # Bob reports what each call cost and how big its context was, but not the token split:
+                # the context counts as input, and the cost is Bob's own figure rather than an estimate
+                ps.api_calls.append(ApiCall(b.agent_id, str(d.get("id") or ""), ts, None,
+                                            input_tokens=int(spend.get("contextTokens") or 0),
+                                            cost_usd=float(spend.get("cost") or 0)))
+            for cid, name, args in _calls(d):
+                res = results.get(cid) or {}
+                text = _text(res.get("content")) if res else None
+                sig = _signature(res)
+                is_error = bool(sig["isError"]) if "isError" in sig else bool(text) and text.lower().startswith(("error", "failed"))
+                rmeta = _meta(res)
+                call = b.tool(ts, cid, name, _absolute(args, cwd), result=text, is_error=is_error,
+                              duration_ms=rmeta.get("durationMs") if isinstance(rmeta.get("durationMs"), int) else None)
+                if not is_error and isinstance(rmeta.get("changes"), dict):
+                    _count_changes(ps, rmeta["changes"], call.file_path)
+                sub = res.get("messages")
+                if rmeta.get("subagentId") and isinstance(sub, list):
+                    _subagent(b, str(rmeta["subagentId"]), rmeta, args, cid, sub, cwd)
+
+
+def _thread(rows: list[tuple[int | None, object]]) -> list[tuple[str | None, dict]]:
+    """[(created_at ms, raw data)] -> [(iso timestamp, message dict)], skipping rows that aren't JSON objects."""
+    out = []
+    for created_at, raw in rows:
+        try:
+            d = json.loads(raw) if isinstance(raw, str) else raw
+        except (TypeError, ValueError):
+            continue
+        if isinstance(d, dict):
+            out.append((ms_to_iso(_meta(d).get("timestamp") or created_at), d))
+    return out
+
+
+def _subagent(parent: _Builder, aid: str, meta: dict, args: dict, call_id, msgs: list, cwd: str | None) -> None:
+    ps = parent.ps
+    sub = ps.subagents.setdefault(aid, Subagent(aid))
+    sub.agent_type = meta.get("agentType") or args.get("name") or None
+    sub.description = one_line(safe_text(str(args.get("description") or "")), 120) or None
+    sub.tool_use_id = call_id
+    b = _Builder(ps, agent_id=aid)
+    _feed(b, _thread([(None, m) for m in msgs]), cwd)
+    parent.stamps.extend(b.stamps)
+    stamps = sorted(s for s in b.stamps if s)
+    if stamps:
+        sub.started_at, sub.ended_at = stamps[0], stamps[-1]
+    calls = [c for c in ps.tool_calls if c.agent_id == aid]
+    sub.n_tool_calls, sub.n_tool_errors = len(calls), sum(c.is_error for c in calls)
+    for c in ps.api_calls:
+        if c.agent_id == aid:
+            sub.input_tokens += c.input_tokens
+            sub.est_cost_usd += c.cost_usd
+
+
+def parse_bob_task(task: dict) -> ParsedSession | None:
+    msgs = task.get("messages") or []
+    if not any(m["role"] == "user" for m in msgs):
+        return None
+    ps = ParsedSession(id=task["id"])
+    ps.project_path = task_folder(task)
+    ps.git_branch = task.get("git_branch") or None
+    ps.cc_version = task.get("version") or None
+    ps.entrypoint = f"bob:{task.get('task_type') or 'normal'}"
+    ps.custom_title = task.get("title") or None
+    b = _Builder(ps)
+    for ms in (task.get("created_at"), task.get("updated_at")):
+        if ms_to_iso(ms):
+            b.stamps.append(ms_to_iso(ms))
+    thread = _thread([(m.get("created_at"), m["data"]) for m in msgs])
+    ps.parse_errors += len(msgs) - len(thread)
+    _feed(b, thread, ps.project_path)
+    if task.get("status") == "error" and task.get("last_error"):
+        ps.n_api_errors += 1
+        b.event(b.stamps[-1] if b.stamps else None, "system", "api_error", safe_text(str(task["last_error"]))[:300])
+    try:
+        costs = json.loads(task.get("costs") or "{}")
+    except ValueError:
+        costs = {}
+    if isinstance(costs, dict) and not ps.api_calls:  # per-message spend, when Bob wrote it, already covers the task
+        model = normalize_model(costs.get("model"))
+        inp, out, cr, cw = (int(costs.get(k) or 0) for k in ("input", "output", "cacheRead", "cacheWrite"))
+        cost = float(costs.get("cost") or 0)
+        if inp or out or cr or cw or cost:
+            ps.api_calls.append(ApiCall("", "task-total", ms_to_iso(task.get("updated_at")), model, input_tokens=inp,
+                                        output_tokens=out, cache_read_tokens=cr, cache_write_tokens=cw,
+                                        cost_usd=cost or estimate_cost(model, inp, cr, cw, out)))
+    return finish_session(ps, b.stamps)

chronicle/cases.py

@@ -0,0 +1,75 @@
+"""A lesson's teaching material beyond its case file (analyze.case_of): principle, checks, clues, topics and a diagram.
+Grounded in the session; personal learning history stays in the browser."""
+
+from __future__ import annotations
+
+import re
+
+from .redact import redact
+from .learning import topic_ids
+
+LESSON_KINDS = ("fix", "gotcha", "decision", "learning", "pattern")
+
+
+VISUAL_SCHEMA = {
+    "type": "object", "additionalProperties": False,
+    "required": ["type", "title", "nodes", "edges"],
+    "properties": {
+        "type": {"type": "string", "enum": ["flow", "relationship", "comparison"]},
+        "title": {"type": "string", "description": "Short title of the concept being illustrated"},
+        "nodes": {"type": "array", "items": {
+            "type": "object", "additionalProperties": False, "required": ["id", "label", "detail"],
+            "properties": {"id": {"type": "string", "description": "Unique short ASCII slug"},
+                           "label": {"type": "string", "description": "1-4 words, using actual session terminology"},
+                           "detail": {"type": "string", "description": "One sentence explaining this part or tradeoff"}}}},
+        "edges": {"type": "array", "items": {
+            "type": "object", "additionalProperties": False, "required": ["from", "to", "label"],
+            "properties": {"from": {"type": "string"}, "to": {"type": "string"},
+                           "label": {"type": "string", "description": "Short, established relationship or action"}}}},
+    },
+    "description": "Small explanatory diagram: 2-4 parts, up to 5 connections, grounded in the lesson. "
+                   "A flow shows order, a relationship shows connections, a comparison shows real alternatives. "
+                   "Empty title, nodes and edges when unsupported. Never invent components or relationships.",
+}
+
+
+def visual_of(raw) -> dict | None:
+    if not isinstance(raw, dict) or raw.get("type") not in ("flow", "relationship", "comparison"):
+        return None
+
+    def text(value, limit):
+        return redact(value.strip())[:limit] if isinstance(value, str) else ""
+
+    nodes = {}
+    for node in raw.get("nodes") if isinstance(raw.get("nodes"), list) else []:
+        if not isinstance(node, dict):
+            continue
+        nid, label = text(node.get("id"), 32), text(node.get("label"), 80)
+        if re.fullmatch(r"[A-Za-z0-9_-]+", nid) and label and nid not in nodes and len(nodes) < 4:
+            nodes[nid] = {"id": nid, "label": label, "detail": text(node.get("detail"), 600)}
+    edges, seen = [], set()
+    for edge in raw.get("edges") if isinstance(raw.get("edges"), list) else []:
+        if not isinstance(edge, dict):
+            continue
+        a, b = edge.get("from"), edge.get("to")
+        if not isinstance(a, str) or not isinstance(b, str) or a not in nodes or b not in nodes or a == b or (a, b) in seen:
+            continue
+        seen.add((a, b))
+        edges.append({"from": a, "to": b, "label": text(edge.get("label"), 40)})
+    if len(nodes) < 2 or not edges and raw["type"] != "comparison":
+        return None
+    return {"type": raw["type"], "title": text(raw.get("title"), 100), "nodes": list(nodes.values()), "edges": edges[:5]}
+
+
+def lesson_of(raw: dict) -> dict:
+    """The teaching fields the analysis supported, redacted; empty ones are left out, nothing is invented."""
+    def text(value) -> str:
+        return redact(value.strip())[:6000] if isinstance(value, str) else ""
+
+    def texts(value, limit: int) -> list[str]:
+        return [text(x) for x in value if isinstance(x, str) and text(x)][:limit] if isinstance(value, list) else []
+
+    out = {"clues": texts(raw.get("clues"), 6), "principle": text(raw.get("principle")),
+           "checklist": texts(raw.get("checklist"), 4), "topics": topic_ids(raw.get("topics")),
+           "visual": visual_of(raw.get("visual"))}
+    return {k: v for k, v in out.items() if v}

chronicle/chat_import.py

@@ -0,0 +1,325 @@
+"""Import chats from a claude.ai or ChatGPT data export as sessions (`interlatch import`, Sources › Import export…).
+
+Both exports are a .zip with conversations.json; the format is recognized from its contents. Only the chats
+(conversations.json, and claude.ai's projects.json for project names) are read and archived; the account files
+(users.json, user.json) and ChatGPT's chat.html are never opened. Imports are repeatable: a newer export updates the
+chats that changed and adds new ones.
+
+Imported chats are not analyzed automatically (years of chats would use up the Claude plan's limits in one go):
+screen them (screen.py) to queue the ones worth it, analyze one with **Analyze now**, or import with `--analyze` to
+queue them all.
+"""
+
+from __future__ import annotations
+
+import gzip
+import hashlib
+import json
+import logging
+import re
+import struct
+import zipfile
+import zlib
+from dataclasses import dataclass
+from pathlib import Path
+
+from . import chatgpt_export, claude_export
+from .util import utcnow_iso
+from .views import NOT_ANALYZED_CHAT
+
+log = logging.getLogger("chronicle.chat_import")
+
+_CONVERSATIONS_RE = re.compile(r"^conversations(?:-\d+)?\.json$")  # large exports may be split
+_LOCAL_HEADER = struct.Struct("<4s5H3I2H")  # signature, version, flags, method, time, date, crc, sizes, name/extra lengths
+
+
+@dataclass(frozen=True)
+class Format:
+    key: str  # kv and archive name
+    label: str
+    module: object
+
+    @property
+    def agent(self) -> str:
+        return self.module.AGENT
+
+    @property
+    def source(self) -> str:
+        return self.module.SOURCE
+
+    @property
+    def last_import_key(self) -> str:
+        return f"{self.key}:last-import"
+
+    @property
+    def not_analyzed(self) -> str:
+        return NOT_ANALYZED_CHAT.format(label=self.label)
+
+
+CLAUDE_AI = Format("claude-ai", "claude.ai", claude_export)
+CHATGPT = Format("chatgpt", "ChatGPT", chatgpt_export)
+FORMATS = (CLAUDE_AI, CHATGPT)
+
+
+class ExportError(Exception):
+    """The file is not an export Interlatch can read."""
+
+
+@dataclass
+class Export:
+    format: Format
+    conversations: list[dict]
+    files: dict[str, bytes]  # what gets archived: the conversations file(s), claude.ai's projects.json
+    note: str | None = None  # read from a zip cut off after its chats
+
+
+def _wanted(name: str) -> bool:
+    return bool(_CONVERSATIONS_RE.match(name)) or name == "projects.json"
+
+
+def _files(path: Path, name: str) -> tuple[dict[str, bytes], str | None]:
+    """The chat files of an export .zip, its unpacked folder, or a conversations.json, and a note when the zip was cut off."""
+    path = Path(path).expanduser()
+    if zipfile.is_zipfile(path):
+        with zipfile.ZipFile(path) as z:
+            names = {Path(n).name: n for n in z.namelist() if not n.startswith("__MACOSX/")}
+            return {n: z.read(full) for n, full in sorted(names.items()) if _wanted(n)}, None
+    if path.is_dir():
+        return {p.name: p.read_bytes() for p in sorted(path.iterdir()) if p.is_file() and _wanted(p.name)}, None
+    if path.suffix == ".json" and path.is_file():
+        sibling = path.with_name("projects.json")
+        return {"conversations.json": path.read_bytes(), **({"projects.json": sibling.read_bytes()} if sibling.is_file() else {})}, None
+    if path.is_file():
+        with open(path, "rb") as f:
+            if f.read(4) == b"PK\x03\x04":
+                return _cut_off_zip(path, name)
+    if path.exists():
+        raise ExportError(f"{name} is not a chat export: give the .zip, its unpacked folder, or conversations.json")
+    raise ExportError(f"{path} not found")
+
+
+def _zip64_size(extra: bytes) -> int:
+    """The compressed size from a local header's zip64 extra field (original size first, then compressed)."""
+    i = 0
+    while i + 4 <= len(extra):
+        tag, n = struct.unpack_from("<HH", extra, i)
+        if tag == 1 and n >= 16:
+            return struct.unpack_from("<Q", extra, i + 12)[0]
+        i += 4 + n
+    return 0xFFFFFFFF
+
+
+def _cut_off_zip(path: Path, name: str) -> tuple[dict[str, bytes], str]:
+    """The chat files of a zip without its end, as an interrupted download leaves it, read entry by entry.
+
+    `zipfile` needs the central directory, the last thing in a zip, so a partial download looks like no zip at all
+    even when every chat is there: ChatGPT puts conversations-*.json near the start and gigabytes of attachments
+    after them. The chats are accepted only when the cut falls in a later file Interlatch does not read.
+    """
+    size = path.stat().st_size
+    files: dict[str, bytes] = {}
+    cut_in = None  # the entry the file ends in
+    redownload = f"{name} is an incomplete download ({size / 1e9:.2f} GB, the end of the zip is missing)"
+    with open(path, "rb") as f:
+        while True:
+            head = f.read(_LOCAL_HEADER.size)
+            if head[:4] == b"PK\x01\x02":  # the central directory: every entry was read, only the zip's end is damaged
+                cut_in = ""
+                break
+            if len(head) < _LOCAL_HEADER.size or head[:4] != b"PK\x03\x04":
+                break
+            _, _, flags, method, _, _, crc, csize, _, nlen, xlen = _LOCAL_HEADER.unpack(head)
+            raw, extra = f.read(nlen), f.read(xlen)
+            entry = Path(raw.decode("utf-8", "replace")).name
+            if len(raw) < nlen or len(extra) < xlen:
+                cut_in = entry
+                break
+            if flags & 0x9:  # encrypted, or the size only follows the data: the next entry cannot be found
+                break
+            if csize == 0xFFFFFFFF:
+                csize = _zip64_size(extra)
+            if f.tell() + csize > size:
+                cut_in = entry
+                break
+            if not (_wanted(entry) and not raw.startswith(b"__MACOSX/")):
+                f.seek(csize, 1)
+                continue
+            data = f.read(csize)
+            try:
+                data = data if method == 0 else zlib.decompress(data, -15) if method == 8 else None
+            except zlib.error:
+                data = None
+            if data is None or zlib.crc32(data) != crc:
+                raise ExportError(f"{redownload}, and {entry} in it is damaged: download the export again")
+            files[entry] = data
+    shards = [n for n in files if _CONVERSATIONS_RE.match(n)]
+    if cut_in is None or not shards or _wanted(cut_in):
+        where = f"inside {cut_in}" if cut_in and _wanted(cut_in) else "before all its chats could be read"
+        raise ExportError(f"{redownload}: it is cut off {where}. Download the export again")
+    note = ("the end of the zip is damaged, but every chat was read" if not cut_in else
+            f"incomplete download, cut off at {size / 1e9:.2f} GB in {cut_in}, after the chats: all {len(shards)} "
+            f"conversations file{'s' if len(shards) > 1 else ''} read")
+    log.warning("%s: %s", name, note)
+    return files, note
+
+
+def _folders(path: Path) -> set[str]:
+    try:
+        with zipfile.ZipFile(path) as z:
+            return {n.split("/")[0] for n in z.namelist() if "/" in n}
+    except (OSError, zipfile.BadZipFile):
+        return set()
+
+
+def read_export(path: Path, name: str | None = None) -> Export:
+    name = name or Path(path).name
+    files, note = _files(path, name)
+    shards = [n for n in files if _CONVERSATIONS_RE.match(n)]
+    if not shards and "projects" in _folders(path):
+        raise ExportError(f"{name} holds your claude.ai projects, not chats, and the export does not say which project a "
+                          "chat belongs to: there is nothing to import from it. The chats are in conversations-000.zip.")
+    if not shards:
+        raise ExportError(f"no conversations.json in {name}: is it a claude.ai or ChatGPT data export? "
+                          "(claude.ai sends several zips; the chats are in conversations-000.zip)")
+    conversations: list[dict] = []
+    for name in shards:
+        try:
+            data = json.loads(files[name])
+        except ValueError as exc:
+            raise ExportError(f"{name} is not valid JSON") from exc
+        if isinstance(data, dict):
+            data = data.get("conversations") or []
+        if not isinstance(data, list):
+            raise ExportError(f"{name} is not a list of conversations")
+        conversations += [c for c in data if isinstance(c, dict)]
+    fmt = CHATGPT if chatgpt_export.is_chatgpt(conversations) else CLAUDE_AI
+    if fmt is CLAUDE_AI and conversations and not claude_export.is_claude(conversations):
+        raise ExportError("conversations.json is neither a claude.ai nor a ChatGPT export")
+    if fmt is CHATGPT:
+        files.pop("projects.json", None)
+    return Export(fmt, conversations, files, note)
+
+
+def import_export(cfg, conn, path: Path, *, analyze: bool = False, progress=None, name: str | None = None) -> dict:
+    """Import (or re-import) an export. `name` is the file's name when `path` is an upload's temporary copy."""
+    from .db import kv_set
+    from .ingest import _unchanged, forgotten_ids, store_parsed
+    from .util import file_lock
+
+    name = name or Path(path).name
+    export = read_export(Path(path), name)
+    fmt, mod = export.format, export.format.module
+    projects = claude_export.project_names(export.files.get("projects.json")) if fmt is CLAUDE_AI else {}
+    digest = hashlib.sha1(b"".join(export.files[k] for k in sorted(export.files))).hexdigest()[:12]
+    dst = cfg.archive_dir / fmt.key / digest
+    shard = next(n for n in export.files if _CONVERSATIONS_RE.match(n))
+    archive = dst / f"{shard}.gz"
+    if not archive.exists():  # the export's chats, kept for good
+        dst.mkdir(parents=True, exist_ok=True)
+        for fname, raw in export.files.items():
+            with gzip.open(dst / f"{fname}.gz", "wb") as f:
+                f.write(raw)
+    counts = {"format": fmt.label, "conversations": len(export.conversations), "new": 0, "updated": 0, "unchanged": 0,
+              "empty": 0, "excluded": 0, **({"note": export.note} if export.note else {})}
+    with file_lock(cfg.locks_dir / "ingest.lock", timeout=900) as got:
+        if not got:
+            raise ExportError("a sync is running; try again when it finishes")
+        skip = forgotten_ids(conn)
+        for i, conv in enumerate(export.conversations):
+            if progress and i % 50 == 0:
+                progress(f"importing {fmt.label} chats… {i:,}/{len(export.conversations):,}")
+            sid, sig = mod.conversation_id(conv), mod.conversation_signature(conv)
+            if not sid:
+                counts["empty"] += 1
+                continue
+            if sid in skip or _unchanged(conn, sid, sig, False):
+                counts["unchanged"] += 1
+                continue
+            ps = mod.parse_conversation(conv, projects)
+            if ps is None:
+                counts["empty"] += 1
+                continue
+            if cfg.is_excluded(ps.project_path):
+                counts["excluded"] += 1
+                continue
+            queued = conn.execute("SELECT 1 FROM sessions WHERE id = ? AND analysis_status = 'pending'", (sid,)).fetchone()
+            result = store_parsed(conn, cfg, ps, claude_dir=dst, project_dir=None, transcript_path=archive,
+                                  archive_path=archive, files_sig=sig, agent=fmt.agent, source=fmt.source)
+            if not analyze and not queued:  # a chat already queued for analysis (screen --queue) stays queued
+                conn.execute("UPDATE sessions SET analysis_status = 'skipped', analysis_reason = ? "
+                             "WHERE id = ? AND analysis_status = 'pending'", (fmt.not_analyzed, sid))
+            counts["new" if result == "new" else "updated"] += 1
+            conn.commit()
+        kv_set(conn, fmt.last_import_key, json.dumps({"at": utcnow_iso(), "file": name, **counts}))
+        conn.commit()
+    log.info("%s import from %s: %s", fmt.label, name, counts)
+    return counts
+
+
+def reparse_archived(cfg, conn, skip: set[str] = frozenset()) -> int:
+    """Re-read, from the export each was last imported from (kept in the archive), the chats an older parser stored,
+    after a parser upgrade; each keeps its analysis state. Returns how many chats were re-parsed."""
+    from .ingest import store_parsed
+
+    done = 0
+    for fmt in FORMATS:
+        mod = fmt.module
+        tag = "|" + mod.conversation_signature({}).rsplit("|", 1)[-1]  # every signature ends with the parser version
+        by_dir: dict[Path, set[str]] = {}
+        for sid, sig, archive in conn.execute("SELECT id, files_sig, archive_path FROM sessions WHERE source = ?", (fmt.source,)):
+            if sid not in skip and archive and not (sig or "").endswith(tag):
+                by_dir.setdefault(Path(archive).parent, set()).add(sid)
+        for d, stale in by_dir.items():
+            projects_gz = d / "projects.json.gz"
+            try:
+                projects = claude_export.project_names(gzip.decompress(projects_gz.read_bytes())) \
+                    if fmt is CLAUDE_AI and projects_gz.exists() else {}
+            except OSError:
+                projects = {}
+            for shard in sorted(d.glob("conversations*.json.gz")):
+                try:
+                    data = json.loads(gzip.decompress(shard.read_bytes()))
+                except (OSError, ValueError):
+                    log.warning("could not read archived export %s", shard)
+                    continue
+                data = data.get("conversations") or [] if isinstance(data, dict) else data
+                for conv in data if isinstance(data, list) else []:
+                    sid = mod.conversation_id(conv) if isinstance(conv, dict) else None
+                    if sid not in stale:
+                        continue
+                    stale.discard(sid)
+                    ps = mod.parse_conversation(conv, projects)
+                    if ps is None or cfg.is_excluded(ps.project_path):
+                        continue
+                    store_parsed(conn, cfg, ps, claude_dir=d, project_dir=None, transcript_path=shard, archive_path=shard,
+                                 files_sig=mod.conversation_signature(conv), agent=fmt.agent, source=fmt.source)
+                    conn.commit()
+                    done += 1
+    return done
+
+
+def summary(counts: dict) -> str:
+    parts = [f"{counts['new']} new", f"{counts['updated']} updated", f"{counts['unchanged']} unchanged"]
+    if counts.get("empty"):
+        parts.append(f"{counts['empty']} empty")
+    if counts.get("excluded"):
+        parts.append(f"{counts['excluded']} excluded")
+    note = f" ({counts['note']})" if counts.get("note") else ""
+    return f"{counts['format']} export: {counts['conversations']} chats · " + ", ".join(parts) + note
+
+
+def import_status(conn) -> dict:
+    """Per format: chats imported and analyzed, how screening sorted them, and the last import."""
+    from .db import kv_get
+    from .screen import screen_status
+
+    out = {}
+    for fmt in FORMATS:
+        r = conn.execute("SELECT COUNT(*), SUM(analysis_status = 'done') FROM sessions WHERE source = ?", (fmt.source,)).fetchone()
+        try:
+            last = json.loads(kv_get(conn, fmt.last_import_key) or "null")
+        except ValueError:
+            last = None
+        out[fmt.key] = {"label": fmt.label, "agent": fmt.agent, "sessions": r[0] or 0, "analyzed": r[1] or 0, "last_import": last,
+                        "screen": screen_status(conn, fmt.source)}
+    return out