taskops-cli 0.2.0__py3-none-any.whl

taskops/engine/narrate.py

@@ -0,0 +1,91 @@
+"""Asking Claude to read the day's dossier and write what it means.
+
+The ONE place in taskops that calls a model, and it is deliberately the cheapest possible shape:
+a subprocess running the `claude` binary the developer is already logged into. No SDK, no API
+key, no dependency — the package still installs with nothing, and the narration is paid for by
+the subscription rather than by the token.
+
+**The model only ever sees the DOSSIER.** Not the transcripts, not the diffs — the facts the
+report already assembled from the log. That is what keeps a narration cheap, reproducible enough
+to argue with, and unable to leak a conversation into a committed file.
+
+This module decides how a long dossier is CUT and STITCHED. What one reading costs, and how the
+text reaches the caller while it is still being written, lives in `_stream`.
+"""
+
+from __future__ import annotations
+
+from typing import Callable, Optional
+
+from .._errors import NarrationFailed
+from ._chunks import CHUNK_CHARS, slices
+from ._prompts import CHUNK_PROMPT, PROMPT, STITCH_PROMPT
+from ._stream import TIMEOUT, stream_narration
+
+__all__ = ["narrate", "stream_narration", "PROMPT", "TIMEOUT", "CHUNK_CHARS"]
+
+OnPass = Optional[Callable[[int, int], None]]
+"""Told `(this pass, how many)` as each reading starts. A whole-project dossier takes several
+minutes per pass, and a caller that cannot say which one is running has nothing to show but a
+cursor — which is how this looked like a hang."""
+
+OnText = Optional[Callable[[str], None]]
+"""Told every delta as it arrives. The engine does not print: it hands the fragment to whoever
+asked, and the transport decides whether that is a terminal, a socket, or nothing."""
+
+
+def narrate(dossier: str, *, model: str = "", timeout: float = TIMEOUT,
+            on_pass: OnPass = None, on_text: OnText = None) -> str:
+    """The prose for one dossier. Raises `NarrationFailed` with what to do about it.
+
+    ONE reading when the dossier fits (`_chunks.CHUNK_CHARS`), otherwise one reading per slice
+    and a final pass that stitches them. The long path costs N+1 calls and is taken on purpose:
+    trimming the prompt instead would produce a report that silently forgets the cards that
+    happened to sort last, and nothing on the page would say so.
+
+    Both callbacks are optional and default to nothing, so every existing caller keeps working
+    and a narration nobody is watching costs exactly what it did before.
+    """
+    parts = slices(dossier)
+    total = 1 if len(parts) == 1 else len(parts) + 1
+    ask = _reader(model, timeout, total, on_pass, on_text)
+    if total == 1:
+        return ask(1, PROMPT + dossier)
+    told = [ask(i, f"{CHUNK_PROMPT}(slice {i} of {len(parts)})\n\n{part}")
+            for i, part in enumerate(parts, start=1)]
+    return ask(total, STITCH_PROMPT + "\n\n---\n\n".join(told))
+
+
+def _reader(model: str, timeout: float, total: int,
+            on_pass: OnPass, on_text: OnText) -> Callable[[int, str], str]:
+    """One pass of the narration: announced, streamed to the watcher, returned whole.
+
+    A closure rather than five arguments threaded through every call site — the three ways a
+    dossier is read (single, slice, stitch) differ only in their prompt, and that is the one
+    thing the returned function takes.
+    """
+    def ask(n: int, prompt: str) -> str:
+        if on_pass:
+            on_pass(n, total)
+        written: list[str] = []
+        for delta in stream_narration(prompt, model=model, timeout=timeout):
+            written.append(delta)
+            if on_text:
+                on_text(delta)
+        return _said("".join(written))
+
+    return ask
+
+
+def _said(text: str) -> str:
+    """The prose, never an empty string.
+
+    A CLI that is installed but not logged in can finish cleanly having emitted no text at all,
+    and a report whose narration is a blank section reads as a taskops bug rather than a login
+    problem.
+    """
+    said = text.strip()
+    if not said:
+        raise NarrationFailed("claude answered with nothing — check `claude` runs and is "
+                              "logged in (`claude -p hello`)")
+    return said

taskops/engine/project.py

