claude-code-sessions 0.16.0__tar.gz → 0.16.1__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (34) hide show
  1. {claude_code_sessions-0.16.0 → claude_code_sessions-0.16.1}/PKG-INFO +34 -4
  2. {claude_code_sessions-0.16.0 → claude_code_sessions-0.16.1}/README.md +33 -3
  3. {claude_code_sessions-0.16.0 → claude_code_sessions-0.16.1}/claude_code_sessions.egg-info/PKG-INFO +34 -4
  4. {claude_code_sessions-0.16.0 → claude_code_sessions-0.16.1}/claude_code_sessions.egg-info/SOURCES.txt +1 -0
  5. {claude_code_sessions-0.16.0 → claude_code_sessions-0.16.1}/claude_code_sessions.py +297 -32
  6. claude_code_sessions-0.16.1/tests/test_duplicate_transcripts.py +392 -0
  7. {claude_code_sessions-0.16.0 → claude_code_sessions-0.16.1}/tests/test_plan_move.py +263 -0
  8. {claude_code_sessions-0.16.0 → claude_code_sessions-0.16.1}/LICENSE +0 -0
  9. {claude_code_sessions-0.16.0 → claude_code_sessions-0.16.1}/claude_code_sessions.egg-info/dependency_links.txt +0 -0
  10. {claude_code_sessions-0.16.0 → claude_code_sessions-0.16.1}/claude_code_sessions.egg-info/entry_points.txt +0 -0
  11. {claude_code_sessions-0.16.0 → claude_code_sessions-0.16.1}/claude_code_sessions.egg-info/top_level.txt +0 -0
  12. {claude_code_sessions-0.16.0 → claude_code_sessions-0.16.1}/claude_code_sessions_gui.py +0 -0
  13. {claude_code_sessions-0.16.0 → claude_code_sessions-0.16.1}/pyproject.toml +0 -0
  14. {claude_code_sessions-0.16.0 → claude_code_sessions-0.16.1}/setup.cfg +0 -0
  15. {claude_code_sessions-0.16.0 → claude_code_sessions-0.16.1}/tests/test_alignment.py +0 -0
  16. {claude_code_sessions-0.16.0 → claude_code_sessions-0.16.1}/tests/test_anonymize.py +0 -0
  17. {claude_code_sessions-0.16.0 → claude_code_sessions-0.16.1}/tests/test_cli.py +0 -0
  18. {claude_code_sessions-0.16.0 → claude_code_sessions-0.16.1}/tests/test_commands.py +0 -0
  19. {claude_code_sessions-0.16.0 → claude_code_sessions-0.16.1}/tests/test_containment.py +0 -0
  20. {claude_code_sessions-0.16.0 → claude_code_sessions-0.16.1}/tests/test_converge.py +0 -0
  21. {claude_code_sessions-0.16.0 → claude_code_sessions-0.16.1}/tests/test_discovery.py +0 -0
  22. {claude_code_sessions-0.16.0 → claude_code_sessions-0.16.1}/tests/test_encoding.py +0 -0
  23. {claude_code_sessions-0.16.0 → claude_code_sessions-0.16.1}/tests/test_engine.py +0 -0
  24. {claude_code_sessions-0.16.0 → claude_code_sessions-0.16.1}/tests/test_golden.py +0 -0
  25. {claude_code_sessions-0.16.0 → claude_code_sessions-0.16.1}/tests/test_gui_models.py +0 -0
  26. {claude_code_sessions-0.16.0 → claude_code_sessions-0.16.1}/tests/test_helpers.py +0 -0
  27. {claude_code_sessions-0.16.0 → claude_code_sessions-0.16.1}/tests/test_journal.py +0 -0
  28. {claude_code_sessions-0.16.0 → claude_code_sessions-0.16.1}/tests/test_recover.py +0 -0
  29. {claude_code_sessions-0.16.0 → claude_code_sessions-0.16.1}/tests/test_retitle.py +0 -0
  30. {claude_code_sessions-0.16.0 → claude_code_sessions-0.16.1}/tests/test_rows.py +0 -0
  31. {claude_code_sessions-0.16.0 → claude_code_sessions-0.16.1}/tests/test_scaffold.py +0 -0
  32. {claude_code_sessions-0.16.0 → claude_code_sessions-0.16.1}/tests/test_sync.py +0 -0
  33. {claude_code_sessions-0.16.0 → claude_code_sessions-0.16.1}/tests/test_transcripts.py +0 -0
  34. {claude_code_sessions-0.16.0 → claude_code_sessions-0.16.1}/tests/test_undo.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: claude-code-sessions
3
- Version: 0.16.0
3
+ Version: 0.16.1
4
4
  Summary: Unofficial tool for Claude Code sessions on disk: make a session visible under your other Claude account on the same machine, or move one between project folders. Command line or GUI. Journaled, reversible, fails closed.
5
5
  Author: Craig Stoller
6
6
  License: MIT
@@ -622,9 +622,17 @@ window.
622
622
  | CLI-only sessions (any OS) | transcript layout verified | mutations allowed via `--transcript-only` |
623
623
 
624
624
  The dates are measurements against specific builds - most recently Claude Desktop
