sessions: /branch creates generation chains — 23.9% of transcripts, and CodeV cannot tell them apart

[grimmerk]

What was measured (2026-09-05, live experiment)

/branch <name> copies the transcript to a new session id and lets the same process keep writing to the new file. Confirmed end to end on this machine:

	before	after /branch
session id	b4feeab6	a8f5603a
pid	93499	93499 (unchanged)
sessions/<pid>.json	id + name = branch-test-a	id + name updated in place
transcripts	1	2 — parent intact (57 KB, ends cleanly), child is a copy
history.jsonl	—	the /branch line lands under the parent, everything after under the child

Resuming the parent afterwards works (new pid, appends to the parent transcript). So the reported symptom is confusion, not failure.

This is not an edge case: 21 of 88 transcripts on disk (23.9%) carry forkedFrom.

The exact primitive

Claude Code records the link itself, on every copied line of the child:

"forkedFrom": { "sessionId": "<parent>", "messageUuid": "<branch point>" }

The root transcript has zero such lines. Enrichment already greps every transcript, so one more pattern yields a complete child → parent map. No heuristics, no content comparison.

Four consequences in CodeV

/branch copies the transcript but NOT history.jsonl. The child's prompts before the branch exist only in the transcript. CodeV's list is built from history.jsonl, so:

1. Deep search cannot see them. Searching for anything said before the branch finds the parent, never the child — search systematically points at the older generation.
2. messageCount is wrong. A child carrying a full conversation renders as "1 msgs" (observed: 5 msgs vs the parent's 38).
3. Pins do not follow. Verified in ~/.config/codev/session-marks.json: the pin sat on the parent while work continued in the child.
4. Ordering. Resuming a parent lifts it above the child that actually continues the work.

The sharper problem: identically-named live sessions

Because /branch moves you into the new session, the new name lands on the work you are continuing, while the original session keeps the old name — the wrong way round. The workaround in daily use is a three-step swap: branch with a temporary name, resume the parent and rename it <name>-2, then rename the child back to the original name.

Why the child gets the original name is the important part: /branch carries in-flight background subagents across, and their output lands in the child. So the unfinished task genuinely continues there, and the name follows the work. The parent is then resumed and repurposed for a different task, which is why it takes the -2.

That makes the rename dance a manual substitute for something CodeV does not provide: stable task identity across session ids. The user's mental model keys on name + task; CodeV keys on session id, and the two diverge every time a branch happens.

The result is that names are deliberately reused across generations. Measured right now:

pid=22290  id=b7f7c407  "agentic-fred harden again - pr2-1533-v7-readiness — deps ref…"
pid=20653  id=a96a4274  "agentic-fred harden again - pr2-1533-v7-readiness — deps ref…"
pid=27303  id=6fab4f73  "agentic-fred harden again - pr2-1533-v7-readiness — deps ref…"

Three distinct sessions, three live pids, identical names. CodeV is reporting this correctly — it is simply undisplayable, and scanning the terminals by eye does not separate them either.

And iTerm2 switching matches on the tab title, so all three rows switch to the same terminal. That is the "clicking any of them goes to the same session" report. Not a regression of the same-cwd work (activeStateRef is replaced wholesale each detection, and the direct pid→id mapping never reaches the cwd fallback) — it is the existing title-matching mechanism meeting a case where titles are intentionally not unique.

Proposed work, in priority order

• C0 — make same-named live sessions distinguishable, and switch by TTY/pid rather than title. This is the one that hurts today. Display needs something unique per row (branch generation, divergence time, pid/tty).
• C1 — surface the forkedFrom relation. Bind identity to the task, not blindly to the newest descendant. An earlier proposal here was to resolve pins to the tip of the chain. That is too crude: after the dance the child continues the original task while the parent is live under a different task, so both are meaningful and "newest" is not the same as "the thing you pinned". The relation should be shown, and any migration should follow the task — the signal for which is the name moving, not the chain advancing.
• C2 — messageCount summed along the chain.
• C3 — optional chain collapse in the list (plan §6's C3).
• C4 — sessions: resume fails for sessions whose transcript was cleaned up — detect and mark as expired #135 expired-session marking, which shares the "can this id still be resumed" diagnostic.

Documentation this falsifies

• docs/session-finding-plan.md §6 states C3 chain collapse is "essentially defunct … no generation chains exist; only meaningful if --fork-session / copy-fork become common." Generation chains are a daily occurrence and 23.9% of the corpus.
• §4.4 lists forking under "Edge cases (v1 ignores them; re-pin manually if hit)". Same false premise.

Both should be corrected regardless of which items above get built.

🤖 On behalf of @grimmerk — generated with Claude Code

[grimmerk]

Open question: would switching to /fork avoid this?

/fork runs the opposite way round — the copy goes out to a background session and you stay in place. The original therefore keeps both its name and its task, and in-flight subagents stay with you rather than being carried away. That removes the reason for the rename dance described above, and with it most of the pin drift.

It likely trades one problem for another, and the trade is unverified:

• CodeV switches to a session with claude --resume <uuid>. A live background session reportedly cannot be resumed that way — the picker marks it bg and refuses; entering it needs claude attach <id>, or claude stop <id> first. If that holds, clicking a forked session in CodeV would fail, which is a new gap rather than a fixed one.
• Unknown whether sessions/<pid>.json marks background sessions distinguishably (CodeV would need that to choose attach over resume).
• Unknown whether /fork also writes forkedFrom. The field name suggests it is shared, in which case the chain detection proposed above works for both.
• /fork also defaults the copy into its own worktree, so it edits files outside the current checkout.

Worth measuring before any decision, using the same method as the /branch experiment: snapshot session id / pid / transcripts / history.jsonl before and after, then click the row in CodeV and record what happens. Ten minutes.

🤖 On behalf of @grimmerk — generated with Claude Code

[grimmerk]

Cross-links and a sequencing decision, now that the surrounding work is filed.

Documentation half is done and waiting: PR #143 corrects §6 and §4.4 and adds §4.7 recording what the experiment established. It is open and only needs merging — worth landing independently of any code here, since the falsified statements are actively misleading while they stand. A stale imperative invites the next person to "fix" the code back.

Sequencing, recorded as open question 3 in #144 (the Sessions tracking issue):

• C0 goes first and is not blocked on anything. Telling identically-named live sessions apart, and switching by TTY/pid instead of by window title, is presentation and process plumbing — it needs no new abstraction, and it is the item that bites daily. Note Ghostty: no per-tab TTY/PID — missing cross-reference and TTY switch fallback #63 (Ghostty exposes no per-tab TTY) blocks the switching half on that terminal specifically, so C0 may land for iTerm2/Terminal.app first.
• C1–C3 wait for a decision on whether to introduce stable task identity across sessionIds, rather than patching each symptom. Pin drift, search pointing at ancestors, and indistinguishable rows are one gap surfacing in three places; fixing them one at a time means covering the same ground three times, each time slightly differently.

A third consumer of that decision: #145 (named session-list snapshots) stores sessionIds, so a snapshot degrades exactly the way a pin does when /branch mints a new id for the same work. That makes three features waiting on the same answer, which is itself an argument for answering it rather than routing around it.

/fork remains unverified, and it is the option that would remove the rename dance entirely rather than compensating for it. Three things to establish before it can be recommended: whether a live background session can be resumed at all (CodeV switches via claude --resume), whether /fork also writes forkedFrom, and what its default worktree behaviour does to the project mapping. Until those are measured, the dance stays the documented workflow.

🤖 On behalf of @grimmerk — generated with Claude Code

[grimmerk]

Two corrections and one addition to the /fork section above, after reading a survey of the upstream discussion.

1. Any statement about /fork must carry a version — mine did not

/fork has changed meaning twice, so unversioned notes about it go stale silently:

Version	What /fork meant
before 2.1.161	an alias of /branch
2.1.161 – 2.1.211	an in-session forked subagent
2.1.212 (2026-07-16) onward	copies the conversation into a background session; the old subagent behaviour moved to /subtask

The machine these measurements were taken on runs 2.1.260, so the third row is the one that applies here. The open questions listed above are questions about that behaviour and should be re-read with the version attached.

This also matters for reading anything written about it: material from early 2026 uses "fork" for what is now /branch, so counting mentions across articles measures the rename, not the behaviour or anyone's preference.

2. The naming problem is a known upstream gap, not a local quirk

Upstream feature request anthropics/claude-code#32631 ("Conversation Branching — full spec for fork, merge, and tree navigation") asks for, among other things, branch-tree navigation and meaningful names instead of session IDs — which is the same missing abstraction this issue names as stable task identity across sessionIds.

Read the right way round: the gap being unfilled upstream is a reason for CodeV to surface it, not a reason to wait. CodeV already holds the two things needed — forkedFrom from the transcripts, and the pid→sessionId map in ~/.claude/sessions/ — and it is the only tool in the loop that sees all sessions at once.

3. /branch shares the working tree by accident, not by design

Upstream anthropics/claude-code#81695 makes the point that branching copies the session while the working tree stays shared, so the conversation timeline and the code timeline cannot move independently. Consequence for CodeV: a session's project association can quietly stop describing what that session is actually working on after a branch. Worth knowing before building anything that keys off the project path.

The community workaround for genuinely parallel work is a git worktree plus an independent session, which sidesteps this entirely.

Decision recorded

Not switching to /fork (open question 4 in #144, decided). The upstream discussion supports that: the loudest complaint about forking is that there is no way to bring the result back — no merge-back, no branch diff, no tree view. The three-step rename dance documented above stays the working practice.

🤖 On behalf of @grimmerk — generated with Claude Code

[grimmerk]

Two corrections from continued work on this.

1. It is windows, not tabs. Sessions are run one per iTerm2 window, so the switching problem above should read window title, not tab name. The collision is identical — three live sessions sharing a name means three windows sharing a title, and title-based switching cannot separate them — but C0's fix has to target windows, and any implementation note saying "tab" is misleading.

2. Terminal choice is not where the memory goes. Measured 2026-09-05 while investigating a slow machine: iTerm2 itself held 368MB across 3 processes, while 36 claude processes held 4.66GB (32 of them with a live TTY), against 20.4GB of 21.5GB swap in use. Several sessions had been running 7-17 days. Moving to a lighter terminal emulator would reclaim the 368MB, not the 4.5GB.

That measurement also found, against ~/.claude/sessions/: 1 session registered whose process was dead (a stale row) and 1 live session with no registration (invisible as active; an earlier draft said 5, but four of those were infrastructure processes, not sessions). That is #94, and it is now grouped with this work in #144.

🤖 On behalf of @grimmerk — generated with Claude Code