tasktree-manager 2.16.1__tar.gz → 2.18.0__tar.gz

{tasktree_manager-2.16.1 → tasktree_manager-2.18.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.18.0] - 2026-10-20
+
+### Added
+- **epic**: Ask another task's session with epic ask (#14)
+
+
+## [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

{tasktree_manager-2.16.1 → tasktree_manager-2.18.0}/PKG-INFO

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

{tasktree_manager-2.16.1 → tasktree_manager-2.18.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 and `epic ask` so the Claude sessions of one epic share what they know
 - 📦 **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,15 +100,34 @@ 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 ask DIC-2862-pcaps-s3 "which bucket?"    # a read-only copy of that task's latest session answers
+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.
+`epic ask TASK "question"` resumes a copy of that task's latest Claude session to answer:
+forked and not saved, hooks off, only the Read/Grep/Glob tools, no MCP servers, so the
+task's own session and status stay untouched; credential files (`~/.ssh`, `~/.aws`, `.env`
+and similar) are denied to it. It exits 3 without asking when the task's session is
+running; the calling session then messages it with SendMessage (`--fork` asks a copy
+anyway). Each turn of the copy is a model call on that session's context, at most
+`--max-turns` (default 8); `--model sonnet` makes it cheaper.
+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`.
 
-Exit code is 0 on success, 1 on failure with the reason on stderr. `delete` and `finish` run
+Exit code is 0 on success, 1 on failure with the reason on stderr, and 3 from `epic ask`
+when the task's session is running (its name goes to stdout). `delete` and `finish` run
 the same safety check as the TUI (uncommitted, unpushed, or unmerged work blocks deletion);
 with `glab`/`gh` installed, squash/rebase-merged branches are recognized as merged. If the
 diff cannot be archived for any repo, the CLI stops before deleting and prints the path of

{tasktree_manager-2.16.1 → tasktree_manager-2.18.0}/docs/user-guide.md

@@ -89,7 +89,31 @@ 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.
+- When the log does not answer a question, a session runs
+  `tasktree-manager epic ask TASK "question"`. A read-only copy of that task's latest
+  Claude session answers: it can read files but not change them or read credential
+  files, and nothing is saved in that task. If the task's session is running, the command exits
+  with code 3 and prints the session name, and the asking session sends it a message
+  with SendMessage instead (`--fork` asks a copy anyway). Only tasks of the same epic
+  and the epic folder can be asked, and a session in a task outside any epic cannot
+  ask. Each turn of the copy is a model call on the size of that session's context,
+  at most `--max-turns` (default 8); `--model sonnet` makes it cheaper.
+- 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/ask/sync`.
 
 ### Worktrees
 