625
- 1.24012.11.0 (Microsoft Store install) and Claude Code CLI 2.1.220. The on-disk format has
626
- changed once already during this tool's own development; treat a much newer build as
627
- unverified territory.
625
+ 2.42304.0.0 (Microsoft Store MSIX install) and Claude Code CLI 2.1.302. On 2026-10-14 the
626
+ read-only paths were verified against a real Desktop 2.x store, build 2.37337.1.0 (`list`,
627
+ `doctor`, `alignment`, `recover` without `--apply`, and a `converge` dry run): the row format
628
+ had only gained keys, and every row this tool had written under 1.x was still present, some
629
+ already re-saved by the new app. Later on 2026-10-14 a `converge --apply` ran against that
630
+ 2.x store with the app closed: after the app restarted, every row it had written was still
631
+ present and `doctor` reported none vanished. On 2026-10-17 two more `converge --apply` runs
632
+ went through against 2.42304.0.0 with the app closed, with the same result. That build moved
633
+ the browser-extension helper, which the running-app guard follows from 0.16.1 (see Roadmap).
634
+ The on-disk format has changed once already during this tool's own development; treat a
635
+ much newer build as unverified territory.
628
636
 
629
637
  **On non-Windows, `move` and every `sync` route refuse to touch the desktop store, and there
630
638
  is no flag to override that.** The layout is confirmed on Windows only; macOS reportedly has
@@ -950,6 +958,28 @@ window into `journaled`/`completed`/`rolled_back`.
950
958
  placement, and the one box the operator's own habit would have flipped stays opt-in per
951
959
  run because RULING 8 says so. DPI awareness, the audit's last item, is its own later
952
960
  release; the harness it needed now exists.
961
+ - **0.16.1 follows the desktop app's browser helper to its new folder.** Desktop 2.42304.0
962
+ deleted the `ChromeNativeHost` folder beside the session store and installed the helper in
963
+ a versioned `Claude-NativeHost\<version>` folder instead. This tool recognised the helper
964
+ only at the old exact path, so the copy at the new one counted as the running app. With the
965
+ desktop app closed and a browser running the Claude extension, every apply refused, and
966
+ neither the measured-build exclusion nor the signed-helper opt-in was consulted. The guard
967
+ failed closed, but the refusal said only to close the desktop app, which was already
968
+ closed. The guard now also recognises the new layout, derived from the real store root,
969
+ with the version folder accepted only when it is dotted ASCII digits; what each exclusion
970
+ requires is unchanged. When a process named like the helper sits at a location neither
971
+ rule recognises, the refusal now names its path and says neither exclusion can apply, so
972
+ the next move shows up in the refusal instead of failing silently. The note says Chrome or
973
+ Edge can launch the helper; on the machine where this was found, Edge did. The measurement
974
+ ceremony and the opt-in check script now find the helper where the guard does; the
975
+ ceremony had been waiting indefinitely for a helper it could not see. Also in this
976
+ release: when a session's transcript exists in two project folders and one copy is a
977
+ strict byte-prefix of the other, the duplicated-transcript hold names the stale copy, the
978
+ live copy and the removal command. It still chooses nothing. Identical copies are named
979
+ as interchangeable; copies that have diverged keep the old wording. The prefix case is
980
+ what a desktop session leaves behind when it enters a second worktree and is later
981
+ resumed in the one its sidebar row remembers: the copy in the second worktree stops
982
+ growing. It was seen twice on one machine in October.
953
983
  - Platform rows above move from "unverified" to "verified" as contributors confirm the store
954
984
  paths and behavior on their own machines.
955
985
 
@@ -592,9 +592,17 @@ window.
592
592
  | CLI-only sessions (any OS) | transcript layout verified | mutations allowed via `--transcript-only` |
593
593
 
594
594
  The dates are measurements against specific builds - most recently Claude Desktop
595
- 1.24012.11.0 (Microsoft Store install) and Claude Code CLI 2.1.220. The on-disk format has
596
- changed once already during this tool's own development; treat a much newer build as
597
- unverified territory.
595
+ 2.42304.0.0 (Microsoft Store MSIX install) and Claude Code CLI 2.1.302. On 2026-10-14 the
596
+ read-only paths were verified against a real Desktop 2.x store, build 2.37337.1.0 (`list`,
597
+ `doctor`, `alignment`, `recover` without `--apply`, and a `converge` dry run): the row format
598
+ had only gained keys, and every row this tool had written under 1.x was still present, some
599
+ already re-saved by the new app. Later on 2026-10-14 a `converge --apply` ran against that
600
+ 2.x store with the app closed: after the app restarted, every row it had written was still
601
+ present and `doctor` reported none vanished. On 2026-10-17 two more `converge --apply` runs
602
+ went through against 2.42304.0.0 with the app closed, with the same result. That build moved
603
+ the browser-extension helper, which the running-app guard follows from 0.16.1 (see Roadmap).
604
+ The on-disk format has changed once already during this tool's own development; treat a
605
+ much newer build as unverified territory.
598
606
 
599
607
  **On non-Windows, `move` and every `sync` route refuse to touch the desktop store, and there
600
608
  is no flag to override that.** The layout is confirmed on Windows only; macOS reportedly has
@@ -920,6 +928,28 @@ window into `journaled`/`completed`/`rolled_back`.
920
928
  placement, and the one box the operator's own habit would have flipped stays opt-in per
921
929
  run because RULING 8 says so. DPI awareness, the audit's last item, is its own later
922
930
  release; the harness it needed now exists.
931
+ - **0.16.1 follows the desktop app's browser helper to its new folder.** Desktop 2.42304.0
932
+ deleted the `ChromeNativeHost` folder beside the session store and installed the helper in
933
+ a versioned `Claude-NativeHost\<version>` folder instead. This tool recognised the helper
934
+ only at the old exact path, so the copy at the new one counted as the running app. With the
935
+ desktop app closed and a browser running the Claude extension, every apply refused, and
936
+ neither the measured-build exclusion nor the signed-helper opt-in was consulted. The guard
937
+ failed closed, but the refusal said only to close the desktop app, which was already
938
+ closed. The guard now also recognises the new layout, derived from the real store root,
939
+ with the version folder accepted only when it is dotted ASCII digits; what each exclusion
940
+ requires is unchanged. When a process named like the helper sits at a location neither
941
+ rule recognises, the refusal now names its path and says neither exclusion can apply, so
942
+ the next move shows up in the refusal instead of failing silently. The note says Chrome or
943
+ Edge can launch the helper; on the machine where this was found, Edge did. The measurement
944
+ ceremony and the opt-in check script now find the helper where the guard does; the
945
+ ceremony had been waiting indefinitely for a helper it could not see. Also in this
946
+ release: when a session's transcript exists in two project folders and one copy is a
947
+ strict byte-prefix of the other, the duplicated-transcript hold names the stale copy, the
948
+ live copy and the removal command. It still chooses nothing. Identical copies are named
949
+ as interchangeable; copies that have diverged keep the old wording. The prefix case is
950
+ what a desktop session leaves behind when it enters a second worktree and is later
951
+ resumed in the one its sidebar row remembers: the copy in the second worktree stops
952
+ growing. It was seen twice on one machine in October.
923
953
  - Platform rows above move from "unverified" to "verified" as contributors confirm the store
924
954
  paths and behavior on their own machines.
925
955
 
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: claude-code-sessions
3
- Version: 0.16.0
3
+ Version: 0.16.1
4
4
  Summary: Unofficial tool for Claude Code sessions on disk: make a session visible under your other Claude account on the same machine, or move one between project folders. Command line or GUI. Journaled, reversible, fails closed.
5
5
  Author: Craig Stoller
6
6
  License: MIT
@@ -622,9 +622,17 @@ window.
622
622
  | CLI-only sessions (any OS) | transcript layout verified | mutations allowed via `--transcript-only` |
623
623
 
624
624
  The dates are measurements against specific builds - most recently Claude Desktop
625
- 1.24012.11.0 (Microsoft Store install) and Claude Code CLI 2.1.220. The on-disk format has
626
- changed once already during this tool's own development; treat a much newer build as
627
- unverified territory.
625
+ 2.42304.0.0 (Microsoft Store MSIX install) and Claude Code CLI 2.1.302. On 2026-10-14 the
626
+ read-only paths were verified against a real Desktop 2.x store, build 2.37337.1.0 (`list`,
627
+ `doctor`, `alignment`, `recover` without `--apply`, and a `converge` dry run): the row format
628
+ had only gained keys, and every row this tool had written under 1.x was still present, some
629
+ already re-saved by the new app. Later on 2026-10-14 a `converge --apply` ran against that
630
+ 2.x store with the app closed: after the app restarted, every row it had written was still
631
+ present and `doctor` reported none vanished. On 2026-10-17 two more `converge --apply` runs
632
+ went through against 2.42304.0.0 with the app closed, with the same result. That build moved
633
+ the browser-extension helper, which the running-app guard follows from 0.16.1 (see Roadmap).
634
+ The on-disk format has changed once already during this tool's own development; treat a
635
+ much newer build as unverified territory.
628
636
 
629
637
  **On non-Windows, `move` and every `sync` route refuse to touch the desktop store, and there
630
638
  is no flag to override that.** The layout is confirmed on Windows only; macOS reportedly has
@@ -950,6 +958,28 @@ window into `journaled`/`completed`/`rolled_back`.
950
958
  placement, and the one box the operator's own habit would have flipped stays opt-in per
951
959
  run because RULING 8 says so. DPI awareness, the audit's last item, is its own later
952
960
  release; the harness it needed now exists.
961
+ - **0.16.1 follows the desktop app's browser helper to its new folder.** Desktop 2.42304.0
962
+ deleted the `ChromeNativeHost` folder beside the session store and installed the helper in
963
+ a versioned `Claude-NativeHost\<version>` folder instead. This tool recognised the helper
964
+ only at the old exact path, so the copy at the new one counted as the running app. With the
965
+ desktop app closed and a browser running the Claude extension, every apply refused, and
966
+ neither the measured-build exclusion nor the signed-helper opt-in was consulted. The guard
967
+ failed closed, but the refusal said only to close the desktop app, which was already
968
+ closed. The guard now also recognises the new layout, derived from the real store root,
969
+ with the version folder accepted only when it is dotted ASCII digits; what each exclusion
970
+ requires is unchanged. When a process named like the helper sits at a location neither
971
+ rule recognises, the refusal now names its path and says neither exclusion can apply, so
972
+ the next move shows up in the refusal instead of failing silently. The note says Chrome or
973
+ Edge can launch the helper; on the machine where this was found, Edge did. The measurement
974
+ ceremony and the opt-in check script now find the helper where the guard does; the
975
+ ceremony had been waiting indefinitely for a helper it could not see. Also in this
976
+ release: when a session's transcript exists in two project folders and one copy is a
977
+ strict byte-prefix of the other, the duplicated-transcript hold names the stale copy, the
978
+ live copy and the removal command. It still chooses nothing. Identical copies are named
979
+ as interchangeable; copies that have diverged keep the old wording. The prefix case is
980
+ what a desktop session leaves behind when it enters a second worktree and is later
981
+ resumed in the one its sidebar row remembers: the copy in the second worktree stops
982
+ growing. It was seen twice on one machine in October.
953
983
  - Platform rows above move from "unverified" to "verified" as contributors confirm the store
954
984
  paths and behavior on their own machines.
955
985
 
@@ -15,6 +15,7 @@ tests/test_commands.py
15
15
  tests/test_containment.py
16
16
  tests/test_converge.py
17
17
  tests/test_discovery.py
18
+ tests/test_duplicate_transcripts.py
18
19
  tests/test_encoding.py
19
20
  tests/test_engine.py
20
21
  tests/test_golden.py
@@ -22,7 +22,7 @@ import sys
22
22
  # only answer worth printing. A hardcoded duplicate in pyproject could disagree
23
23
  # with the module after a partial bump, and the disagreement would surface as a
24
24
  # user reporting a bug against a version they were not running.
25
- __version__ = "0.16.0"
25
+ __version__ = "0.16.1"
26
26
 
27
27
  SCHEME_CURRENT = r"[^A-Za-z0-9]" # app >= ~2026-07-12: underscores also become '-'
28
28
  SCHEME_LEGACY = r"[^A-Za-z0-9_]" # before: underscores survived
@@ -361,6 +361,166 @@ def find_transcripts(projects_root, session_id):
361
361
  return hits
362
362
 
363
363
 
364
+ # How much of each copy the duplicated-transcript diagnosis reads at a time.
365
+ # Streaming, so no copy is ever held whole and the longest is read once, only
366
+ # as far as the longest of the others: transcripts run to 96 MB, and this is
367
+ # advice printed beside a refusal, not a reason to read one twice.
368
+ _COPIES_CHUNK = 1024 * 1024
369
+
370
+
371
+ def _byte_prefixes(ref_path, others):
372
+ """For each (path, size) in OTHERS, whether that file's SIZE bytes are
373
+ exactly the first SIZE bytes of REF_PATH. One pass over REF_PATH, every
374
+ other copy read alongside it and dropped at its first mismatch. None when
375
+ a file ends short of its stat size - it changed under the read. OSError
376
+ propagates."""
377
+ results = [None] * len(others)
378
+ handles = []
379
+ try:
380
+ ref = open(ref_path, "rb")
381
+ handles.append(ref)
382
+ for p, _n in others:
383
+ handles.append(open(p, "rb"))
384
+ pending = list(range(len(others)))
385
+ pos = 0
386
+ while pending:
387
+ chunk = ref.read(_COPIES_CHUNK)
388
+ for i in list(pending):
389
+ n = others[i][1]
390
+ need = min(len(chunk), n - pos)
391
+ got = handles[i + 1].read(need)
392
+ if len(got) < need:
393
+ return None
394
+ if got != chunk[:need]:
395
+ results[i] = False
396
+ pending.remove(i)
397
+ elif pos + need >= n:
398
+ results[i] = True
399
+ pending.remove(i)
400
+ if not chunk:
401
+ return None if pending else results
402
+ pos += len(chunk)
403
+ return results
404
+ finally:
405
+ for fh in handles:
406
+ fh.close()
407
+
408
+
409
+ def _transcript_copies(paths):
410
+ """How the copies of ONE session's transcript relate: a diagnosis for the
411
+ duplicated-transcript refusal, never a choice. The refusal stands whatever
412
+ this says, and nothing here removes, prefers or writes a file.
413
+
414
+ `relation` is one of
415
+ strict_prefix every copy but the longest is a byte-prefix of it - what
416
+ an append-only transcript leaves when one copy stopped
417
+ growing and another carried on (seen in 2026-10 after a
418
+ desktop session entered a second worktree and was later
419
+ resumed from its sidebar row) - so the shorter copies are
420
+ `stale` and the longest is `live`;
421
+ identical every copy is the same bytes, so any one of them can go;
422
+ diverged some copy is not a prefix of the longest: two histories,
423
+ which only the user can choose between or merge;
424
+ inconclusive the bytes do not settle it - a copy unreadable or
425
+ changing under the read, or several tied for longest -
426
+ with `reason` saying which.
427
+ Only strict_prefix fills `live` and `stale`; `copies` lists every path
428
+ with its size.
429
+ """
430
+ out = {"relation": "inconclusive", "reason": "", "live": "", "stale": [],
431
+ "copies": []}
432
+ sizes = []
433
+ for p in paths:
434
+ try:
435
+ sizes.append(os.path.getsize(p))
436
+ except OSError:
437
+ sizes.append(None)
438
+ out["copies"] = [{"path": p, "bytes": n} for p, n in zip(paths, sizes)]
439
+ if None in sizes:
440
+ out["reason"] = "a copy could not be read"
441
+ return out
442
+ top = max(sizes)
443
+ ref = sizes.index(top)
444
+ others = [i for i in range(len(paths)) if i != ref]
445
+ try:
446
+ same = _byte_prefixes(paths[ref], [(paths[i], sizes[i])
447
+ for i in others])
448
+ after = [os.path.getsize(p) for p in paths]
449
+ except OSError:
450
+ out["reason"] = "a copy could not be read"
451
+ return out
452
+ if same is None or after != sizes:
453
+ # Stat, compare, stat again - _transcript_facts' own rule: an answer
454
+ # about bytes that moved during the read describes no file.
455
+ out["reason"] = "a copy changed while it was being compared"
456
+ return out
457
+ if not all(same):
458
+ out["relation"] = "diverged"
459
+ return out
460
+ longest = [i for i in range(len(paths)) if sizes[i] == top]
461
+ if len(longest) == len(paths):
462
+ out["relation"] = "identical"
463
+ elif len(longest) == 1:
464
+ out["relation"] = "strict_prefix"
465
+ out["live"] = paths[ref]
466
+ out["stale"] = [paths[i] for i in others]
467
+ else:
468
+ out["reason"] = "more than one copy is the longest"
469
+ return out
470
+
471
+
472
+ def _remove_command(env, path):
473
+ """The removal a stale-copy diagnosis prints, quoted for the platform's
474
+ usual shell. Single quotes, so nothing in the path expands; -LiteralPath,
475
+ so PowerShell does not read [ ] as a wildcard. PowerShell also treats the
476
+ typographic single quotes as quotes, so each is doubled like the ASCII
477
+ one."""
478
+ if env.is_windows:
479
+ for q in "'\u2018\u2019\u201a\u201b":
480
+ path = path.replace(q, q + q)
481
+ return "Remove-Item -LiteralPath '{0}'".format(path)
482
+ return "rm -- '{0}'".format(path.replace("'", "'\\''"))
483
+
484
+
485
+ def _copies_advice(env, tc):
486
+ """The diagnosis half of a duplicated-transcript refusal - the text that
487
+ follows 'Nothing was written.' - or None when the copies are diverged or
488
+ inconclusive, which keep the older advice: a diagnosis is only worth
489
+ printing when the bytes settle it. Paths are printed whole, so redact()
490
+ and --anonymize treat them as they treat every path in a refusal."""
491
+ size = {c["path"]: c["bytes"] for c in tc["copies"]}
492
+ if tc["relation"] == "strict_prefix":
493
+ stale = tc["stale"]
494
+ one = len(stale) == 1
495
+ lines = [" live : {0} ({1:,} bytes)".format(
496
+ tc["live"], size[tc["live"]])]
497
+ lines += [" stale : {0} ({1:,} bytes)".format(p, size[p])
498
+ for p in stale]
499
+ lines.append(" suggested fix - remove the stale cop{0} (--verbose "
500
+ "prints {1} in full):".format("y" if one else "ies",
501
+ "its path" if one
502
+ else "their paths"))
503
+ lines += [" " + _remove_command(env, p) for p in stale]
504
+ return ("The copies are one history at different lengths: {0} a "
505
+ "strict byte-prefix of the {3}, which is what an "
506
+ "append-only transcript leaves when one copy stopped growing "
507
+ "and another carried on. So the shorter cop{1} stale and the "
508
+ "{3} is the live one. Nothing is chosen for you; once the "
509
+ "stale cop{1} gone, the row will open the live one:\n{2}"
510
+ .format("the shorter copy is" if one
511
+ else "every shorter copy is",
512
+ "y is" if one else "ies are", "\n".join(lines),
513
+ "longer" if one else "longest"))
514
+ if tc["relation"] == "identical":
515
+ return ("The copies are byte-identical ({0:,} bytes each), so {1} can "
516
+ "go. Remove or rename all but one - whichever is left is what "
517
+ "the row will open:\n{2}".format(
518
+ tc["copies"][0]["bytes"],
519
+ "either" if len(tc["copies"]) == 2 else "any of them",
520
+ "\n".join(" " + c["path"] for c in tc["copies"])))
521
+ return None
522
+
523
+
364
524
  def iter_transcripts(projects_root):
365
525
  out = []
366
526
  try:
@@ -734,23 +894,59 @@ def _expected_helper_paths(env):
734
894
  copied to C:\\tmp\\packages\\claude_x\\localcache\\roaming\\claude\\
735
895
  chromenativehost\\chrome-native-host.exe would have been excused. The
736
896
  "out-of-path binaries still count" guarantee was not actually enforced.
897
+
898
+ A candidate that is not an absolute path derives nothing. With APPDATA unset
899
+ the classic candidate is the relative Claude\\claude-code-sessions, and abspath
900
+ resolved its helper location against whatever the working directory was.
737
901
  """
738
902
  out = set()
739
903
  for cand in getattr(env, "store_candidates", ()) or ():
904
+ if not os.path.isabs(cand):
905
+ continue
740
906
  parent = os.path.dirname(cand)
741
907
  out.add(os.path.normcase(os.path.abspath(
742
908
  os.path.join(parent, "ChromeNativeHost", "chrome-native-host.exe"))))
743
909
  return out
744
910
 
745
911
 
912
+ # Amendment 2026-10-17 (docs/internals.md). Desktop 2.42304 moved the helper to
913
+ # <Roaming>\Claude-NativeHost\<version>\chrome-native-host.exe, <Roaming> being the
914
+ # folder that holds the store's Claude folder. The guard stopped recognising it, so
915
+ # neither ruling was reached and the signed-helper opt-in silently stopped working.
916
+ # The version folder is constrained to the naming the app was seen to use - dotted
917
+ # ASCII digits, matched whole; \d would also accept other scripts' digits. That is a
918
+ # narrowing, not a boundary: the folder carries the store's own ACL, so whoever can
919
+ # plant a binary there can already plant one at the old location.
920
+ _HELPER_NAME = "chrome-native-host.exe"
921
+ _NATIVE_HOST_DIR = "Claude-NativeHost"
922
+ _HELPER_VERSION_RE = re.compile(r"[0-9]+(?:\.[0-9]+)*")
923
+
924
+
925
+ def _expected_native_host_dirs(env):
926
+ """The versioned layout's Claude-NativeHost folder(s), derived from the same
927
+ store candidates as _expected_helper_paths and skipping relative ones for the
928
+ same reason."""
929
+ out = set()
930
+ for cand in getattr(env, "store_candidates", ()) or ():
931
+ if not os.path.isabs(cand):
932
+ continue
933
+ roaming = os.path.dirname(os.path.dirname(cand))
934
+ out.add(os.path.normcase(os.path.abspath(
935
+ os.path.join(roaming, _NATIVE_HOST_DIR))))
936
+ return out
937
+
938
+
746
939
  def _looks_like_chrome_helper(text, env):
747
940
  """True when TEXT is the helper's own image path at a REAL store root.
748
941
 
749
- Exact match against _expected_helper_paths, not a substring or segment test.
750
- A lister entry carrying trailing arguments (POSIX `ps` reports whole command
751
- lines) will not equal a path and therefore falls through to counting, which
752
- is the safe direction - a process merely NAMING the helper must never
753
- inherit its exclusion.
942
+ The old location is an exact match against _expected_helper_paths. The
943
+ versioned one is exact but for the version: the grandparent must equal a
944
+ derived Claude-NativeHost folder, the parent's name must be dotted ASCII
945
+ digits, and the basename must be the helper's. Neither is a substring or
946
+ segment test. A lister entry carrying trailing arguments (POSIX `ps` reports
947
+ whole command lines) will not match either and therefore falls through to
948
+ counting, which is the safe direction - a process merely NAMING the helper
949
+ must never inherit its exclusion.
754
950
  """
755
951
  if not text:
756
952
  return False
@@ -762,7 +958,12 @@ def _looks_like_chrome_helper(text, env):
762
958
  if os.sep == "\\":
763
959
  text = text.replace("/", "\\")
764
960
  norm = os.path.normcase(os.path.abspath(text))
765
- return norm in _expected_helper_paths(env)
961
+ if norm in _expected_helper_paths(env):
962
+ return True
963
+ version_dir = os.path.dirname(norm)
964
+ return (os.path.basename(norm) == os.path.normcase(_HELPER_NAME)
965
+ and _HELPER_VERSION_RE.fullmatch(os.path.basename(version_dir)) is not None
966
+ and os.path.dirname(version_dir) in _expected_native_host_dirs(env))
766
967
 
767
968
 
768
969
  def _measured_helper_state(text, env):
@@ -892,30 +1093,60 @@ def _signed_helper_state(text):
892
1093
  return "signed" if cn == _HELPER_PUBLISHER and org == _HELPER_PUBLISHER else "unsigned"
893
1094
 
894
1095
 
1096
+ _HELPER_LAUNCHED_BY = (
1097
+ "A browser running the Claude extension (Chrome or Edge) launches it, and it can "
1098
+ "outlive the desktop app. Closing every browser that runs the extension should "
1099
+ "stop it.")
1100
+
1101
+
1102
+ def _named_like_helper(text):
1103
+ """The entry's last path component is the helper's file name. Note-only: this
1104
+ decides whether to WARN about a helper nothing recognises, never whether to
1105
+ excuse one. Both separators are split on whatever the platform, because the
1106
+ helper is a Windows binary and its path is a Windows path."""
1107
+ return re.split(r"[\\/]", text or "")[-1].lower() == _HELPER_NAME
1108
+
1109
+
895
1110
  def helper_hash_note(running, env):
896
- """Explain a helper that is counted because it is not the measured build."""
1111
+ """Explain a helper that is counted: one that is not the measured build, or,
1112
+ failing that, one at a location this version does not recognise.
1113
+
1114
+ The helper is named by its path, never as "the process above": the refusal
1115
+ prints only the first process it found, which may be the desktop app."""
897
1116
  for text in running:
898
1117
  state = _measured_helper_state(text, env)
899
1118
  if state in ("changed", "unreadable"):
900
1119
  note = (
901
- "\nNote: the process above is the desktop app's Chrome-extension "
902
- "helper. A measured build of it is excluded from this guard, but this "
903
- "one {0} - the helper auto-updates in place, so an exclusion cannot "
904
- "carry over to code that was never measured. Closing Chrome clears "
905
- "this. To restore the exclusion, re-measure with "
1120
+ "\nNote: {0} is the desktop app's browser-extension helper. {1} A "
1121
+ "measured build of it is excluded from this guard, but this one {2} - "
1122
+ "the helper auto-updates, so an exclusion cannot carry over to code "
1123
+ "that was never measured. To restore the exclusion, re-measure with "
906
1124
  "tools/native-host-measurement/watch_ceremony.py (about 12 minutes) "
907
1125
  "and update _HELPER_SHA256.".format(
1126
+ text, _HELPER_LAUNCHED_BY,
908
1127
  "could not be read" if state == "unreadable"
909
1128
  else "is a different binary"))
910
1129
  if not signed_helper_trust_enabled(env):
911
1130
  note += (
912
1131
  "\nThe helper updates every few days, so re-measuring each time is "
913
1132
  "usually not worth it. The alternative is to trust any helper at "
914
- "this path that Windows reports as validly signed by Anthropic, "
915
- "PBC - weaker than measured bytes, and OFF by default because it "
916
- "rests on evidence you have not examined. Turn it on with:\n"
1133
+ "the app's own helper location that Windows reports as validly "
1134
+ "signed by Anthropic, PBC - weaker than measured bytes, and OFF by "
1135
+ "default because it rests on evidence you have not examined. Turn "
1136
+ "it on with:\n"
917
1137
  " claude-code-sessions trust-signed-helper --on")
918
1138
  return note
1139
+ # Ruled 2026-10-17: the next layout move must announce itself. This only
1140
+ # advises - the process keeps counting either way.
1141
+ for text in running:
1142
+ if _named_like_helper(text) and _measured_helper_state(text, env) is None:
1143
+ return (
1144
+ "\nNote: {0} is named like the desktop app's browser-extension helper "
1145
+ "but is not at a location this version recognises, so neither the "
1146
+ "measured-build exclusion nor the signed-helper opt-in can apply to "
1147
+ "it. {1} If it is the app's own helper, the app may have moved it "
1148
+ "again; reporting the location lets the guard follow it.".format(
1149
+ text, _HELPER_LAUNCHED_BY))
919
1150
  return ""
920
1151
 
921
1152
 
@@ -2891,8 +3122,10 @@ _ANON_STRUCTURAL_KEYS = frozenset((
2891
3122
  "a", "a_in_b", "a_total", "a_unique", "account", "accounts",
2892
3123
  "activity_unknown", "after", "age_days", "allow_orphan", "b",
2893
3124
  "b_in_a", "b_total", "b_unique", "blank_rows", "by_account_count",
3125
+ "bytes",
2894
3126
  "classification", "cli_session_id", "command_runnable", "complete",
2895
- "config", "consistent", "conversations", "created", "current",
3127
+ "config", "consistent", "conversations", "copies", "created",
3128
+ "current",
2896
3129
  "dead_excluded", "dead_rows", "degrade_reason", "deleted",
2897
3130
  "dest_account", "dest_dropped", "dest_email_source", "dest_org",
2898
3131
  "dest_path", "dest_reset", "destinations", "detail",
@@ -2904,26 +3137,29 @@ _ANON_STRUCTURAL_KEYS = frozenset((
2904
3137
  "held_orphan_detail", "held_same", "held_unknown", "holder_titles",
2905
3138
  "holders", "holds", "identity_disagreement", "in_all_accounts",
2906
3139
  "incoming_turns", "is_update", "last_activity", "leaving_a_gap",
2907
- "leg_suffix_note", "legacy", "legacy_folders", "listed",
3140
+ "leg_suffix_note", "legacy", "legacy_folders", "listed", "live",
2908
3141
  "live_asserted", "local_id", "max_containment", "mb", "measured",
2909
3142
  "measured_line", "model", "name", "newer_only", "no_transcript",
2910
3143
  "non_destinations", "nonterminal_ops", "notes", "now", "oauth",
2911
3144
  "of", "only", "only_session", "op_id", "op_type", "opens", "org",
2912
3145
  "orphan_ids", "orphans", "overrode_tombstone", "pairs", "path",
2913
3146
  "per_account", "post_b64", "pre_activity", "pre_b64", "present",
2914
- "reachable", "reason", "regresses", "regressing", "removed",
3147
+ "reachable", "reason", "regresses", "regressing", "relation",
3148
+ "removed",
2915
3149
  "reset", "result", "resurrected", "retitle", "rollback_declined",
2916
3150
  "rollback_residue", "roots", "row", "row_count", "row_errors",
2917
3151
  "row_path", "rows", "safe", "scope", "scoped", "session",
2918
3152
  "session_id", "sessions", "shared", "short",
2919
3153
  "short_of_all_accounts", "sibling_divergence", "siblings",
2920
3154
  "skip_detail", "skipped", "source_account", "source_org",
2921
- "source_path", "source_resolved_from", "stale_lock", "status",
3155
+ "source_path", "source_resolved_from", "stale", "stale_lock",
3156
+ "status",
2922
3157
  "store_is_a_guess", "store_label", "store_org", "store_path",
2923
3158
  "store_why", "stores", "superseded", "swapping",
2924
3159
  "swaps_conversation", "tally", "title_collision",
2925
3160
  "title_provenance", "title_source", "titles", "to_session",
2926
- "transcript", "transcript_count", "transcript_mb",
3161
+ "transcript", "transcript_copies", "transcript_count",
3162
+ "transcript_mb",
2927
3163
  "transcript_mtime", "transcript_paths", "transcript_size",
2928
3164
  "transcripts", "turns", "unchanged", "unknown_layout",
2929
3165
  "unlisted_ranked", "unlisted_recent", "unlisted_transcripts",
@@ -6183,13 +6419,21 @@ def _transcript_facts(env, session_id, fps_cache=None):
6183
6419
  if len(found) > 1:
6184
6420
  # The paths alone are evidence, not a way forward - this plan's rule is
6185
6421
  # that a refusal names one, and listing the duplicates and stopping left
6186
- # the user holding the evidence with no instruction.
6187
- raise Refusal(
6422
+ # the user holding the evidence with no instruction. When the bytes
6423
+ # settle which copies are stale (or that they are identical), the
6424
+ # refusal says so and names the fix; it still chooses nothing. The
6425
+ # structured diagnosis rides on the exception for converge's hold.
6426
+ copies = _transcript_copies(found)
6427
+ exc = Refusal(
6188
6428
  "{0} exists in more than one project folder, so a row built for it "
6189
6429
  "would name a file this tool cannot identify; refusing to guess "
6190
- "which. Nothing was written. Remove or rename the copies you do not "
6191
- "want - whichever one is left is what the row will open:\n{1}"
6192
- .format(session_id, "\n".join(" " + f for f in found)))
6430
+ "which. Nothing was written. {1}".format(
6431
+ session_id, _copies_advice(env, copies) or (
6432
+ "Remove or rename the copies you do not want - whichever "
6433
+ "one is left is what the row will open:\n" +
6434
+ "\n".join(" " + f for f in found))))
6435
+ exc.transcript_copies = copies
6436
+ raise exc
6193
6437
  path = found[0]
6194
6438
  # Stat BEFORE reading, and again after - see the comparison at the end.
6195
6439
  try:
@@ -6747,11 +6991,13 @@ def _new_row_preflight(env, m):
6747
6991
  "the transcript for {0} is no longer on disk, so this row would open "
6748
6992
  "nothing. Nothing was written.".format(m["to_session"]))
6749
6993
  if len(found) > 1:
6994
+ advice = _copies_advice(env, _transcript_copies(found))
6750
6995
  raise Refusal(
6751
6996
  "{0} now exists in more than one project folder, so the row planned "
6752
6997
  "against a single transcript no longer names one. Nothing was "
6753
- "written:\n{1}".format(m["to_session"], "\n".join(" " + f
6754
- for f in found)))
6998
+ "written{1}".format(m["to_session"], (". " + advice) if advice
6999
+ else ":\n" + "\n".join(" " + f
7000
+ for f in found)))
6755
7001
  if os.path.realpath(found[0]) != os.path.realpath(m["transcript"]):
6756
7002
  raise Refusal(
6757
7003
  "the transcript for {0} has moved since this was planned ({1} -> "
@@ -11192,11 +11438,20 @@ def plan_converge(env, flags):
11192
11438
  # pair proceeds. Refusing the whole bulk run over one such
11193
11439
  # conversation would leave the monthly chore permanently stuck on
11194
11440
  # its weirdest member.
11441
+ copies = getattr(prep, "transcript_copies", None)
11195
11442
  for acct in missing:
11196
- holds.append({"session": sid, "account": acct,
11197
- "label": dests[acct]["label"], "title": "",
11198
- "reason": "held_transcript_unusable",
11199
- "detail": str(prep), "retitle": ""})
11443
+ hold = {"session": sid, "account": acct,
11444
+ "label": dests[acct]["label"], "title": "",
11445
+ "reason": "held_transcript_unusable",
11446
+ "detail": str(prep), "retitle": ""}
11447
+ if copies is not None:
11448
+ # The duplicated-transcript diagnosis, for --json. One
11449
+ # copy per hold, never shared: the public manifest's
11450
+ # anonymize scrub rewrites these paths in place.
11451
+ hold["transcript_copies"] = dict(
11452
+ copies, stale=list(copies["stale"]),
11453
+ copies=[dict(c) for c in copies["copies"]])
11454
+ holds.append(hold)
11200
11455
  continue
11201
11456
  facts, title, title_source, disagree, holder_titles = prep
11202
11457
  if disagree:
@@ -11772,6 +12027,16 @@ def _public_converge_manifest(env, m):
11772
12027
  # not gain a null key from being displayed.
11773
12028
  if isinstance(h.get("measured_line"), str):
11774
12029
  h["measured_line"] = _scrub(h["measured_line"])
12030
+ # The duplicated-transcript diagnosis carries the same paths
12031
+ # the detail quotes, as fields - and a path names its
12032
+ # app-encoded project folder, which only this pass replaces.
12033
+ tc = h.get("transcript_copies")
12034
+ if isinstance(tc, dict):
12035
+ tc["live"] = _scrub(tc.get("live"))
12036
+ tc["stale"] = [_scrub(p) for p in tc.get("stale") or []]
12037
+ for c in tc.get("copies") or []:
12038
+ if isinstance(c, dict):
12039
+ c["path"] = _scrub(c.get("path"))
11775
12040
  for note in out.get("notes") or []:
11776
12041
  if isinstance(note, dict):
11777
12042
  note["retitle"] = _scrub(note.get("retitle"))