@@ -0,0 +1,57 @@
+"""The state of the WORK: the board, and the three numbers that summarise it.
+
+Nothing here is stored. That is the property worth protecting — a new column or a
+different count is a rendering change with no migration, and any number on screen
+can be traced back to the rows that produced it.
+
+Who is doing the work lives in `activity`: that reads events and leases, this reads
+tasks and dependencies, and keeping them apart means a change to how liveness is
+judged cannot break how a board is drawn.
+"""
+
+from __future__ import annotations
+
+from .._clock import now
+from .._types import CLOSED_STATUSES, OPEN_STATUSES, STATUSES, WORKING_STATUSES
+from ..contracts import Board, Card, Column
+from ..storage import Store
+
+__all__ = ["board", "counts"]
+
+
+def board(store: Store) -> Board:
+    """Every task, in columns, with the counts that make a card readable.
+
+    The aggregates come from ONE query each (`count_by_task`, `live`) rather than
+    three per task: that difference is what separates a board that is fine at fifty
+    tasks from one that stalls at five hundred.
+    """
+    tasks = store.tasks.all()
+    commits = store.events.count_by_task("commit")
+    live = {lease["task"]: lease for lease in store.leases.live(now())}
+    cards = [Card(task=task, lease=live.get(task["id"]),
+                  blocked_by=len(store.deps.open_blockers_of(task["id"])),
+                  blocks=len(store.deps.dependents_of(task["id"])),
+                  commits=commits.get(task["id"], 0))
+             for task in tasks]
+    columns = [Column(status=status,
+                      cards=[c for c in cards if c["task"]["status"] == status])
+               for status in STATUSES]
+    return Board(repo=str(store.root), columns=columns,
+                 ready=sum(1 for t in tasks if t["status"] == "ready"),
+                 total=len(tasks))
+
+
+def counts(store: Store) -> dict[str, int]:
+    """Ready / working / blocked, and the open-closed split.
+
+    `next` reports these when it has nothing to hand over, so "nothing ready" always
+    arrives with a diagnosis: everything blocked reads differently from everything
+    claimed, and only one of the two is worth waking a human for.
+    """
+    statuses = [task["status"] for task in store.tasks.all()]
+    return {"ready": statuses.count("ready"),
+            "working": sum(1 for s in statuses if s in WORKING_STATUSES),
+            "blocked": sum(1 for s in statuses if s in ("blocked", "backlog")),
+            "open": sum(1 for s in statuses if s in OPEN_STATUSES),
+            "closed": sum(1 for s in statuses if s in CLOSED_STATUSES)}

taskops/engine/replay.py

@@ -0,0 +1,142 @@
+"""Events -> tasks and dependencies. What makes the log the source of truth rather than a diary.
+
+Without this, importing another developer's log gave you their EVENTS and an empty board — which is
+exactly what happened when the usage guide was followed end to end, and what the sync test missed by
+asserting on the log file instead of on the board.
+
+It lives in `engine` because every line is a decision: which events describe state, what to do when
+two machines disagree, and what to ignore. `storage.sync` moves bytes; this decides what they mean.
+
+**Additive and idempotent.** Replaying the same event twice must change nothing, because a `git pull`
+can deliver the same log a second time and `taskops sync` is safe to run in a loop. Nothing here
+deletes: an event that arrives for a task this machine has never seen creates it, and an event that
+contradicts newer local state loses.
+"""
+
+from __future__ import annotations
+
+from .._types import EDITABLE_FIELDS, Status
+from ..contracts import Event, Task
+from ..storage import Store
+
+__all__ = ["apply", "REPLAYED"]
+
+REPLAYED = ("created", "blocked", "status", "done", "edited")
+"""The kinds that describe STATE. Everything else — comments, commits, activity — is history: worth
+keeping and rendering, but it does not tell you what a task IS. Listing them positively rather than
+skipping a blocklist means a new kind is inert here until somebody decides it should not be."""
+
+
+def apply(store: Store, events: list[Event]) -> int:
+    """Materialise state from events. Returns how many actually changed something."""
+    changed = 0
+    for event in events:
+        if event["kind"] == "created":
+            changed += int(_create(store, event))
+        elif event["kind"] == "blocked":
+            changed += int(_block(store, event))
+        elif event["kind"] in ("status", "done"):
+            changed += int(_status(store, event))
+        elif event["kind"] == "edited":
+            changed += int(_edited(store, event))
+    return changed
+
+
+def _edited(store: Store, event: Event) -> bool:
+    """A rewritten title, spec or priority — newer-wins, exactly like `_status`.
+
+    The SAME arbitrator (`event["ts"]` against `task["updated"]`) rather than a per-field
+    clock: one `updated` column is what the row has, and a second timestamp per field would
+    be a schema for a case — two people editing two different fields of one card within the
+    same sync window — that a shared task list barely produces. What it costs is that the
+    older edit loses even when it touched another field; both are in the log, so it is
+    recoverable, which is the trade `_status` already makes.
+    """
+    task = store.tasks.get(event["task"])
+    field = event["body"].get("field")
+    value = event["body"].get("to")
+    if task is None or not isinstance(field, str) or field not in EDITABLE_FIELDS:
+        return False
+    if not isinstance(value, int if field == "priority" else str) or isinstance(value, bool):
+        return False
+    if event["ts"] <= task["updated"] or task[field] == value:  # type: ignore[literal-required]
+        return False
+    store.tasks.set_field(event["task"], field, value, when=event["ts"])
+    return True
+
+
+def _create(store: Store, event: Event) -> bool:
+    """A task this machine has not seen. Existing ones are left ALONE.
+
+    Not upserted: a `created` event is a statement about the past, and re-applying it would undo
+    every local edit made since — a teammate's clone would keep resetting a spec somebody improved.
+    """
+    if store.tasks.get(event["task"]) is not None:
+        return False
+    body = event["body"]
+    store.tasks.insert(Task(
+        id=event["task"], title=str(body.get("title", "(untitled)")),
+        spec=str(body.get("spec", "")), status="backlog",
+        priority=_int(body.get("priority"), 2), parent=_optional(body.get("parent")),
+        labels=_strings(body.get("labels")), files=_strings(body.get("files")),
+        created_by=event["actor"], assignee=str(body.get("assignee", "")),
+        created=event["ts"], updated=event["ts"]))
+    return True
+
+
+def _block(store: Store, event: Event) -> bool:
+    """A dependency edge. Idempotent at the table (`INSERT OR IGNORE`), so this only reports.
+
+    The blocker may not exist here yet — events arrive in file order, and a plan's edges can precede
+    the tasks they point at when two logs merge. The edge is added anyway: `deps` has no foreign key
+    for exactly this reason, and `open_blockers_of` joins on `tasks`, so an edge to an unknown task
+    simply does not block until that task shows up.
+    """
+    blocker = str(event["body"].get("on", ""))
+    if not blocker or blocker == event["task"]:
+        return False
+    store.deps.add(blocker, event["task"])
+    return True
+
+
+def _status(store: Store, event: Event) -> bool:
+    """A status change, applied only if it is NEWER than what this machine has.
+
+    `updated` is the arbitrator, and it is a wall clock from another machine — so a badly skewed
+    clock can win an argument it should have lost. That is the accepted cost of having no server:
+    both edits are in the log either way, so the outcome is always recoverable, and the alternative
+    (a vector clock per task) is a great deal of machinery for a case that is already rare.
+
+    A lease is never replayed. Leases are live local state about a process on one machine, and
+    importing one would mean claiming a task on behalf of an agent that is not running here.
+    """
+    task = store.tasks.get(event["task"])
+    target = event["body"].get("to")
+    if task is None or not isinstance(target, str) or target not in _STATUSES:
+        return False
+    if event["ts"] <= task["updated"]:
+        return False
+    store.tasks.set_status(event["task"], _as_status(target), when=event["ts"])
+    return True
+
+
+_STATUSES = frozenset({"backlog", "ready", "claimed", "in_progress", "blocked", "review",
+                       "done", "cancelled"})
+
+
+def _as_status(value: str) -> Status:
+    return value          # type: ignore[return-value]
+
+
+def _int(value: object, fallback: int) -> int:
+    return value if isinstance(value, int) and not isinstance(value, bool) else fallback
+
+
+def _optional(value: object) -> str | None:
+    return str(value) if isinstance(value, str) and value.strip() else None
+
+
+def _strings(value: object) -> list[str]:
+    if not isinstance(value, list):
+        return []
+    return [str(item) for item in value]        # type: ignore[misc]

taskops/engine/reports.py

@@ -0,0 +1,67 @@
+"""The fingerprint a written daily report carries, and what makes one STALE.
+
+A dossier on disk is a claim about a day, and the day keeps happening after it is written.
+The header line is what lets a reader tell the difference between "this is the day" and
+"this was the day as of event 812" — without it, a report generated at noon and read at
+midnight is indistinguishable from a complete one, which is the failure mode that makes
+generated documents untrustworthy.
+
+`max_seq` and not a timestamp: seq is the log's own local order, so "did anything land
+after this was written" is an integer comparison with no clock skew in it. The `generated`
+field is for the human, and nothing reads it back.
+"""
+
+from __future__ import annotations
+
+import time
+
+from .._types import LOCAL_ONLY_KINDS
+from ..storage import Store
+from .day import MAX_EVENTS, window
+
+__all__ = ["stamp", "stamped_seq", "missing_events", "NO_STAMP"]
+
+_PREFIX = "<!-- taskops:report"
+
+_FIELD = "max_seq="
+
+NO_STAMP = -1
+"""What `stamped_seq` answers for a file nobody generated — a hand-written report, or one
+from before this existed. Staleness is then UNKNOWN, and reported as not stale rather than
+as stale: nagging about a file taskops did not write is noise nobody can act on."""
+
+
+def stamp(label: str, max_seq: int, at: float) -> str:
+    """The header line. Machine-readable, and an HTML comment so it renders as nothing."""
+    return (f"{_PREFIX} date={label} {_FIELD}{max_seq} "
+            f"generated={time.strftime('%Y-%m-%dT%H:%M:%S', time.localtime(at))} -->")
+
+
+def stamped_seq(text: str) -> int:
+    """The `max_seq` a written report was generated at, or `NO_STAMP`.
+
+    Read off the FIRST line only. A stamp further down is not a stamp — it is prose that
+    happens to quote one, and trusting it would let a narration re-date its own report.
+    """
+    first = text.lstrip().splitlines()[0] if text.strip() else ""
+    if not first.startswith(_PREFIX):
+        return NO_STAMP
+    for field in first.split():
+        if field.startswith(_FIELD) and field[len(_FIELD):].isdigit():
+            return int(field[len(_FIELD):])
+    return NO_STAMP
+
+
+def missing_events(store: Store, from_date: str, to_date: str, since_seq: int) -> int:
+    """How many of the window's events landed AFTER the report was generated.
+
+    Scoped to the report's OWN window, because the fingerprint is a global `max_seq`: work on
+    another day would otherwise mark every past report stale forever. Heartbeats are
+    excluded for the same reason the dossier excludes them — a live agent would make every
+    report of today stale within a minute, and the word would stop meaning anything.
+    """
+    if since_seq <= NO_STAMP:
+        return 0
+    start, end = window(from_date)[0], window(to_date)[1]
+    return sum(1 for event in store.events.after_seq(since_seq, limit=MAX_EVENTS)
+               if start <= event["ts"] < end and event["kind"] not in LOCAL_ONLY_KINDS)

taskops/engine/scheduler.py

@@ -0,0 +1,135 @@
+"""Choosing what an agent does next, and claiming it without a race.
+
+Three jobs, in the order they matter:
+
+**Unblock.** `ready` is a stored status, so something has to move a task there when
+its last dependency closes. `unblock` is that one writer — nothing else in the
+package may set `ready` — which is what keeps the column from drifting away from the
+dependency graph.
+
+**Score.** Priority first, then the anti-collision term: a task whose `files`
+overlap what a LIVE agent is editing sorts last. Two agents in one file is a merge
+conflict that both of them will spend context on, and the cheapest place to prevent
+it is here, before either has started.
+
+**Claim.** One INSERT on a primary key, under a transaction that took the write lock
+before it read. See `_leases` for why that ordering is the whole story.
+"""
+
+from __future__ import annotations
+
+from .._clock import LEASE_TTL, now
+from .._ids import slugify
+from .._types import OPEN_STATUSES, WORKING_STATUSES, Status
+from ..contracts import Lease, Task
+from ..storage import Store
+
+__all__ = ["unblock", "ready_tasks", "score", "claim", "branch_for", "sweep_dead"]
+
+_COLLISION_PENALTY = 100
+"""Bigger than any priority band, so a file collision always outranks urgency.
+
+Deliberate: an urgent task handed to a second agent in the same file is not urgent
+work, it is two agents about to undo each other. The penalty defers it, never
+hides it — nothing else is pickable and it comes back to the top.
+"""
+
+
+def sweep_dead(store: Store, *, at: float | None = None) -> list[str]:
+    """Expire silent leases and walk their tasks back to `ready`. Returns those ids.
+
+    The crash-recovery path, and it runs at the START of every claim rather than on a
+    timer: a daemon would be another process to keep alive, and the moment anyone
+    asks for work is exactly when a stuck task matters.
+    """
+    when = now() if at is None else at
+    freed: list[str] = []
+    for task_id in store.leases.sweep(when):
+        task = store.tasks.get(task_id)
+        if task is not None and task["status"] in WORKING_STATUSES:
+            store.tasks.set_status(task_id, "ready", when=when)
+            freed.append(task_id)
+    return freed
+
+
+def unblock(store: Store, *, at: float | None = None) -> list[str]:
+    """Promote every `backlog` task whose dependencies are all closed. Returns ids.
+
+    Also demotes: a `ready` task that gained a dependency goes back to `backlog`, so
+    a mid-flight discovery cannot leave pickable work that is not actually pickable.
+    """
+    when = now() if at is None else at
+    changed: list[str] = []
+    for task in store.tasks.with_status(("backlog", "ready")):
+        blocked = bool(store.deps.open_blockers_of(task["id"]))
+        target: Status = "backlog" if blocked else "ready"
+        if task["status"] != target:
+            store.tasks.set_status(task["id"], target, when=when)
+            if target == "ready":
+                changed.append(task["id"])
+    return changed
+
+
+def ready_tasks(store: Store, *, labels: tuple[str, ...] = (),
+                actor: str = "") -> list[Task]:
+    """Pickable work for this actor, best first. Call `unblock` before this, or it lies.
+
+    Assignment FILTERS, it does not merely sort: a card assigned to somebody else is not offered at
+    all, and the caller's own assigned cards come before the open pool. Without the filter,
+    "assigned" would be a label any agent could ignore, and dispatch could not promise a worker that
+    the card it was launched for is still there when it asks.
+    """
+    pool = [t for t in store.tasks.with_status(("ready",))
+            if not t["assignee"] or t["assignee"] == actor]
+    if labels:
+        wanted = set(labels)
+        pool = [t for t in pool if wanted & set(t["labels"])]
+    busy = _busy_files(store)
+    return sorted(pool, key=lambda t: (0 if t["assignee"] == actor and actor else 1,
+                                      score(t, busy), t["created"]))
+
+
+def _busy_files(store: Store) -> set[str]:
+    """Files that a live lease is plausibly editing right now."""
+    out: set[str] = set()
+    for lease in store.leases.live(now()):
+        task = store.tasks.get(lease["task"])
+        if task is not None:
+            out |= set(task["files"])
+    return out
+
+
+def score(task: Task, busy_files: set[str]) -> int:
+    """Lower is better. Priority, plus a penalty for touching occupied files."""
+    collides = bool(busy_files & set(task["files"]))
+    return task["priority"] + (_COLLISION_PENALTY if collides else 0)
+
+
+def branch_for(task: Task) -> str:
+    """`tk/<id>/<slug>` — the shape the commit guard matches on.
+
+    Composed here rather than left to the agent because the guard's regex and this
+    string are one contract, and an agent inventing `feature/tk-4f2a` would be
+    denied its own commits with no clue why.
+    """
+    return f"tk/{task['id']}/{slugify(task['title'])}"
+
+
+def claim(store: Store, task: Task, *, actor: str, session: str = "",
+          at: float | None = None, ttl: float = LEASE_TTL) -> Lease | None:
+    """Take the lease, or None if somebody got there first.
+
+    None rather than an exception: losing a race is the NORMAL outcome when twenty
+    agents ask for work at once, and the caller's response is to try the next task,
+    not to handle an error.
+    """
+    when = now() if at is None else at
+    lease = Lease(task=task["id"], actor=actor, session=session, branch="",
+                  acquired=when, expires=when + ttl)
+    return lease if store.leases.acquire(lease) else None
+
+
+def open_children(store: Store, task_id: str) -> int:
+    """How many subtasks are still open — the fact the `done` guard needs."""
+    return sum(1 for child in store.tasks.children(task_id)
+               if child["status"] in OPEN_STATUSES)

taskops/engine/transcript.py

@@ -0,0 +1,127 @@
+"""Finding and reading a Claude Code session transcript. Every line here was verified on disk.
+
+**`$CLAUDE_CONFIG_DIR` is honoured, and that is not a nicety.** On the machine this was written on it
+is `~/.claude-jp`, so a hardcoded `~/.claude` found a different installation's projects and reported
+that the workers had left no transcript at all. They had; it was in the other home.
+
+**A transcript is located by DIRECTORY, not by searching for a session id.** Claude Code names the
+directory after the working directory with every separator turned into a dash, so a dispatched worker
+running in `<repo>/.taskops/trees/tk-856f45` gets a directory of its own — one per CARD. That makes the
+lookup a path computation rather than a scan, and it works retroactively on transcripts written before
+taskops knew it would ever read them.
+
+**`gitBranch` verifies what the path suggests.** Every entry carries it, so an entry can be confirmed
+to belong to the card's branch rather than assumed. That is what makes reading the main project's
+directory safe too, where many cards' sessions are mixed together.
+
+The format is NOT documented as stable — the Agent SDK offers `get_session_messages()` for this, which
+is a supported contract — so everything here degrades to "nothing found" rather than raising, and an
+entry shape this version does not recognise is passed through as `other` instead of dropped.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+from typing import Any, Iterator, cast
+
+__all__ = ["home", "slug_for", "directories_for", "read_entries", "ENV_HOME"]
+
+ENV_HOME = "CLAUDE_CONFIG_DIR"
+
+_MAX_TEXT = 4000
+"""Characters kept per entry. A single assistant turn can run to tens of thousands, and a viewer
+needs the shape of the conversation more than the whole of one message."""
+
+
+def home() -> Path:
+    """Claude Code's config directory. `$CLAUDE_CONFIG_DIR` wins, else `~/.claude`."""
+    forced = os.environ.get(ENV_HOME, "").strip()
+    return Path(forced).expanduser() if forced else Path.home() / ".claude"
+
+
+def slug_for(path: Path) -> str:
+    """A working directory -> the transcript directory name Claude Code uses.
+
+    Every separator becomes a dash, including the leading one, so `/Users/b/x` becomes `-Users-b-x`
+    and a worktree at `/Users/b/x/.taskops/trees/tk-1` becomes `-Users-b-x--taskops-trees-tk-1` — the
+    doubled dash is the dot of `.taskops`, which is where the encoding stops being guessable and starts
+    being something to verify. It was.
+    """
+    return str(path.resolve()).replace("/", "-").replace(".", "-")
+
+
+def directories_for(root: Path, tree: Path) -> list[Path]:
+    """Where this card's transcripts could be: its worktree's directory, then the project's.
+
+    The worktree's comes FIRST and is per-card, so it needs no filtering. The project's is shared by
+    every session anybody ran in the repository, which is why callers filter it by branch.
+    """
+    base = home() / "projects"
+    found = [base / slug_for(tree), base / slug_for(root)]
+    return [path for path in found if path.is_dir()]
+
+
+def read_entries(directory: Path, *, branch: str = "",
+                 sessions: tuple[str, ...] = ()) -> Iterator[dict[str, Any]]:
+    """Every raw entry in every transcript in `directory`, oldest file first.
+
+    Two filters, and the second is what rescues the ordinary case. `branch` matches the entry's own
+    `gitBranch`, which is how the shared project directory can be read without mixing in other cards'
+    conversations — but it only works for an agent that made a branch. A person who claimed a card and
+    worked on `main` produces entries the branch filter throws away, so `sessions` names transcripts
+    directly: a file whose stem is a recorded session id belongs to the card by record, and its entries
+    are taken whatever branch they were on.
+
+    Both empty means take everything, which is correct for a per-card worktree directory.
+    """
+    for path in sorted(directory.glob("*.jsonl"), key=_mtime):
+        named = path.stem in sessions
+        for entry in _lines(path):
+            if branch and not named and entry.get("gitBranch") not in (branch, None):
+                continue
+            yield entry
+
+
+def _mtime(path: Path) -> float:
+    try:
+        return path.stat().st_mtime
+    except OSError:
+        return 0.0
+
+
+def _lines(path: Path) -> Iterator[dict[str, Any]]:
+    """Parsed lines, skipping anything unreadable.
+
+    A malformed line is skipped rather than fatal, for the same reason it is in the event log: this
+    file is written by whatever Claude Code version was installed, and one bad line must not make a
+    conversation unreadable.
+    """
+    try:
+        with path.open("r", encoding="utf-8", errors="replace") as handle:
+            for line in handle:
+                parsed = _parse(line)
+                if parsed is not None:
+                    yield parsed
+    except OSError:
+        return
+
+
+def _parse(line: str) -> dict[str, Any] | None:
+    raw = line.strip()
+    if not raw:
+        return None
+    try:
+        found: Any = json.loads(raw)
+    except json.JSONDecodeError:
+        return None
+    return cast("dict[str, Any]", found) if isinstance(found, dict) else None
+
+
+def clip(text: str) -> str:
+    """One entry's text, bounded. Says it was cut rather than trailing off."""
+    flat = text.strip()
+    if len(flat) <= _MAX_TEXT:
+        return flat
+    return flat[:_MAX_TEXT] + f"\n… (+{len(flat) - _MAX_TEXT} more characters)"