{tasktree_manager-2.16.1 → tasktree_manager-2.18.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.1"
+version = "2.18.0"
 tag_format = "v{version}"
 branch = "main"
 commit_message = "chore(release): {version} [skip ci]"

{tasktree_manager-2.16.1 → tasktree_manager-2.18.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.1'
-__version_tuple__ = version_tuple = (2, 16, 1)
+__version__ = version = '2.18.0'
+__version_tuple__ = version_tuple = (2, 18, 0)
 
 __commit_id__ = commit_id = None

{tasktree_manager-2.16.1 → tasktree_manager-2.18.0}/tasktree_manager/cli.py

@@ -3,23 +3,58 @@
 Running ``tasktree-manager`` with no arguments starts the TUI; any argument
 routes here instead. Built for scripts and automation (e.g. Claude skills
 that create a task and then work in its worktrees): plain text on stdout,
-errors on stderr, exit code 0 on success and 1 on failure.
+errors on stderr, exit code 0 on success and 1 on failure (`epic ask` also uses 3:
+the task's session is running, message it instead).
 """
 
 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.agent_sessions import AgentSession, list_agent_sessions
 from .services.config import Config, ConfigError
+from .services.epic_ask import (
+    ASK_MAX_TURNS,
+    ASK_QUESTION_MAX_BYTES,
+    ASK_TIMEOUT,
+    ASK_TIMEOUT_MAX,
+    LOOP_GUARD_ENV,
+    AskError,
+    AskTarget,
+    build_ask_command,
+    live_sessions,
+    pick_session,
+    resolve_ask_task,
+    run_ask,
+)
+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, parent_epic_name
+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."""
@@ -79,6 +114,58 @@ 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_ask = epic_sub.add_parser(
+        "ask", help="Ask another task of the epic: a read-only copy of its latest session answers"
+    )
+    epic_ask.add_argument("task", help="Task (or the epic) to ask")
+    epic_ask.add_argument("question", help='Question ("-" reads it from stdin)')
+    epic_ask.add_argument("--session", default=None, help="Session id to ask (default: the newest)")
+    epic_ask.add_argument(
+        "--fork",
+        action="store_true",
+        help="Ask a copy even when the task's session is running (default: exit 3)",
+    )
+    epic_ask.add_argument("--model", default=None, help="Model for the answer (default: Claude's)")
+    epic_ask.add_argument(
+        "--timeout",
+        type=_ask_timeout,
+        default=ASK_TIMEOUT,
+        help=f"Seconds to wait for the answer (default {ASK_TIMEOUT})",
+    )
+    epic_ask.add_argument(
+        "--max-turns",
+        type=_ask_max_turns,
+        default=ASK_MAX_TURNS,
+        help=f"Turns the copy may take; each is a model call (default {ASK_MAX_TURNS})",
+    )
+    epic_ask.add_argument("--json", action="store_true", dest="as_json", help="Output JSON")
+    epic_ask.set_defaults(func=cmd_epic_ask)
+
+    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)
@@ -335,6 +422,241 @@ 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_ask(manager: TaskManager, config: Config, args: argparse.Namespace) -> int:
+    """Ask another task of the epic; exit 3 when its session is running.
+
+    A running session is asked with SendMessage by the calling agent: only
+    a fork is asked here, unless --fork.
+    """
+    if os.environ.get(LOOP_GUARD_ENV):
+        return _error("epic ask cannot run inside another epic ask")
+    question = (sys.stdin.read() if args.question == "-" else args.question).strip()
+    if not question:
+        return _error("the question is empty")
+    size = len(question.encode())
+    if size > ASK_QUESTION_MAX_BYTES:
+        return _error(f"the question is {size} bytes; the limit is {ASK_QUESTION_MAX_BYTES}")
+    caller = _find_task_by_cwd(manager)
+    epic, task = resolve_ask_task(manager, caller, args.task)
+
+    # Before the session lookup: a running session may not have a transcript yet
+    if not args.fork:
+        sessions = list_agent_sessions(config.claude_path)
+        if sessions is None:
+            print("warning: could not list running Claude sessions", file=sys.stderr)
+        live = live_sessions(task, sessions or [])
+        if live:
+            _print_live_sessions(task, live, args.as_json)
+            return 3
+
+    target = AskTarget(epic=epic, task=task, session=pick_session(task, args.session))
+    command = build_ask_command(
+        config.claude_path,
+        target,
+        question,
+        caller.name if caller else None,
+        args.model,
+        args.max_turns,
+    )
+    try:
+        answer = run_ask(command, target.session.cwd, args.timeout)
+    except AskError as e:
+        return _error(_CONTROL_CHARS.sub(" ", f"{task.name} did not answer: {e}"))
+    if args.as_json:
+        payload = {
+            "task": task.name,
+            "status": "answered",
+            "session_id": target.session.session_id,
+            "cwd": str(target.session.cwd),
+            "answer": answer.text,
+            "usage": answer.usage,
+        }
+        print(json.dumps(payload, indent=2))
+        return 0
+    print(f"== {task.name} (copy of session {target.session.session_id}) ==")
+    for line in _safe_lines(answer.text.rstrip()):
+        print(line)
+    return 0
+
+
+def _print_live_sessions(task: Task, live: list[AgentSession], as_json: bool) -> None:
+    if as_json:
+        rows = [
+            {
+                "name": s.name,
+                "session_id": s.session_id,
+                "status": s.status,
+                "cwd": str(s.directory),
+            }
+            for s in live
+        ]
+        print(json.dumps({"task": task.name, "status": "running", "sessions": rows}, indent=2))
+        return
+    # SendMessage addresses a session by name; an unnamed one only by its id
+    names = ", ".join(
+        f'"{_CONTROL_CHARS.sub("", s.name or s.session_id)}" ({s.status})' for s in live
+    )
+    print(f"{task.name} has a running Claude session: {names}.")
+    print("Message it with SendMessage (to: that name); the answer arrives later as a message.")
+    print("If the message is held or refused, pass --fork to ask a read-only copy instead.")
+
+
+def _ask_timeout(value: str) -> float:
+    try:
+        seconds = float(value)
+    except ValueError:
+        seconds = float("nan")
+    if not 1 <= seconds <= ASK_TIMEOUT_MAX:
+        raise argparse.ArgumentTypeError(f"must be between 1 and {ASK_TIMEOUT_MAX} seconds")
+    return seconds
+
+
+def _ask_max_turns(value: str) -> int:
+    try:
+        turns = int(value)
+    except ValueError:
+        turns = 0
+    if not 1 <= turns <= 50:
+        raise argparse.ArgumentTypeError("must be between 1 and 50")
+    return turns
+
+
+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.
 
@@ -545,7 +867,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

{tasktree_manager-2.16.1 → tasktree_manager-2.18.0}/tasktree_manager/services/agent_sessions.py

@@ -43,6 +43,9 @@ _STATUS_MAP = {
 # When several sessions run in one worktree, the most urgent state wins
 _STATUS_PRECEDENCE = {"needs_input": 0, "working": 1, "ready": 2}
 
+# Name of the read-only copies `epic ask` runs: not work, so never listed
+ASK_COPY_PREFIX = "epic-ask-"
+
 _DIRECTORY_KEYS = ("cwd", "directory", "workdir", "projectPath", "path")
 _STATUS_KEYS = ("status", "state")
 
@@ -110,6 +113,9 @@ def parse_agent_sessions(payload: str) -> list[AgentSession] | None:
         # unknown statuses (dead/exited sessions) must not render as working
         if not directory or raw_status is None:
             continue
+        name = str(record.get("name", ""))
+        if name.startswith(ASK_COPY_PREFIX):
+            continue
         status = _STATUS_MAP.get(raw_status.lower())
         if status is None:
             continue
@@ -118,7 +124,7 @@ def parse_agent_sessions(payload: str) -> list[AgentSession] | None:
                 directory=Path(directory).resolve(),
                 status=status,
                 session_id=str(record.get("sessionId", "")),
-                name=str(record.get("name", "")),
+                name=name,
             )
         )
     return sessions

{tasktree_manager-2.16.1 → tasktree_manager-2.18.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,88 @@ 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 find_session(folders: Iterable[Path], session_id: str) -> SessionRef | None:
+    """The session `session_id` if it was started in one of `folders`."""
+    for folder in folders:
+        for mtime_ns, _size, path in _transcripts(folder):
+            if path.stem != session_id:
+                continue
+            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: