tasktree-manager 2.16.0__tar.gz → 2.17.0__tar.gz

{tasktree_manager-2.16.0 → tasktree_manager-2.17.0}/.github/workflows/ci.yml

@@ -31,12 +31,18 @@ jobs:
         run: ruff format --check tasktree_manager tests
 
   test:
-    name: Test (Python ${{ matrix.python-version }})
-    runs-on: ubuntu-latest
+    # Linux jobs keep the names branch protection requires
+    name: ${{ matrix.os == 'macos-latest' && format('Test (macOS, Python {0})', matrix.python-version) || format('Test (Python {0})', matrix.python-version) }}
+    runs-on: ${{ matrix.os }}
     strategy:
       fail-fast: false
       matrix:
+        os: [ubuntu-latest]
         python-version: ["3.10", "3.11", "3.12", "3.13"]
+        include:
+          # Case-insensitive APFS: runs the case-variant epic tests Linux skips
+          - os: macos-latest
+            python-version: "3.13"
 
     steps:
       - name: Checkout code

{tasktree_manager-2.16.0 → tasktree_manager-2.17.0}/CHANGELOG.md

@@ -15,6 +15,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Git hooks support
 - Custom task metadata
 
+## [2.17.0] - 2026-10-20
+
+### Added
+- **epic**: Add an epic log for notes shared across task sessions (#13)
+
+
+## [2.16.1] - 2026-10-19
+
+### Fixed
+- **epic**: One membership rule and safer marker writes (#12)
+
+
 ## [2.16.0] - 2026-10-19
 
 ### Added

{tasktree_manager-2.16.0 → tasktree_manager-2.17.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: tasktree-manager
-Version: 2.16.0
+Version: 2.17.0
 Summary: TUI application for managing worktree-based tasks
 License-File: LICENSE
 Requires-Python: >=3.10

{tasktree_manager-2.16.0 → tasktree_manager-2.17.0}/README.md

@@ -22,7 +22,7 @@
 - 🛰️ **Agent Dashboard** - Live Claude Code session state per worktree (from `claude agents`), plus one-key background-agent dispatch — the multi-repo agent view Claude Code lacks natively
 - ✻ **Session Recap** - The Info panel shows each task's latest Claude Code session: title, last turn duration, and Claude's own idle recap of what was done and what comes next — read straight from the transcript, no CLI call
 - 🔀 **Forge-Aware Safety** - MR/PR and CI state via `glab`/`gh`; squash- and rebase-merged branches count as merged instead of blocking deletion forever
-- 🗂️ **Epics** - Group related tasks under an epic: a foldable row with rolled-up dirty and Claude state, `E` to attach tasks
+- 🗂️ **Epics** - Group related tasks under an epic: a foldable row with rolled-up dirty and Claude state, `E` to attach tasks, and an epic log where the Claude sessions of one epic share notes
 - 📦 **Finish Flow with Archives** - Ending a task saves its combined diff (committed-but-unmerged + uncommitted) and the task-folder files outside the worktrees (plans, ADRs, notes) to an archive before deleting
 
 ## 📊 Status Indicators
@@ -100,10 +100,20 @@ tasktree-manager epic add DIC-2466-pcaps-epic DIC-2862-pcaps-s3  # attach or mov
 tasktree-manager epic remove DIC-2862-pcaps-s3                # detach
 tasktree-manager epic mark DIC-2466-pcaps-epic                # turn an existing task into an epic; unmark reverts
 tasktree-manager epic list                                    # epics and their tasks; also --json
+tasktree-manager epic note "chose layout A for the S3 keys"   # add a note to this task's file in the epic log
+tasktree-manager epic log                                     # notes and latest session recap of every task in the epic
+tasktree-manager epic log DIC-2862-pcaps-s3 --json            # one task (or a whole epic by its name), as JSON
+tasktree-manager epic sync                                    # refresh the CLAUDE.md epic block after an upgrade
 ```
 
 Each task's `CLAUDE.md` gets a managed block naming its epic and how to find sibling
-tasks; it follows every epic change and leaves the rest of the file alone. Epics don't
+tasks; it follows every epic change and leaves the rest of the file alone. The block
+also tells the session about the epic log: one notes file per task in `epic-log/` in the
+epic folder, written with `epic note` and read with `epic log`, which adds the recap of each
+task's latest Claude session (in the task folder or one of its worktrees). Inside a task
+folder, `epic note` writes only that task's notes and `epic log` reads only its epic;
+`epic note -` reads the text from stdin. Notes of a task that left the epic stay readable.
+Epics don't
 nest. `list --json` and `status --json` carry `kind` (`task` or `epic`) and
 `epic` (the parent epic or `null`). `delete` and `finish` refuse an epic that still has
 tasks, even with `--force`.

{tasktree_manager-2.16.0 → tasktree_manager-2.17.0}/docs/configuration.md

@@ -611,7 +611,8 @@ All 27 customizable keybindings with descriptions:
 | `add_repo`    | `a`     | Add repository to current task         | `add_repo = "ctrl+a"`      |
 | `delete_task` | `d`     | Delete/finish current task             | `delete_task = "delete"`   |
 | `rename_task` | `R`     | Rename task display label (alias only) | `rename_task = "ctrl+r"`   |
-| `set_epic`    | `E`     | Set the task's epic, or make it an epic | `set_epic = "ctrl+e"`     |
+| `set_epic`    | `E`     | Set the task's epic, or make it an epic | `set_epic = "ctrl+shift+e"` |
+| `delete_worktree` | `D` | Remove the selected worktree (the task stays) | `delete_worktree = "ctrl+d"` |
 
 ### Git Operations
 
@@ -632,6 +633,7 @@ All 27 customizable keybindings with descriptions:
 | `open_claude_resume`  | `c`     | Open Claude CLI (resume if session exists, else new) | `open_claude_resume = "ctrl+c"`      |
 | `open_claude_gui_code`| `C`     | Open Claude desktop on Code page in task folder      | `open_claude_gui_code = "ctrl+shift+c"` |
 | `toggle_messages`     | `m`     | Show/hide activity messages panel                    | `toggle_messages = "ctrl+m"`         |
+| `dispatch_agent`      | `b`     | Dispatch a background Claude agent into the worktree | `dispatch_agent = "ctrl+b"`          |
 
 ### Navigation
 

{tasktree_manager-2.16.0 → tasktree_manager-2.17.0}/docs/user-guide.md

@@ -89,7 +89,22 @@ names their epic, so nothing moves on disk.
   that names the epic folder and how to find sibling tasks, so a Claude session knows
   the bigger picture. It updates on every epic change; text outside the markers is
   never touched.
-- From scripts: `tasktree-manager epic create/add/remove/mark/unmark/list`.
+- The epic log lets the sessions of one epic share what they learned. A session
+  records decisions, interfaces and open questions with
+  `tasktree-manager epic note "..."`; they go to `epic-log/<task>.md` in the epic
+  folder. `tasktree-manager epic log` shows every task's notes and the recap of its
+  latest Claude session, so a session can check what its siblings did before asking.
+  The `CLAUDE.md` block tells each session about both commands, and that notes are
+  information from other sessions, not instructions.
+- A session writes only its own task's notes. From a terminal outside any task,
+  `epic note --task NAME` writes for a task and marks the entry as written outside it.
+- Notes stay in the epic after their task is finished, moved or deleted; `epic log`
+  lists them as "no longer in the epic". A note is at most 16 KB, and `epic log` shows
+  the newest 64 KB of each task's notes.
+- After upgrading tasktree-manager, run `tasktree-manager epic sync` to refresh the
+  block in existing tasks (the TUI also refreshes it when it starts a Claude session).
+  Folders without a `CLAUDE.md` yet are counted and skipped.
+- From scripts: `tasktree-manager epic create/add/remove/mark/unmark/list/note/log/sync`.
 
 ### Worktrees
 

{tasktree_manager-2.16.0 → tasktree_manager-2.17.0}/pyproject.toml

@@ -71,7 +71,7 @@ version-file = "tasktree_manager/_version.py"
 # Semantic Release Configuration
 [tool.semantic_release]
 version_toml = ["pyproject.toml:tool.semantic_release.version"]
-version = "2.16.0"
+version = "2.17.0"
 tag_format = "v{version}"
 branch = "main"
 commit_message = "chore(release): {version} [skip ci]"

{tasktree_manager-2.16.0 → tasktree_manager-2.17.0}/tasktree_manager/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '2.16.0'
-__version_tuple__ = version_tuple = (2, 16, 0)
+__version__ = version = '2.17.0'
+__version_tuple__ = version_tuple = (2, 17, 0)
 
 __commit_id__ = commit_id = None

{tasktree_manager-2.16.0 → tasktree_manager-2.17.0}/tasktree_manager/app.py

@@ -366,6 +366,9 @@ class TaskTreeApp(App):
             (kb.get("delete_worktree", "D"), "delete_worktree", "Del WT"),
         ]
 
+        # Every key a configured action uses ("s,space" binds two keys)
+        claimed_keys = {key.strip() for keys in kb.values() for key in keys.split(",")}
+
         yield AppHeader()
         with Horizontal(id="main-container"):
             # Left column: Tasks (top) and Worktrees (bottom)
@@ -382,7 +385,7 @@ class TaskTreeApp(App):
                         id="task-list",
                         context_bindings=task_panel_bindings,
                         # A fold key bound to any action in config stays that action
-                        fold_keys=tuple(k for k in ("enter", "space") if k not in kb.values()),
+                        fold_keys=tuple(k for k in ("enter", "space") if k not in claimed_keys),
                     )
                 with Vertical(id="worktree-panel"):
                     with Horizontal(classes="panel-title-bar"):
@@ -1302,7 +1305,8 @@ class TaskTreeApp(App):
                 initial_base_branch=self.config.default_base_branch,
                 title=f"Clone Task: {self.current_task.name}",
                 epics=self._epic_choices(),
-                initial_epic=self._epic_of(self.current_task),
+                # A clone joins the source task's epic; a clone of an epic joins none
+                initial_epic=self.query_one("#task-list", TaskList).epic_of(self.current_task.name),
             ),
             handle_result,
         )
@@ -1432,7 +1436,7 @@ class TaskTreeApp(App):
                 return
             try:
                 self.task_manager.set_task_display_name(task, new_name)
-            except OSError as e:
+            except (OSError, ValueError) as e:
                 self.notify(escape(f"Rename failed: {e}"), severity="error")
                 return
             label = task.display_label
@@ -1452,6 +1456,7 @@ class TaskTreeApp(App):
             self.notify("Epics don't nest: an epic can't join another epic", severity="warning")
             return
         epics = [(label, name) for label, name in self._epic_choices() if name != task.name]
+        parent = self.query_one("#task-list", TaskList).epic_of(task.name)
 
         def handle_choice(choice: tuple[str, str | None] | None) -> None:
             if choice is None:
@@ -1469,8 +1474,8 @@ class TaskTreeApp(App):
             EpicPickerModal(
                 task.display_label,
                 epics,
-                self.query_one("#task-list", TaskList).epic_of(task.name),
-                task.epic_name is None,
+                parent,
+                parent is None,
             ),
             handle_choice,
         )
@@ -2084,7 +2089,9 @@ class TaskTreeApp(App):
         """
         fresh_task = self.task_manager.get_task(task.name)
         if fresh_task:
-            self.task_manager.ensure_claude_md_files(fresh_task)
+            problem = self.task_manager.ensure_claude_md_files(fresh_task)
+            if problem:
+                self.call_from_thread(self.notify, escape(problem), severity="warning")
             self.task_manager.ensure_worktree_settings(fresh_task)
         ensure_claude_hooks(task.path, self.config.claude_memory_dir)
 

{tasktree_manager-2.16.0 → tasktree_manager-2.17.0}/tasktree_manager/cli.py

@@ -8,17 +8,37 @@ errors on stderr, exit code 0 on success and 1 on failure.
 
 import argparse
 import json
+import os
+import re
 import shutil
 import sys
+from datetime import timezone
 from pathlib import Path
 
 from . import __version__
 from .services import forge
 from .services.config import Config, ConfigError
+from .services.epic_log import (
+    EPIC_ROLE,
+    FORMER_ROLE,
+    EpicLogEntry,
+    read_epic_log,
+    resolve_log_target,
+)
 from .services.git_ops import GitOps
-from .services.models import EPIC_KIND, TASK_KIND, ArchiveResult, Task
+from .services.models import (
+    EPIC_KIND,
+    TASK_KIND,
+    ArchiveResult,
+    Task,
+    parent_epic_name,
+    same_folder,
+)
 from .services.task_manager import ARCHIVE_NOTES_SHOWN, ArchiveIncompleteError, TaskManager
 
+# C0/C1 controls except tab; notes are split on newlines before this runs
+_CONTROL_CHARS = re.compile(r"[\x00-\x08\x0a-\x1f\x7f-\x9f]")
+
 
 def build_parser() -> argparse.ArgumentParser:
     """Build the argument parser for the headless CLI."""
@@ -78,6 +98,31 @@ def build_parser() -> argparse.ArgumentParser:
     epic_list.add_argument("--json", action="store_true", dest="as_json", help="Output JSON")
     epic_list.set_defaults(func=cmd_epic_list)
 
+    epic_note = epic_sub.add_parser("note", help="Add a note to this task's file in the epic log")
+    epic_note.add_argument("text", help='Note text ("-" reads it from stdin)')
+    epic_note.add_argument(
+        "--task", default=None, help="Task that writes the note (default: inferred from $PWD)"
+    )
+    epic_note.set_defaults(func=cmd_epic_note)
+
+    epic_log = epic_sub.add_parser(
+        "log", help="Show the notes and latest session recap of tasks in an epic"
+    )
+    epic_log.add_argument(
+        "task",
+        nargs="?",
+        default=None,
+        help="One task of the epic (default: the epic of $PWD and all its tasks)",
+    )
+    epic_log.add_argument("--json", action="store_true", dest="as_json", help="Output JSON")
+    epic_log.set_defaults(func=cmd_epic_log)
+
+    epic_sync = epic_sub.add_parser(
+        "sync", help="Refresh the epic block in the CLAUDE.md of epics and their tasks"
+    )
+    epic_sync.add_argument("name", nargs="?", default=None, help="Epic name (default: all)")
+    epic_sync.set_defaults(func=cmd_epic_sync)
+
     list_parser = sub.add_parser("list", help="List tasks with their repos and dirty state")
     list_parser.add_argument("--json", action="store_true", dest="as_json", help="Output JSON")
     list_parser.set_defaults(func=cmd_list)
@@ -334,6 +379,142 @@ def cmd_epic_list(manager: TaskManager, config: Config, args: argparse.Namespace
     return 0
 
 
+def cmd_epic_note(manager: TaskManager, config: Config, args: argparse.Namespace) -> int:
+    """Append a note to the task's file in its epic log.
+
+    Inside a task folder a session writes only its own notes; from outside
+    any task, `--task` writes and the heading records that.
+    """
+    caller = _find_task_by_cwd(manager)
+    source = None
+    if args.task:
+        task = manager.get_task(args.task)
+        if task is None:
+            return _error(f"no such task: {args.task}")
+        if caller is None:
+            source = "written outside the task folder"
+        elif not same_folder(caller.path, task.path):
+            return _error(f"inside task {caller.name}: notes go to its own file, not {task.name}")
+    elif caller is None:
+        return _error("not inside a task directory; pass --task")
+    else:
+        task = caller
+    text = sys.stdin.read() if args.text == "-" else args.text
+    path = manager.append_epic_note(task, text, source=source)
+    print(f"Noted in {path}")
+    return 0
+
+
+def cmd_epic_log(manager: TaskManager, config: Config, args: argparse.Namespace) -> int:
+    """Show notes and the latest session recap of one task or a whole epic."""
+    epic, only = resolve_log_target(manager, _find_task_by_cwd(manager), args.task)
+    entries = read_epic_log(manager, epic, only)
+    for entry in entries:
+        if entry.problem:
+            print(f"warning: {entry.task}: {entry.problem}", file=sys.stderr)
+    if args.as_json:
+        print(json.dumps([_epic_log_json(entry) for entry in entries], indent=2))
+        return 0
+    for index, entry in enumerate(entries):
+        if index:
+            print()
+        _print_epic_log_entry(entry)
+    return 0
+
+
+def _epic_log_json(entry: EpicLogEntry) -> dict:
+    session = None
+    if entry.session is not None:
+        recap = entry.recap
+        session = {
+            "id": entry.session.session_id,
+            "cwd": str(entry.session.cwd),
+            "title": recap.title if recap else None,
+            "finished_at": recap.finished_at.isoformat() if recap and recap.finished_at else None,
+            "summary": recap.summary if recap else None,
+            # The typed prompt only stands in for a missing recap, as in the TUI
+            "last_prompt": recap.last_prompt if recap and not recap.summary else None,
+        }
+    return {
+        "task": entry.task,
+        "role": entry.role,
+        "notes_path": str(entry.notes_path),
+        "notes": entry.notes,
+        "notes_truncated": entry.notes_truncated,
+        "session": session,
+        "problem": entry.problem,
+    }
+
+
+def _print_epic_log_entry(entry: EpicLogEntry) -> None:
+    role = {EPIC_ROLE: " (epic)", FORMER_ROLE: " (no longer in the epic)"}.get(entry.role, "")
+    print(f"== {entry.task}{role} ==")
+    recap = entry.recap
+    if entry.role == FORMER_ROLE:
+        pass
+    elif recap is None:
+        print("Last session: none recorded")
+    else:
+        when = "time unknown"
+        if recap.finished_at:
+            when = recap.finished_at.astimezone(timezone.utc).strftime("%Y-%m-%d %H:%M UTC")
+        print(f"Last session: {recap.title} ({when})")
+        if recap.summary:
+            print(f"  Recap: {recap.summary}")
+        elif recap.last_prompt:
+            print(f"  Last prompt: {recap.last_prompt}")
+    if not entry.notes:
+        print("Notes: none yet")
+        return
+    cut = ", older notes cut" if entry.notes_truncated else ""
+    print(f"Notes ({entry.notes_path}{cut}):")
+    # Indented, so a note cannot forge a "== task ==" line; controls dropped
+    for line in _safe_lines(entry.notes.rstrip()):
+        print(f"  {line}" if line else "")
+
+
+def _safe_lines(text: str) -> list[str]:
+    return [_CONTROL_CHARS.sub("", line) for line in text.split("\n")]
+
+
+def cmd_epic_sync(manager: TaskManager, config: Config, args: argparse.Namespace) -> int:
+    """Refresh the CLAUDE.md epic block of epics and their tasks."""
+    if args.name:
+        epic = manager.get_task(args.name)
+        if epic is None:
+            return _error(f"no such epic: {args.name}")
+        if manager.epic_of(epic) != epic.name:
+            return _error(f"{epic.name} is not an epic")
+        epics = [epic.name]
+    else:
+        epics = [task.name for task in manager.list_tasks() if manager.epic_of(task) == task.name]
+    synced = missing = failed = 0
+    for name in epics:
+        for member in [name, *manager.epic_child_names(name)]:
+            try:
+                task = manager.get_task(member)
+            except (OSError, ValueError) as e:
+                print(f"warning: {member}: {e}", file=sys.stderr)
+                failed += 1
+                continue
+            if task is None:
+                continue
+            if not (task.path / "CLAUDE.md").is_file():
+                missing += 1
+                continue
+            problem = manager.sync_epic_block(task)
+            if problem:
+                print(f"warning: {problem}", file=sys.stderr)
+                failed += 1
+            else:
+                synced += 1
+    print(
+        f"Synced {synced} folder(s); {missing} without CLAUDE.md "
+        f"(written when a Claude session starts there from the TUI); {failed} failed"
+    )
+    return 1 if failed else 0
+
+
 def _refuse_epic_with_children(manager: TaskManager, task: Task, verb: str) -> bool:
     """Print an error and return True if `task` is an epic that still has tasks.
 
@@ -354,6 +535,8 @@ def _refuse_epic_with_children(manager: TaskManager, task: Task, verb: str) -> b
 def cmd_list(manager: TaskManager, config: Config, args: argparse.Namespace) -> int:
     """List tasks with their repos and dirty state."""
     tasks = manager.list_tasks()
+    # One TASKS_DIR listing for every parent_epic_name lookup below
+    listing = set(os.listdir(config.tasks_dir)) if config.tasks_dir.is_dir() else set()
     dirty: dict[str, bool] = {}
     errored: dict[str, bool] = {}
     for task in tasks:
@@ -369,7 +552,7 @@ def cmd_list(manager: TaskManager, config: Config, args: argparse.Namespace) ->
                 "name": task.name,
                 "display_name": task.display_name,
                 "kind": task.kind,
-                "epic": task.epic_name,
+                "epic": parent_epic_name(task, listing),
                 "path": str(task.path),
                 "repos": [wt.name for wt in task.worktrees],
                 "dirty": dirty[task.name],
@@ -542,7 +725,8 @@ def cmd_add_repo(manager: TaskManager, config: Config, args: argparse.Namespace)
 def _find_task_by_cwd(manager: TaskManager) -> Task | None:
     """Find the task whose directory contains the current working directory."""
     cwd = Path.cwd().resolve()
-    for task in manager.list_tasks():
+    # A symlink alias resolves to the same folder: the real folder wins
+    for task in sorted(manager.list_tasks(), key=lambda task: task.path.is_symlink()):
         task_path = task.path.resolve()
         if cwd == task_path or cwd.is_relative_to(task_path):
             return task
@@ -635,7 +819,7 @@ def cmd_status(manager: TaskManager, config: Config, args: argparse.Namespace) -
         payload = {
             "task": task.name,
             "kind": task.kind,
-            "epic": task.epic_name,
+            "epic": parent_epic_name(task),
             "path": str(task.path),
             "claude": claude,
             "worktrees": [

{tasktree_manager-2.16.0 → tasktree_manager-2.17.0}/tasktree_manager/services/claude_sessions.py

@@ -14,6 +14,7 @@ costs one bounded read regardless of its length.
 import json
 import os
 import re
+from collections.abc import Iterable
 from dataclasses import dataclass
 from datetime import datetime, tzinfo
 from pathlib import Path
@@ -23,6 +24,8 @@ from .claude_hooks import project_dir_candidates
 RECAP_SUFFIX = "(disable recaps in /config)"
 TAIL_WINDOW = 1 << 20
 TAIL_WINDOW_RETRY = 4 << 20
+# Most a session-folder lookup reads from the start of a transcript
+HEAD_BUDGET = 16 << 20
 # Turns that span a laptop sleep report days of "duration"; anything above
 # an hour is noise rather than work time
 DURATION_CAP_MS = 3_600_000
@@ -56,13 +59,22 @@ class ClaudeRecap:
     last_prompt: str | None
 
 
-def transcript_key(folder: Path) -> tuple[Path, int, int] | None:
-    """Return ``(path, mtime_ns, size)`` of the newest transcript for a folder.
+@dataclass(frozen=True)
+class SessionRef:
+    """A transcript and the folder its session was started in."""
 
-    One ``scandir`` per candidate project dir and no file reads, so callers
-    can poll it to detect changes cheaply.
-    """
-    newest: tuple[int, int, Path] | None = None
+    path: Path
+    cwd: Path
+    mtime_ns: int
+
+    @property
+    def session_id(self) -> str:
+        return self.path.stem
+
+
+def _transcripts(folder: Path) -> list[tuple[int, int, Path]]:
+    """``(mtime_ns, size, path)`` of every transcript in a folder's project dirs."""
+    found = []
     for project_dir in project_dir_candidates(folder):
         try:
             entries = list(os.scandir(project_dir))
@@ -77,15 +89,76 @@ def transcript_key(folder: Path) -> tuple[Path, int, int] | None:
                 # Claude prunes old transcripts at startup; one can vanish
                 # between the scandir and the stat
                 continue
-            candidate = (stat.st_mtime_ns, stat.st_size, Path(entry.path))
-            if newest is None or candidate[0] > newest[0]:
-                newest = candidate
+            found.append((stat.st_mtime_ns, stat.st_size, Path(entry.path)))
+    return found
+
+
+def transcript_key(folder: Path) -> tuple[Path, int, int] | None:
+    """Return ``(path, mtime_ns, size)`` of the newest transcript for a folder.
+
+    One ``scandir`` per candidate project dir and no file reads, so callers
+    can poll it to detect changes cheaply.
+    """
+    newest = max(_transcripts(folder), key=lambda found: found[0], default=None)
     if newest is None:
         return None
     mtime_ns, size, path = newest
     return path, mtime_ns, size
 
 
+def transcript_cwd(path: Path) -> Path | None:
+    """The folder a session started in: the first ``cwd`` in its transcript.
+
+    Whole records are read, since ``cwd`` follows the message body; a first
+    prompt bigger than HEAD_BUDGET leaves the cwd unknown.
+    """
+    try:
+        with open(path, "rb") as f:
+            budget = HEAD_BUDGET
+            while budget > 0:
+                line = f.readline(budget)
+                if not line:
+                    return None
+                budget -= len(line)
+                if b'"cwd"' not in line:
+                    continue
+                try:
+                    record = json.loads(line)
+                except ValueError:
+                    continue
+                cwd = record.get("cwd") if isinstance(record, dict) else None
+                if isinstance(cwd, str) and cwd:
+                    return Path(cwd)
+    except OSError:
+        return None
+    return None
+
+
+def latest_session(folders: Iterable[Path]) -> SessionRef | None:
+    """The newest session started in one of `folders` (a task and its worktrees).
+
+    Project dir names fold every non-alphanumeric character, so `X/1` and `X-1`
+    share one dir; a transcript counts only when its recorded cwd is the folder.
+    """
+    candidates = [
+        (mtime_ns, str(path), path, folder)
+        for folder in folders
+        for mtime_ns, _size, path in _transcripts(folder)
+    ]
+    for mtime_ns, _key, path, folder in sorted(candidates, reverse=True):
+        cwd = transcript_cwd(path)
+        if cwd is not None and _same_dir(cwd, folder):
+            return SessionRef(path=path, cwd=folder, mtime_ns=mtime_ns)
+    return None
+
+
+def _same_dir(a: Path, b: Path) -> bool:
+    try:
+        return os.path.samefile(a, b)
+    except OSError:
+        return os.path.realpath(a) == os.path.realpath(b)
+
+
 def read_claude_recap(path: Path) -> ClaudeRecap | None:
     """Read the recap from one transcript (see ``transcript_key`` to pick it)."""
     try: