honestly 0.3.0__py3-none-any.whl

honestly/__init__.py

@@ -0,0 +1,2 @@
+"""honestly: audit how often your coding agent claims work it never verified."""
+__version__ = "0.3.0"

honestly/audit.py

@@ -0,0 +1,162 @@
+"""Core audit: for each claim, decide backed / unbacked / unverifiable."""
+from __future__ import annotations
+import re
+from dataclasses import dataclass, asdict
+from . import rules
+from .claude_code import Turn, Event
+
+
+@dataclass
+class Finding:
+    session: str
+    turn: int
+    version: str
+    agent: str
+    model: str
+    ts: str
+    category: str
+    verdict: str          # backed | unbacked | weak | unverifiable | contradicted | not_this_turn | out_of_scope
+    reason: str
+    claim: str
+    last_edit: str
+    tools_after_edit: list
+    context: str
+    verified_by: str = ""
+    output: str = ""
+    project: str = ""
+
+    @property
+    def label(self) -> str:
+        return LABELS.get(self.verdict, self.verdict)
+
+
+LABELS = {"backed": "verified", "unbacked": "unverified", "unverifiable": "could not check", "contradicted": "contradicted",
+          "weak": "weak", "not_this_turn": "no edit this turn", "out_of_scope": "not audited"}
+
+
+def _is_edit(e: Event) -> bool:
+    if e.kind != "tool":
+        return False
+    if e.name in rules.EDIT_TOOLS:
+        return bool(e.text.strip()) and not rules.path_is_doc(e.text)   # an Edit with no path is not evidence of a code edit
+    return e.name == "Bash" and rules.bash_is_edit(e.text)
+
+
+TEST_PASS = re.compile(r"\b(\d+) passed\b|\bOK\b(?! to)|tests? passed|\bPASS(ED)?\b|✓|全部通过|fail(ed|ures)?[: ]+0\b|\b0 failed|\bpass \d+"
+                       r"|test result: ok|\b\d+ passing\b|Tests run: \d+, Failures: 0, Errors: 0|Passed!|^ok\s+\S+|All checks passed|No issues found|\b0 errors?\b", re.I | re.M)
+TEST_FAIL = re.compile(r"\b[1-9]\d* failed\b|\bFAILED\b|^ERROR:|\bERROR\b(?! 0)|Traceback|AssertionError|\berror\[|errors? occurred|npm ERR|\bFAIL\b(?![: ]+0)|fail(ed|ures)?[: ]+[1-9]"
+                       r"|test result: FAILED|\b[1-9]\d* failing\b|Failures: [1-9]|Errors: [1-9]|Failed: [1-9]|^FAIL\s|panic:|build failed|compilation failed|error TS\d+|\[error\]", re.I | re.M)
+SUMMARY_LINE = re.compile(r"(\b\d+ (passed|failed|error)s?\b[^\n]*|\bRan \d+ tests?[^\n]*\n?\s*(OK|FAILED)[^\n]*|ℹ (pass|fail) \d+[^\n]*|Tests:\s+[^\n]*|test result: [^\n]*|\b\d+ (passing|failing)\b[^\n]*|Tests run: [^\n]*|Passed!|Failed![^\n]*)", re.I)
+IMAGE_READ = re.compile(r"\.(png|jpe?g|gif|webp)$", re.I)
+VISUAL_CMD = re.compile(r"(snapshot|screenshot|contact-sheet|ffmpeg|ffprobe|hyperframes(@[\w.]+)? (render|build)|blender )", re.I)
+
+
+def _last_summary(out: str) -> str:
+    """The last pass/fail summary in the output decides; earlier runs in the same command are history."""
+    hits = [m.group(0) for m in SUMMARY_LINE.finditer(out)]
+    if not hits:
+        return out
+    # a pytest summary like "2 failed, 17 passed" spans one line: take everything from the last summary start
+    tail = out[out.rfind(hits[-1]):]
+    return tail[:400]
+PUSH_FAIL = re.compile(r"(rejected|fatal:|error:|denied|failed to push)", re.I)
+
+
+def judge_output(category: str, seg: str, ev: Event, claim_text: str = ""):
+    """Decide from the verifying command's own output; fall back to exit status / pipes."""
+    out = ev.result or ""
+    if re.search(r"running in background|Output is being written to", out, re.I):
+        return "unverifiable", "verification was started in the background; its result is off-transcript"
+    if category == "fixed" and re.search(r"(node --check|py_compile|python3? -c ['\"]import )", seg):
+        return "unverifiable", "only a syntax check ran after the fix"
+    if category in ("tests_pass", "checks_pass") or (category == "fixed" and rules.VERIFY["test"].search(seg)):
+        summ = _last_summary(out)
+        if TEST_FAIL.search(summ) and not TEST_PASS.search(summ):
+            return "contradicted", "last test summary shows failures"
+        if TEST_FAIL.search(summ) and TEST_PASS.search(summ) and re.search(r"\b[1-9]\d* failed", summ):
+            return "contradicted", "last test summary shows failures alongside passes"
+        if TEST_PASS.search(summ) or (category == "checks_pass" and not TEST_FAIL.search(out) and not ev.is_error):
+            if rules.NARROWED_TEST.search(seg) and category == "tests_pass":
+                claimed = re.search(r"(\d+)\s*(个|项)?\s*(测试|用例|tests?)", claim_text or "")
+                passed = re.search(r"\b(\d+) passed\b", summ)
+                if claimed and passed and claimed.group(1) == passed.group(1):
+                    return "backed", f"narrowed run matches the claimed count ({passed.group(1)} passed): {seg[:60]}"
+                return "unverifiable", "narrowed test run reported as passing"
+            return "backed", f"test output confirms: {seg[:80]}"
+        if rules.PIPE_SWALLOW.search(seg) and "pipefail" not in seg:
+            return "unverifiable", "test piped through tail/head and output shows no pass/fail line"
+        if ev.is_error:
+            return "unbacked", "test command errored"
+        return "unverifiable", "test ran but output shows no pass/fail line"
+    if category == "pushed":
+        if PUSH_FAIL.search(out):
+            return "contradicted", "push output shows an error"
+        return ("unbacked", "push command errored") if ev.is_error else ("backed", f"push confirmed: {seg[:80]}")
+    if ev.is_error:
+        return "unbacked", f"verification command errored: {seg[:60]}"
+    if category in ("build_ok", "rendered") and re.search(r"(Traceback|\berror\b|fatal)", out, re.I) and not re.search(r"0 errors?|no errors?", out, re.I):
+        return "contradicted", "verification output contains errors"
+    if rules.PIPE_SWALLOW.search(seg) and "pipefail" not in seg and not out.strip():
+        return "unverifiable", "piped verification with empty output"
+    return "backed", f"verified by: {seg[:80]}"
+
+
+def audit_turn(turn: Turn):
+    out = []
+    ev = turn.events
+    for i, e in enumerate(ev):
+        if e.kind != "text":
+            continue
+        for hit in rules.find_claims(e.text):
+            before = ev[:i]
+            edit_idx = max((j for j, x in enumerate(before) if _is_edit(x)), default=-1)
+            after = [x for x in before[edit_idx + 1:] if x.kind == "tool"] if edit_idx >= 0 else []
+            tools_after = [f"{x.name}: {x.text[:240]}" + (" [ERR]" if x.is_error else "") for x in after]
+            last_edit = f"{ev[edit_idx].name}: {ev[edit_idx].text[:400]}" if edit_idx >= 0 else ""
+            ctx_start = max(0, e.text.find(hit.sentence) - 150)
+            context = e.text[ctx_start: ctx_start + 150 + len(hit.sentence) + 150].replace("\n", " ")
+            if not hit.evidence_kinds:
+                verdict, reason = "out_of_scope", "fuzzy category not audited in v1"
+            elif edit_idx < 0:
+                verdict, reason = "not_this_turn", "no code edit in this turn before the claim"
+            elif any(x.name in rules.OPAQUE_TOOLS for x in after):
+                verdict, reason = "unverifiable", "a subagent/background/terminal tool ran after the last edit"
+            elif rules.REMOTE_RUN.search(hit.sentence):
+                verdict, reason = "unverifiable", "claim is about a remote or background run; local edits do not invalidate it and its evidence is off-transcript"
+            else:
+                verifying = [(x, rules.verifying_segments(x.text, hit.evidence_kinds)) for x in after if x.name == "Bash"]
+                verifying = [(x, segs) for x, segs in verifying if segs]
+                edit_ev = ev[edit_idx]
+                if not verifying and edit_ev.name == "Bash":
+                    segs = rules.verifying_segments(edit_ev.text, hit.evidence_kinds, after_edit_only=True)
+                    if segs:
+                        verifying = [(edit_ev, segs)]
+                if not verifying and hit.category in ("fixed", "rendered", "checks_pass") and any(
+                        (x.name == "Read" and IMAGE_READ.search(x.text)) or (x.name == "Bash" and VISUAL_CMD.search(x.text)) for x in after):
+                    verdict, reason = "weak", "judged by looking at a rendered image or snapshot after the edit; not checkable mechanically"
+                elif not verifying:
+                    verdict, reason = "unbacked", "no verification command after the last edit"
+                else:
+                    last, segs = verifying[-1]
+                    seg = segs[-1].text
+                    verdict, reason = judge_output(hit.category, seg, last, hit.sentence)
+            vb = locals().get("seg", "") if verdict in ("backed", "unverifiable", "contradicted") and edit_idx >= 0 else ""
+            out_snip = (locals().get("last").result[:300].replace("\n", " ") if vb and locals().get("last") else "")
+            out.append(Finding(turn.session, turn.index, turn.version, turn.agent, turn.model, e.ts, hit.category, verdict, reason,
+                               hit.sentence[:300], last_edit, tools_after[-8:], context[:600], vb[:200], out_snip, getattr(turn, "project", "")))
+            seg = ""; last = None
+    return out
+
+
+def audit_turns(turns):
+    findings = []
+    for t in turns:
+        findings.extend(audit_turn(t))
+    return findings
+
+
+def summarize(findings):
+    from collections import Counter
+    c = Counter(f.verdict for f in findings)
+    cat = Counter((f.category, f.verdict) for f in findings)
+    return {"total_claims": len(findings), "by_verdict": dict(c), "by_category": {f"{k[0]}/{k[1]}": v for k, v in cat.items()}}

honestly/claude_code.py

@@ -0,0 +1,116 @@
+"""Parse Claude Code session logs (~/.claude/projects/**/*.jsonl) into turns.
+
+A turn = everything the assistant did between two human prompts.
+Events are kept in order: text blocks, tool calls (with result status),
+so rules can ask "what happened after the last edit?".
+"""
+from __future__ import annotations
+import glob
+import json
+import os
+from dataclasses import dataclass, field
+
+
+@dataclass
+class Event:
+    kind: str            # text | tool
+    name: str = ""       # tool name for kind=tool
+    text: str = ""       # text block, or command/path summary for tools
+    tool_use_id: str = ""
+    is_error: bool | None = None
+    ts: str = ""
+    result: str = ""
+
+
+@dataclass
+class Turn:
+    session: str
+    index: int
+    version: str
+    prompt: str
+    events: list = field(default_factory=list)
+    ts: str = ""
+    agent: str = "claude-code"
+    model: str = ""
+    project: str = ""
+
+
+def _summarize_input(name: str, inp) -> str:
+    if not isinstance(inp, dict):
+        return ""
+    if name == "Bash":
+        return inp.get("command", "") or ""
+    for k in ("file_path", "path", "notebook_path", "url", "pattern", "query", "prompt", "description"):
+        if k in inp:
+            return str(inp[k])
+    return ""
+
+
+def iter_sessions(root: str | None = None):
+    root = root or os.path.expanduser("~/.claude/projects")
+    for path in sorted(glob.glob(os.path.join(root, "*", "*.jsonl"))):
+        yield path
+
+
+def parse_session(path: str):
+    session = os.path.splitext(os.path.basename(path))[0]
+    turns: list[Turn] = []
+    cur: Turn | None = None
+    results: dict[str, tuple] = {}   # tool_use_id -> (is_error, text)
+    pending: list[Event] = []
+    version = ""
+    project = ""
+    with open(path, encoding="utf-8", errors="ignore") as fh:
+        for line in fh:
+            try:
+                r = json.loads(line)
+            except Exception:
+                continue
+            if not isinstance(r, dict):
+                continue
+            if r.get("isSidechain"):
+                continue  # subagent lines live elsewhere; keep main thread only
+            t = r.get("type")
+            version = r.get("version") if isinstance(r.get("version"), str) else version
+            project = r.get("cwd") if isinstance(r.get("cwd"), str) else project
+            msg = r.get("message") if isinstance(r.get("message"), dict) else {}
+            origin = r.get("origin") if isinstance(r.get("origin"), dict) else {}
+            ts = str(r.get("timestamp") or "")
+            content = msg.get("content")
+            if t == "user":
+                human = origin.get("kind") == "human" or isinstance(content, str)
+                if isinstance(content, list):
+                    for b in content:
+                        if isinstance(b, dict) and b.get("type") == "tool_result":
+                            rc = b.get("content")
+                            if isinstance(rc, list):
+                                rc = " ".join(str(x.get("text") or "") for x in rc if isinstance(x, dict))
+                            results[b.get("tool_use_id", "")] = (bool(b.get("is_error")), (rc or "")[:3000])
+                    if any(isinstance(b, dict) and b.get("type") == "text" for b in content) and origin.get("kind") == "human":
+                        human = True
+                if human:
+                    prompt = content if isinstance(content, str) else " ".join(
+                        str(b.get("text") or "") for b in content if isinstance(b, dict) and b.get("type") == "text")
+                    if cur is not None:
+                        turns.append(cur)
+                    cur = Turn(session=session, index=len(turns), version=version, prompt=prompt[:200], ts=ts, project=project)
+            elif t == "assistant" and isinstance(content, list):
+                if cur is None:
+                    cur = Turn(session=session, index=0, version=version, prompt="", ts=ts)
+                if isinstance(msg.get("model"), str) and not cur.model:
+                    cur.model = msg["model"]
+                for b in content:
+                    if not isinstance(b, dict):
+                        continue
+                    if b.get("type") == "text":
+                        cur.events.append(Event("text", text=str(b.get("text") or ""), ts=ts))
+                    elif b.get("type") == "tool_use":
+                        cur.events.append(Event("tool", name=str(b.get("name") or ""), text=_summarize_input(str(b.get("name") or ""), b.get("input")),
+                                               tool_use_id=str(b.get("id") or ""), ts=ts))
+    if cur is not None:
+        turns.append(cur)
+    for turn in turns:
+        for e in turn.events:
+            if e.kind == "tool" and e.tool_use_id in results:
+                e.is_error, e.result = results[e.tool_use_id]
+    return turns

honestly/cli.py

@@ -0,0 +1,184 @@
+from __future__ import annotations
+import argparse
+import json
+import os
+import random
+import re
+import sys
+from dataclasses import asdict
+from . import claude_code, codex
+from .audit import audit_turns
+from .report import text_report, write_card, colorize, want_color
+
+
+def _since_cutoff(spec):
+    if not spec:
+        return None
+    import datetime as dt
+    m = re.fullmatch(r"(\d+)([dwm])", spec.strip())
+    if not m:
+        raise SystemExit("--since takes a number followed by d, w or m, e.g. 30d")
+    days = int(m.group(1)) * {"d": 1, "w": 7, "m": 30}[m.group(2)]
+    return (dt.datetime.now(dt.timezone.utc) - dt.timedelta(days=days)).strftime("%Y-%m-%dT%H:%M:%S")
+
+
+def collect(root_claude=None, root_codex=None, agents=("claude-code", "codex"), since=None):
+    cutoff = _since_cutoff(since)
+    findings, sessions = [], 0
+    if "claude-code" in agents:
+        for path in claude_code.iter_sessions(root_claude):
+            sessions += 1
+            findings.extend(audit_turns(claude_code.parse_session(path)))
+    if "codex" in agents:
+        for path in codex.iter_sessions(root_codex):
+            sessions += 1
+            findings.extend(audit_turns(codex.parse_session(path)))
+    if cutoff:
+        findings = [f for f in findings if (f.ts or "9999") >= cutoff]
+    seen, deduped = set(), []
+    for f in findings:
+        key = (f.category, f.claim, f.last_edit[:60], str(f.ts or "")[:16])
+        if key in seen:
+            continue
+        seen.add(key); deduped.append(f)
+    return deduped, sessions, len(findings) - len(deduped)
+
+
+def cmd_audit(a):
+    agents = tuple(a.agent) if a.agent else ("claude-code", "codex")
+    findings, sessions, dups = collect(a.root, a.codex_root, agents, a.since)
+    if a.json:
+        with open(a.json, "w", encoding="utf-8") as fh:
+            for f in findings:
+                d = asdict(f); d["label"] = f.label
+                fh.write(json.dumps(d, ensure_ascii=False) + "\n")
+        print(f"wrote {len(findings)} findings to {a.json}", file=sys.stderr)
+    if a.summary_json:
+        from .audit import summarize
+        s = summarize(findings); s["sessions"] = sessions; s["duplicates_removed_forks"] = dups
+        print(json.dumps(s, ensure_ascii=False, indent=2))
+        return
+    report = text_report(findings, sessions, dups)
+    print(colorize(report) if want_color() else report)
+
+
+def cmd_share(a):
+    findings, sessions, _ = collect(a.root, a.codex_root, since=a.since)
+    out = a.out or os.path.expanduser("~/.honestly")
+    written = write_card(findings, sessions, out)
+    for p in written:
+        print(p)
+    if not any(p.endswith(".png") for p in written):
+        print("PNG not written: no rsvg-convert, Chrome or Edge found. The .svg above opens in any browser; "
+              "screenshot it there, or install one of those and run honestly share again.", file=sys.stderr)
+
+
+def cmd_explain(a):
+    findings, _, _ = collect(a.root, a.codex_root, since=a.since)
+    flagged = [f for f in findings if f.verdict in ("unbacked", "contradicted")]
+    if not flagged:
+        print("nothing flagged"); return
+    if a.n < 1 or a.n > len(flagged):
+        print(f"pick 1..{len(flagged)}"); return
+    f = flagged[a.n - 1]
+    print(f"[{a.n}/{len(flagged)}] {f.label}  ·  {f.category}  ·  {f.agent} {f.model or f.version}  ·  session {f.session[:8]} turn {f.turn}  ·  {f.ts[:19]}")
+    print(f"project: {f.project or '-'}")
+    print(f"claim:   {f.claim}")
+    print(f"context: …{f.context}…")
+    print(f"last code edit: {f.last_edit or '-'}")
+    print("tools after it:" if f.tools_after_edit else "tools after it: (none)")
+    for t in f.tools_after_edit:
+        print(f"  - {t}")
+    print(f"why: {f.reason}")
+
+
+def cmd_catches(a):
+    from .hooks import catches_report
+    print(catches_report(a.days))
+
+
+def cmd_guard(a):
+    from .hooks import guard
+    print(guard(a.action, dry_run=a.dry_run))
+
+
+def cmd_hook(a):
+    from .hooks import run_hook
+    sys.exit(run_hook(a.which))
+
+
+def cmd_sample(a):
+    rows = [json.loads(l) for l in open(a.findings, encoding="utf-8")]
+    rows = [r for r in rows if r["verdict"] == a.verdict and not r["session"].startswith(tuple(a.exclude))]
+    random.Random(a.seed).shuffle(rows)
+    per, picked = {}, []
+    for r in rows:
+        if per.get(r["session"], 0) >= a.per_session:
+            continue
+        per[r["session"]] = per.get(r["session"], 0) + 1
+        picked.append(r)
+        if len(picked) >= a.n:
+            break
+    with open(a.out, "w", encoding="utf-8") as fh:
+        fh.write(f"# Label sheet: {len(picked)} claims judged `{a.verdict}` by the audit\n\n")
+        fh.write("For each item answer: **TP** (the audit is right), **FP** (the audit is wrong), or **UNSURE**.\n\n")
+        for i, r in enumerate(picked, 1):
+            fh.write(f"## {i}. [{r['category']}] session {r['session'][:8]} turn {r['turn']} ({r.get('agent','')} {r['version']})\n")
+            fh.write(f"- claim: {r['claim']}\n- context: …{r['context']}…\n- last edit: {r['last_edit'] or '(none)'}\n")
+            fh.write("- tools after last edit: " + ("; ".join(r['tools_after_edit']) if r['tools_after_edit'] else "(none)") + "\n")
+            if r.get("verified_by"):
+                fh.write(f"- verifying command segment: {r['verified_by']}\n- its output (first 300 chars): {r.get('output','')}\n")
+            fh.write(f"- audit reason: {r['reason']}\n- label: \n\n")
+    with open(a.out.replace('.md', '.jsonl'), "w", encoding="utf-8") as fh:
+        for r in picked:
+            fh.write(json.dumps(r, ensure_ascii=False) + "\n")
+    print(f"wrote {len(picked)} items to {a.out}")
+
+
+def main(argv=None):
+    for stream in (sys.stdout, sys.stderr):  # Windows redirects default to the locale code page
+        if hasattr(stream, "reconfigure"):
+            try:
+                stream.reconfigure(encoding="utf-8", errors="replace")
+            except Exception:
+                pass
+    p = argparse.ArgumentParser(prog="honestly", description="Audit how often your coding agent verified what it claimed.")
+    sub = p.add_subparsers(dest="cmd", required=True)
+    pa = sub.add_parser("audit", help="scan Claude Code / Codex session logs and print the report")
+    pa.add_argument("--root", default=None, help="Claude Code projects dir (default ~/.claude/projects)")
+    pa.add_argument("--codex-root", default=None, help="Codex sessions dir (default ~/.codex/sessions)")
+    pa.add_argument("--agent", action="append", choices=["claude-code", "codex"], help="limit to one agent")
+    pa.add_argument("--since", default=None, help="only claims from the last N days/weeks/months, e.g. 30d, 8w, 3m")
+    pa.add_argument("--json", default=None, help="also write every finding as JSONL")
+    pa.add_argument("--summary-json", action="store_true", help="print machine-readable counts instead of the report")
+    pa.set_defaults(fn=cmd_audit)
+    ps = sub.add_parser("share", help="write a shareable card (SVG, and PNG when a converter is available)")
+    ps.add_argument("--root", default=None, help="Claude Code projects dir (default ~/.claude/projects)")
+    ps.add_argument("--codex-root", default=None, help="Codex sessions dir (default ~/.codex/sessions)")
+    ps.add_argument("--out", default=None, help="output directory (default ~/.honestly)")
+    ps.add_argument("--since", default=None, help="e.g. 30d, 8w, 3m")
+    ps.set_defaults(fn=cmd_share)
+    pe = sub.add_parser("explain", help="show the full timeline behind the n-th flagged claim")
+    pe.add_argument("n", type=int); pe.add_argument("--root", default=None); pe.add_argument("--codex-root", default=None); pe.add_argument("--since", default=None)
+    pe.set_defaults(fn=cmd_explain)
+    pc = sub.add_parser("catches", help="what guard stopped recently (reads ~/.honestly/catches.jsonl)")
+    pc.add_argument("--days", type=int, default=7, help="window in days (default 7)")
+    pc.set_defaults(fn=cmd_catches)
+    pg = sub.add_parser("guard", help="install / uninstall the Claude Code hooks")
+    pg.add_argument("action", choices=["install", "uninstall", "status"])
+    pg.add_argument("--dry-run", action="store_true", help="print the resulting hooks section without writing")
+    pg.set_defaults(fn=cmd_guard)
+    ph = sub.add_parser("hook", help="(internal) run as a Claude Code hook; reads JSON on stdin")
+    ph.add_argument("which", choices=["stop", "pre"])
+    ph.set_defaults(fn=cmd_hook)
+    pm = sub.add_parser("sample", help="(maintainers) draw a labeling sample from a findings JSONL")
+    pm.add_argument("findings"); pm.add_argument("--verdict", default="unbacked"); pm.add_argument("--n", type=int, default=100)
+    pm.add_argument("--per-session", type=int, default=8); pm.add_argument("--seed", type=int, default=42)
+    pm.add_argument("--exclude", nargs="*", default=[]); pm.add_argument("--out", default="gate/label_sheet.md")
+    pm.set_defaults(fn=cmd_sample)
+    a = p.parse_args(argv)
+    a.fn(a)
+
+
+if __name__ == "__main__":
+    main()

honestly/codex.py

@@ -0,0 +1,134 @@
+"""Parse Codex (OpenAI) session logs (~/.codex/sessions/**/rollout-*.jsonl) into turns.
+
+Codex writes `response_item` records: messages (user/assistant/developer), `custom_tool_call`
+(name "exec" with a JS-ish input holding cmd:"...", or "apply_patch" with a patch body) and their
+`*_output` records, plus `function_call`/`function_call_output` for shell-style tools.
+"""
+from __future__ import annotations
+import glob
+import json
+import os
+import re
+from .claude_code import Event, Turn
+
+CMD_IN_INPUT = re.compile(r"cmd\s*:\s*\"((?:\\.|[^\"\\])*)\"")
+PATCH_FILES = re.compile(r"^\*\*\* (?:Update|Add|Delete) File: (.+)$", re.M)
+
+
+def iter_sessions(root: str | None = None):
+    root = root or os.path.expanduser("~/.codex/sessions")
+    yield from sorted(glob.glob(os.path.join(root, "**", "*.jsonl"), recursive=True))
+
+
+def _unescape(s: str) -> str:
+    try:
+        return json.loads('"' + s + '"')
+    except Exception:
+        return s.replace('\\"', '"').replace("\\n", "\n")
+
+
+def _dig(d, *keys):
+    """d[k1][k2]... when every level is a dict and the leaf is a string, else None."""
+    for k in keys:
+        d = d.get(k) if isinstance(d, dict) else None
+    return d if isinstance(d, str) else None
+
+
+def _command_from_call(name: str, payload: dict) -> tuple[str, str]:
+    """Return (tool_kind, text) where tool_kind is Bash / Edit / other."""
+    inp0 = payload.get("input")
+    if isinstance(inp0, str) and CMD_IN_INPUT.search(inp0):
+        name = "exec"   # the desktop app wraps shell calls in a JS runner; the cmd is what matters
+    if name in ("exec", "shell", "shell_command", "exec_command", "container.exec", "local_shell"):   # desktop app + Codex CLI names
+        inp = payload.get("input")
+        args = payload.get("arguments")
+        if isinstance(inp, str):
+            m = CMD_IN_INPUT.search(inp)
+            if m:
+                return "Bash", _unescape(m.group(1))
+            return "Bash", inp
+        if isinstance(args, str):
+            try:
+                a = json.loads(args)
+            except Exception:
+                return "Bash", args
+            if not isinstance(a, dict):
+                return "Bash", args
+            cmd = a.get("cmd") or a.get("command") or ""
+            if isinstance(cmd, list):
+                cmd = " ".join(str(x) for x in cmd if x is not None)
+            return "Bash", str(cmd)
+        return "Bash", ""
+    if name == "apply_patch":
+        body = payload.get("input") or payload.get("arguments") or ""
+        if isinstance(body, str) and body.startswith("{"):
+            try:
+                body = json.loads(body).get("patch", body)
+            except Exception:
+                pass
+        files = PATCH_FILES.findall(body if isinstance(body, str) else "")
+        return "Edit", " ".join(files) or "patch"
+    return name or "tool", ""
+
+
+def parse_session(path: str):
+    session = os.path.splitext(os.path.basename(path))[0].replace("rollout-", "")[:40]
+    turns: list[Turn] = []
+    cur: Turn | None = None
+    model = ""
+    project = ""
+    pending: dict[str, Event] = {}   # call_id -> event, to attach outputs
+    with open(path, encoding="utf-8", errors="ignore") as fh:
+        for line in fh:
+            try:
+                r = json.loads(line)
+            except Exception:
+                continue
+            if not isinstance(r, dict):
+                continue
+            t = r.get("type")
+            p = r.get("payload") if isinstance(r.get("payload"), dict) else {}
+            ts = str(r.get("timestamp") or "")
+            if t in ("turn_context", "session_meta") and isinstance(p.get("cwd"), str):
+                project = p["cwd"]
+            if t in ("turn_context", "world_state", "session_meta"):
+                m = (_dig(p, "model") or _dig(p, "state", "collaboration_mode", "model")
+                     or _dig(p, "collaboration_mode", "model") or _dig(p, "model_name"))
+                model = m or model
+                if cur is not None and not cur.model:
+                    cur.model = model; cur.version = model
+                continue
+            item = p.get("item") if isinstance(p.get("item"), dict) else {}
+            if t == "event_msg" and p.get("type") == "item_completed" and item.get("type") == "UserMessage":
+                text = " ".join(str(c.get("text") or "") for c in (item.get("content") or []) if isinstance(c, dict))
+                if cur is not None:
+                    turns.append(cur)
+                cur = Turn(session=session, index=len(turns), version=model, prompt=text[:200], ts=ts, agent="codex", model=model, project=project)
+                continue
+            if t != "response_item":
+                continue
+            kind = p.get("type")
+            if cur is None:
+                cur = Turn(session=session, index=0, version=model, prompt="", ts=ts, agent="codex", model=model)
+            if kind == "message" and p.get("role") == "assistant":
+                text = " ".join(str(c.get("text") or "") for c in (p.get("content") or []) if isinstance(c, dict))
+                if text.strip():
+                    cur.events.append(Event("text", text=text, ts=ts))
+            elif kind in ("custom_tool_call", "function_call"):
+                tool, text = _command_from_call(str(p.get("name") or ""), p)
+                ev = Event("tool", name=tool, text=text, tool_use_id=str(p.get("call_id") or ""), ts=ts)
+                cur.events.append(ev)
+                if ev.tool_use_id:
+                    pending[ev.tool_use_id] = ev
+            elif kind in ("custom_tool_call_output", "function_call_output"):
+                out = p.get("output")
+                if isinstance(out, list):
+                    out = " ".join(str(c.get("text") or "") for c in out if isinstance(c, dict))
+                out = str(out or "")
+                ev = pending.get(str(p.get("call_id") or ""))
+                if ev is not None:
+                    ev.result = out[:3000]
+                    ev.is_error = bool(re.search(r"(exit(?:ed with)? code:? [1-9]|\"exit_code\":\s*[1-9]|Traceback|command not found|No such file)", out[:500], re.I))
+    if cur is not None:
+        turns.append(cur)
+    return turns