chsum 2.2.1__tar.gz → 3.0.2__tar.gz

{chsum-2.2.1 → chsum-3.0.2}/.gitignore

@@ -1,5 +1,9 @@
 __pycache__/
 *.pyc
+
+# Build artefacts: `python -m build` writes them, the release publishes from CI.
+dist/
+*.egg-info/
 .venv/
 .DS_Store
 .devharness/*

chsum-3.0.2/CONTRIBUTING.md

@@ -0,0 +1,91 @@
+# Contributing
+
+`README.md` is the user-facing doc. This file is the mechanics.
+
+## Setup
+
+```sh
+pipx install --editable .
+```
+
+The `chsum` package in this checkout is then what runs, from anywhere. Python
+≥3.10, stdlib only — `dependencies` in `pyproject.toml` stays empty, which is
+what lets chsum run against any corpus with no venv. `claude-history` is a
+runtime requirement but a separate binary; only the session listing works
+without it.
+
+## Layout
+
+```
+chsum.py              launcher: a package directory cannot be run by path, and
+                      the plugin's hooks and CI both need one that can
+chsum/
+  __init__.py         what `import chsum` gives the hooks; `main`, `entrypoint`
+  __main__.py         `python3 -m chsum`
+  core.py             the commands, the readers, the renderers
+  checkpoints.py      the git layer: one commit per call that changed the tree
+  sources/
+    __init__.py       the registry, and the translated-transcript cache
+    claude.py         `~/.claude/projects`, read where it lies
+    codex.py          `~/.codex/sessions`, translated to the common shape
+```
+
+`checkpoints.py` holds the git plumbing and imports nothing from `core` — the
+dependency runs one way, and `core` installs its tracer with `set_tracer` rather
+than the layer reaching back for it. The views that render checkpoints and the
+`checkpoints` command stay in `core`.
+
+Adding a tool means one file under `sources/` and one `register(...)` call:
+where its sessions sit, which directory each ran in, and a translation to the
+record shape `core` reads. Nothing in `core` names a format.
+
+A translated file is cached against its original's size and mtime **and** the
+bytes of the translator module. Editing `codex.py` therefore rebuilds every
+Codex translation on the next run; without that, a corrected rule would serve
+its old output forever, since a finished session is never written to again.
+
+## Checking a change
+
+```sh
+python3 -m unittest discover -s tests -t tests
+```
+
+Stdlib `unittest`, no test dependency, ~10s. Each git test builds a throwaway
+repository under `tempfile` and binds every call with `git -C <repo>`, so a test
+that resolves a path wrongly fails against that repository rather than reaching
+the checkout it runs from. `publish.yml` runs the suite before it builds.
+
+The suite covers what fails outside chsum — a moved `HEAD`, a disturbed index, a
+lost history — and the translation and view rules that were measured rather than
+assumed. It does not cover the renderers' prose. Compile as well, then run the
+commands the change could reach:
+
+```sh
+python3 -m compileall -q chsum chsum.py hooks
+chsum                      # listing
+chsum digest --last        # digest, incl. a subagent one if the session had any
+chsum --since 7d -n 0     # listing over a window
+chsum --all --source codex # another tool's sessions, translated on the way in
+chsum find "…" --all       # search, which runs one pass per corpus and merges
+chsum mark --list          # from inside Claude Code — marks need a live session
+```
+
+Read the output rather than checking it exits 0. Every line lands in a future
+context window, so a wrong or unmarked-truncated one is the failure mode.
+
+## Releasing
+
+The version lives in `pyproject.toml`, and `publish.yml` refuses a tag that
+disagrees with it.
+
+```sh
+# bump it, commit, then
+git tag v1.0.4 && git push origin v1.0.4
+```
+
+The tag publishes to PyPI via trusted publishing (no stored token) and asks
+[InDate/indate-tools](https://github.com/InDate/indate-tools) to repin. The
+marketplace opens a PR: publishing and pushing an update to installed users are
+separate decisions.
+
+PyPI version numbers cannot be reused. A bad release is fixed by the next one.

chsum-3.0.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 InDate
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

chsum-2.2.1/README.md → chsum-3.0.2/PKG-INFO

@@ -1,6 +1,18 @@
+Metadata-Version: 2.5
+Name: chsum
+Version: 3.0.2
+Summary: Work logs and reload-ready context from coding-agent conversations. Deterministic: no model, nothing invented.
+Author: InDate
+License-Expression: MIT
+License-File: LICENSE
+Keywords: claude,claude-code,context,transcripts,work-log
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
 # chsum
 
-Work logs and reload-ready context from your Claude Code conversations.
+Work logs and reload-ready context from your coding-agent conversations —
+Claude Code and Codex CLI, listed and digested side by side.
 
 **Digests and listings are never generated by a model.** Every line of that output
 is either copied verbatim from a transcript or computed from it, so nothing can be
@@ -32,6 +44,9 @@ from.
   ends included. → [`chsum`](#chsum-1)
 - **You remember what was said, not when.** — `chsum find "…"` searches the text of
   every conversation; `--notes` searches what you noted. → [`chsum find`](#chsum-find)
+- **chsum printed `01a0acf9:31` and you want that record.** — `chsum where
+  01a0acf9:31` prints the `sed` command for it, resolved to a real path. Pipe it
+  to `sh` to run it. → [`chsum where`](#chsum-where)
 - **You need the exact command Claude ran, or its full output.** — `chsum digest
   <ref> --commands` lists every Bash call in order; `--call <id>` prints one whole.
   → [`chsum digest`](#the-row-views)
@@ -49,6 +64,8 @@ from.
 - **`recap`'s files-touched section misses edits made outside Edit/Write.** — opt in
   to git checkpoints; the plugin's hooks run `chsum hook`. → [`chsum hook`](#chsum-hook)
 
+Coming from 2.x: [what changed](#upgrading-to-30).
+
 The commands, one section each:
 
 | command | what it is for |
@@ -56,6 +73,8 @@ The commands, one section each:
 | [`chsum`](#chsum-1) | list this project's sessions, newest activity first |
 | [`chsum recap`](#chsum-recap) | what happened over a window of turns, with a model-written timeline |
 | [`chsum digest`](#chsum-digest) | one conversation, verbatim and computed, plus row-level views |
+| [`chsum where`](#chsum-where) | a locator to the `sed` command that prints that row |
+| [`chsum checkpoints`](#chsum-hook) | the git checkpoint chains this repo holds, and dropping old ones |
 | [`chsum find`](#chsum-find) | locate a conversation or a note by what it said |
 | [`chsum note`](#chsum-note) | mark the moment that mattered |
 | [`chsum name`](#chsum-name) | rename a session to what it actually was |
@@ -356,16 +375,17 @@ same from here.
 
 One conversation, verbatim and computed: your prompts in order, each with the
 row it sits on; the files changed and the commands that did something; the last
-exchange; and the `sed` line that opens any row. A bare run prints the digest of
-the session you are in; naming a session (a ref, `--last`, `--file`) writes it to
-a file and prints the path, and `--stdout` prints it instead.
+exchange; and the `sed` line that opens any row. Every run writes a file and prints its
+path — a bare one for the session you are in, a named one (a ref, `--last`,
+`--file`) for that conversation — and `--stdout` prints the document instead.
+One rule for every view below, not the digest alone.
 
 https://github.com/user-attachments/assets/93f3cdac-cf82-403a-8333-5c8e42159fd7
 
 ```sh
-chsum digest                                   # this session, printed
-chsum digest <ch_ref>                          # write a digest file
-chsum digest <ch_ref> --stdout                 # print it instead
+chsum digest                                   # this session, written
+chsum digest <ch_ref>                          # that conversation
+chsum digest <ch_ref> --stdout                 # print it instead of writing
 chsum digest --file path/to/session.jsonl      # address by file
 chsum digest <ch_ref>/<agent-id>               # one subagent's own digest
 chsum digest --list                            # this project's digest files
@@ -426,24 +446,55 @@ rest:
 
 ### The row views
 
-Four flags print rather than writing a file: they are lookups reached from a
-hint inside a digest, not artifacts to keep.
+Each writes a file of its own, `<uuid>-<view>.md` beside the digest, and prints
+the path; `--stdout` prints the document instead. The same rule the digest
+itself follows. `chsum digest --list` names the view beside the session each
+file belongs to.
 
 ```sh
-chsum digest <ch_ref> --messages               # every message in order, unfiltered
+chsum digest <ch_ref> --messages               # every message whole, each call a line between them
 chsum digest <ch_ref> --tools                  # every tool call in order
 chsum digest <ch_ref> --commands               # every Bash call in order
 chsum digest <ch_ref> --call <id>              # one tool call whole, with its output
 chsum digest <ch_ref> --agents                 # every subagent and what it reported back
 chsum digest <ch_ref>/<agent-id> --commands    # narrowed to that sidecar
+chsum digest <ch_ref>/<agent-id> --messages    # everything that agent said, and every call it made
+chsum digest <ch_ref> --messages --stdout      # print it rather than write it
+chsum digest <ch_ref> --messages > out.md      # or your own path
+```
+
+All three print in timestamp order across the transcript and its sidecars, with
+nothing filtered, deduplicated or collapsed. `--tools` and `--commands` print one
+line per row — the call id, a `<session>:<line>` locator, local time, the tool
+name and the first line of the call. A row runs long and lets the terminal
+soft-wrap it rather than folding at a space: a command broken across lines can
+no longer be copied in one selection.
+
+`--messages` prints its message rows **whole**, on every ref. Messages are
+prose, and a conversation clipped to a line each is the one thing this view
+cannot be used for. There is no flag or size limit behind that: the turn numbers
+below already select the part of a conversation you want, and a second way to
+ask for less would only be a worse one.
+
+Between them it prints every call, each the same single clipped line `--tools`
+gives it. A turn headed `2 tool calls · 8 commands` states how many ran and
+names none of them, which leaves the work between two replies unreadable; the
+calls sitting in the conversation's own order name each one. They stay clipped
+inside a turn window too, so a read of the conversation never runs through a
+heredoc's body — `--call <id>` opens one whole.
+
+Every view is broken by turn, each headed with the line the digest already
+prints under that prompt:
+
+```
+*turn 8 · 16m · 6 tool calls · 5 files · 108 commands · 12 replies*
 ```
 
-`--messages`, `--tools` and `--commands` each print one line per row — the id
-where there is one, a `<session>:<line>` locator, local time, the role or tool
-name, and the first line of the text — in timestamp order across the transcript
-and its sidecars, with nothing filtered, deduplicated or collapsed. `--call <id>`
-prints one tool call and its captured output whole, which is where the text a row
-clipped actually lives.
+The head names the turn a row sits in, not the row that opens one, so a view
+that keeps no messages — `--tools`, `--commands` — still shows its boundaries,
+and a window opening mid-conversation says which turn it landed in. `--call <id>`
+prints one tool call and its captured output whole, which is where the text a
+clipped call row actually lives.
 
 `--agents` lists every subagent the session ran and each report it sent back,
 numbered where an agent returned more than once. A report is the agent's own
@@ -451,15 +502,22 @@ document and runs to thousands of characters, so it is clipped with the cut
 marked; the row it came from names where the whole text is.
 
 One or two numbers beside `--messages`, `--tools` or `--commands` narrow the view
-to a window of your turns and print those rows whole, so a stretch of
-conversation reads without leaving chsum:
+to a window of your turns. `--tools` and `--commands` print those rows whole, so
+a stretch of conversation reads without leaving chsum; `--messages` keeps the
+shape it has unwindowed, messages whole and calls a line each:
 
 ```sh
 chsum digest --last --messages -1              # your last turn, and everything after it
 chsum digest <ch_ref> --messages 10 11         # your 10th and 11th turns
 chsum digest <ch_ref> --tools -5 -1            # what Claude called across your last five
+chsum digest <ch_ref>/<agent-id> --tools 2 -1  # an agent's own turns, not yours
 ```
 
+On an agent ref the turns counted are the sidecar's own: the task it was handed
+is turn 1, and a prompt sent to it while it worked opens the next. Most agents
+have exactly one turn, so the numbers earn their keep on a `/btw` fork that was
+talked to repeatedly.
+
 Inside a window the rows a view steps over are listed rather than skipped
 silently, one line each with its own locator, so a jump from `2500` to `2513`
 reads as:
@@ -476,20 +534,135 @@ A tool call carries its tool and the size of what it returned, and its result ro
 folds into it. A `thinking` row is named and nothing more — the JSONL keeps its
 signature and drops the text. Harness bookkeeping rows are left out.
 
-A `## Sources` block at the top expands every locator to a full path and gives a
-worked `sed` line, so a row reaches its raw record without chsum:
+A `## Sources` block at the top expands every locator to a path, `~`-relative so
+it fits the width and still pastes into a shell. Where the view clipped its rows
+it also gives a worked `sed` line, so a row reaches its raw record without chsum:
 
 ```
 ## Sources
 
-- `f1b9bbc6` — `~/.claude/projects/…/f1b9bbc6-….jsonl`
-- `f1b9bbc6/a190d601` — `~/.claude/projects/…/f1b9bbc6-…/subagents/agent-a190d601….jsonl`
+- `f1b9bbc6`  `~/.claude/projects/…/f1b9bbc6-….jsonl`
+- `f1b9bbc6/a190d601`  `~/.claude/projects/…/subagents/agent-a190d601….jsonl`
+
+A row's whole text — `sed` the line its locator names:
 
-Open a record: `sed -n '18p' ~/.claude/projects/…/f1b9bbc6-….jsonl`
+- `sed -n '18p' ~/.claude/projects/…/f1b9bbc6-….jsonl | jq -r '…'`
 
 - `01CPKjYaSD`  `f1b9bbc6:26`  11:30:28  Bash  `ls && wc -l chsum.py`
 ```
 
+The `sed` line is an escape hatch for text a row clipped, so a row printed
+whole — a message under `--messages`, any row inside a turn window — leaves it
+out. One source prints as the path alone: there is nothing for a locator to pick
+out, and the bare path is a line the terminal leaves intact to copy.
+
+## Upgrading to 3.0
+
+Two changes break a script written against 2.x.
+
+**Every view writes a file and prints its path.** In 2.x a bare `chsum digest`
+and the row views printed their document to stdout; now they write it and stdout
+carries the path alone, so `chsum digest <ref> --messages > out.md` puts a path
+in that file rather than the messages. `--stdout` restores the old behaviour:
+
+```sh
+chsum digest <ref> --messages --stdout > out.md    # the document, as 2.x gave it
+code $(chsum digest <ref> --messages)              # what the path is for
+```
+
+**Checkpoints are kept until dropped.** 2.x committed each turn and reset it
+away, leaving it in `HEAD`'s reflog to expire in about thirty days. 3.0 chains
+them under `refs/chsum/<session>`, which git keeps — they survive a `gc`, the
+reflog expiring, and the removal of the worktree they were written in, and they
+no longer clear themselves. `chsum checkpoints --prune 30d` is the retention
+that was previously accidental, and `chsum checkpoints --migrate` rebuilds
+checkpoints written by 2.x so they gain the same durability. Both are described
+under [`chsum hook`](#chsum-hook).
+
+## Which tools' sessions it reads
+
+Claude Code sessions, from `~/.claude/projects`, and Codex CLI sessions, from
+`~/.codex/sessions`. Both appear in every listing, digest and search. A `source`
+column appears where the rows disagree and stays absent where one tool wrote
+them all; `chsum --source codex` narrows a listing to one tool.
+
+Claude Code writes the record shape chsum reads, so its transcripts are read
+where they lie. A Codex rollout is written once into that shape under
+`<data dir>/chsum/translated/codex/`, and rebuilt whenever the rollout grows or
+the translation rule changes. Every line number a drill-down prints names that
+translated file, so `sed -n '1454p' <path>` lands on the record the digest
+quoted.
+
+Three properties of a Codex rollout show up in the output, and each is the file
+speaking rather than a fault in the reading:
+
+- **No titles.** Codex records no title for a thread, so a row reads
+  `(untitled)` until `chsum name` gives it one. That name holds in chsum; it
+  does not travel back to Codex, which never reads the translated copy.
+- **`0s` durations.** A thread imported into Codex carries one timestamp on
+  every record, stamped when the import landed. Duration is the spread of the
+  stamps, so such a session reports `0s` however many turns it holds. Of 102
+  rollouts measured, 46 are imports.
+- **No reasoning.** Codex encrypts model reasoning into `encrypted_content`,
+  sealed server-side with no key on the machine. The plaintext `summary` beside
+  it, present on roughly a third, becomes a thinking block. chsum skips thinking
+  rows for both tools, so nothing printed changes.
+
+Rollouts older than seven days are rewritten as `.jsonl.zst` by recent Codex
+versions. Reading one needs a zstd decoder, and chsum holds no dependency
+outside the standard library, so compressed rollouts are left alone.
+
+Adding a third tool costs one file in `chsum/sources/`: where its sessions sit,
+which directory each ran in, and a translation to the common record shape. No
+reader below that layer names a format.
+
+## `chsum where`
+
+Every locator chsum prints — `01a0acf9:31` beside a turn, `f1b9bbc6:26` on a
+row — names a line in a file. This turns one into the command that prints it:
+
+```
+$ chsum where 01a0acf9:31
+sed -n '31p' /Users/joshua/.local/share/chsum/translated/codex/…/01a0acf9-….jsonl | jq
+```
+
+The command alone goes to stdout, so it pipes and substitutes:
+
+```sh
+chsum where 01a0acf9:31 | sh          # print that record
+vim $(chsum where 01a0acf9 | awk '{print $4}')
+```
+
+The file it resolved to, and where the line sits in it, go to stderr — beside
+the command on a terminal, out of the way in a pipe.
+
+Four forms, all of them things chsum printed:
+
+| you have | you type |
+|---|---|
+| one row | `chsum where 01a0acf9:31` |
+| a run of rows | `chsum where 01a0acf9:31-40` |
+| a subagent's row | `chsum where 01a0acf9/a9f0f78b:3` |
+| a session, no row yet | `chsum where 01a0acf9` — prints the path and the template |
+| a tool call id | `chsum where toolu_01V7rDx5Le` — resolves to the row it sits on |
+| a checkpoint stamp | `chsum where <session>:<call-id>` — both halves, as the reflog holds them |
+
+A `ch_…` ref works wherever a session id does. A line past the end of the file
+stops and says how many rows the file holds, rather than handing back a `sed`
+command that prints nothing.
+
+A checkpoint commit is stamped `chsum-checkpoint: <session> @ <time> <call-id>`,
+so a line read out of `git reflog` reaches the call that caused it:
+
+```sh
+git reflog --format='%gs' | grep chsum-checkpoint | head -1 |
+  sed 's/.*checkpoint: \([^ ]*\) @ [^ ]* \(.*\)/\1:\2/' |
+  xargs chsum where | sh
+```
+
+A bare id works too — `chsum where toolu_01V7rDx5Le` searches this project, then
+every project. Naming the session beside it reads that one file directly.
+
 ## `chsum find`
 
 Locate a conversation, or a note, by what it said. This is the one command that
@@ -705,19 +878,62 @@ every repository — and do nothing until that repository opts in. The gate is
 and never committed. When the file is absent, the SessionStart hook asks Claude
 to put the question to you once, and the answer is what writes the file.
 
-Once enabled, the Stop hook commits the working tree on every turn with
-`--no-verify`, then `git reset --soft` back to where `HEAD` was. The checkpoint
-commit ends up referenced by no branch — invisible to `git log` and `git status`
-— but sits in `HEAD`'s reflog, tagged `chsum-checkpoint: <session> @
-<timestamp>`. `recap` reads those back and diffs consecutive checkpoints, which
-sees every change however it was made and carries current line ranges; the
-transcript scan sees `Edit`/`Write`/`MultiEdit` only. Retention is the reflog's
-(~90 days, shorter once `git gc` runs), so the transcript stays the permanent
-fallback and the recap states, as counts, which source each turn came from.
+Once enabled, each tool call that changes the tree is committed under
+`refs/chsum/<session>`, chained onto the previous checkpoint and tagged
+`chsum-checkpoint: <session> @ <timestamp> <tool-call-id>`. The commit is built
+with `git commit-tree` from a throwaway index, so **`HEAD`, your index and your
+working tree are never written** — nothing here can leave a checkpoint as your
+branch tip, and your own commit hooks never fire. It shows in no normal git
+command: `git log`, `git branch` and `git status` are unchanged. `git log --all`
+does list it, since that means every ref.
+
+`recap` and `chsum digest --writes` read the chain and diff consecutive
+checkpoints, which sees every change however it was made and carries current
+line ranges; the transcript scan sees `Edit`/`Write`/`MultiEdit` only.
+
+Because each checkpoint is parented on the last, `git show <checkpoint>` is that
+call's own diff and `git log refs/chsum/<session>` is the session's history. A
+ref is a gc root, so a chain survives `git gc`, survives the reflog expiring,
+and survives the removal of the worktree it was written in — all three of which
+lost the old reflog-based checkpoints.
+
+That durability is why retention is asked for rather than waited for:
+
+```sh
+chsum checkpoints                   # the chains this repo holds, and the gate
+chsum checkpoints --enable          # turn checkpointing on for this project
+chsum checkpoints --disable         # off; chains already recorded stay readable
+chsum checkpoints --prune 30d       # drop chains older than 30 days
+chsum checkpoints --prune 30d --dry-run
+```
+
+The gate is per project and per worktree, held in the git directory. `--enable`
+and `--disable` are both decisions, so either one stops the session-start prompt
+asking again.
+
+Dropping a chain leaves the transcript untouched and makes its commits
+unreachable, which git reclaims on its next `gc`.
+
+Checkpoints written by an older chsum sit in `HEAD`'s reflog instead. They are
+still read — the two sources merge on the stamp each checkpoint carries — but
+they keep the old fragility: unreachable, so a `gc` takes them, and held in the
+worktree's own reflog, so `git worktree remove` takes them with it. Rebuild them
+as chains to keep them:
+
+```sh
+chsum checkpoints --migrate --dry-run   # sessions still reflog-only, and counts
+chsum checkpoints --migrate             # rebuild each as a chain
+```
+
+A project still holding reflog-only checkpoints is told so once at session
+start, the same way the opt-in is raised, and the message names this command.
 
-The hook writes a state file before the commit-and-reset and removes it after,
-so a process killed in between leaves a checkpoint as the branch tip only until
-the next invocation's self-heal resets it away.
+Each checkpoint is rebuilt from the tree and message it already carries, so the
+content is identical and only the shas change — a parent is part of what a sha
+hashes, so an existing commit cannot be re-parented. Nothing downstream resolves
+a checkpoint by sha; `--writes`, `recap` and `chsum where <call-id>` all match on
+the session and call id in the message. The reflog entries stay where they are,
+and a second run finds nothing to do.
 
 ## Where chsum writes
 
@@ -726,8 +942,10 @@ Digests, your session names and the turn store share one directory:
 ```
 <data dir>/chsum/
   digests/<uuid>.md                              `chsum digest <ref>`'s output (`--out` to change)
+  digests/<uuid>-<view>.md                       a row view's output — messages, tools, commands, agents, call-<id>
   names.json                                     your names for sessions
   turns/<project>/<turn-uuid>.json               one turn's recap bullets and notes
+  translated/<tool>/projects/<project>/<id>.jsonl   another tool's session, in the record shape chsum reads
 ```
 
 `CHSUM_DIR` in the environment names the directory outright. Otherwise
@@ -737,7 +955,10 @@ A `~/.chsum` from an earlier version moves there on the next run, once, with a
 line on stderr naming both paths.
 
 Nothing is written to a transcript, with one exception: `chsum name` appends an
-`ai-title` record, the shape Claude Code itself appends.
+`ai-title` record, the shape Claude Code itself appends. That append is skipped
+for a translated session, whose file is rebuilt from its original and whose
+original is never read back by chsum — the name holds in `names.json`, which is
+what every listing reads.
 
 ## Which version am I running