DazzleML
diff --git a/‎CHANGELOG.md‎
Lines changed: 10 additions & 2 deletions b/‎CHANGELOG.md‎
Lines changed: 10 additions & 2 deletions
diff --git a/‎claude_session_backup/cli.py‎
Lines changed: 8 additions & 1 deletion b/‎claude_session_backup/cli.py‎
Lines changed: 8 additions & 1 deletion
diff --git a/‎claude_session_backup/commands.py‎
Lines changed: 75 additions & 6 deletions b/‎claude_session_backup/commands.py‎
Lines changed: 75 additions & 6 deletions
@@ -9,10 +9,16 @@ Status: **prealpha**. Until the first alpha release, breaking changes may land b
 
 ## [Unreleased]
 
+## [0.2.3] -- 2026-05-06 (prealpha)
+
+Closes the v0.2.3 epic bundle: pathkit `start at` semantics (#19), folder-usage long tail with `--top N` / `--all-folders` (#21), `display_top_folders` config (#21 follow-up), `csb scan` term-vs-folder disambiguation with `-d` / `-D` / `-s` flags (#20), pathkit multi-candidate slug disambiguation (#23), and `csb resume` cd + Windows TTY-handoff fix (#24). The release is grounded in a senior-eng upstream-source audit (#25, closed) that ruled out the file-relocation hypothesis and confirmed the slug encoder behavior. 226/226 tests pass.
+
 ### Fixed
 - **`csb list` / `csb scan` "start at" line now reports the cwd that lets `claude --resume` find the session** -- previously derived from a JSONL `cwd` histogram (most-common cwd across all events), which silently misled users when Claude Code was launched from a parent dir and `cd`-ed into a subdir afterwards. Now derived from the project-dir slug (`~/.claude/projects/<slug>/`) via filesystem-validated reverse decoding in the new `claude_session_backup/pathkit.py` module. Mirrors the upstream encoder at `claude-code/utils/sessionStoragePortable.ts:311-319` (`replace(/[^a-zA-Z0-9]/g, '-')`); the inverse uses `os.listdir` per directory level and the longest-encoded-entry-first heuristic to disambiguate slugs that have multiple valid filesystem decodings (e.g., a folder literally named `New--Project` vs. `New\.Project`). Returns the sentinel `<unresolved:slug>` when no candidate decodes (e.g., the original cwd has been deleted) so maintainers can still see the slug. Closes #19. (#19, prealpha-blocker)
 - **Indexer no longer truncates folder usage to top-N; `csb list --top N` / `--all-folders` reveal the long tail** -- `metadata.py` previously kept only `1 + top_n_folders` rows in the SQLite `folder_usage` table at index time, which made the long tail of cwds invisible regardless of any renderer flag. The slug-decoded "start at" cwd was a frequent casualty (e.g., AMD_INTIGRITI's `C:\` ranked 5th by JSONL count and got dropped), surfacing as a missing `(Nx)` count next to the "start at" line. The indexer now persists every distinct cwd from the JSONL events; the renderer truncates at display time using the new flags. Closes #21.
 - **`csb scan` no longer auto-resolves the positional argument as a path against cwd** -- previously, `csb scan amdead` silently treated `amdead` as `<cwd>\amdead` even when the user meant a metadata-search term. The bare positional now means "filter sessions whose name, project, or folder paths contain this term"; explicit path-strict mode is reached via the new `-d` / `-D` flags. Closes #20.
+- **`csb resume` now actually launches claude in the correct cwd, with working stdin** -- previously `cmd_resume` printed `cd <start_folder>` as informational text and then called `os.execvp("claude", ...)` from the user's terminal cwd, which made `claude --resume <uuid>` fail with "No conversation found" whenever the user wasn't already in the right directory. The fix has two layers and an implementation note: (a) target is derived from `pathkit.derive_start_at(jsonl_path)` -- the slug-decoded path is the only cwd whose slug matches the JSONL's parent directory, per the upstream-source audit -- with fallback to `start_folder` for legacy session rows that lack `jsonl_path`; (b) the launch uses `subprocess.run(["claude", "--resume", uuid], cwd=target)` rather than `os.chdir + os.execvp`. The subprocess approach is required on Windows because Python's `os.execvp` there is `_spawnv(P_OVERLAY, ...)` -- the parent process exits and a child spawns, but the controlling-TTY relationship doesn't transfer cleanly (claude TUI renders to stdout but stdin keystrokes go into the void). `subprocess.run` inherits the parent's stdin/stdout/stderr handles, so the TUI works correctly. The python parent process stays alive (~30MB) while claude runs and propagates claude's exit code. `FileNotFoundError` from `subprocess.run` disambiguates between "target folder deleted" and "`claude` not in PATH" via `os.path.isdir(target)`. Closes #24.
+- **Pathkit slug decoding now disambiguates ambiguous on-disk decodings via JSONL signals** -- when the slug `C--code-New--Project` happens to decode to two real folders (e.g., a literal `New--Project` AND a `New\.Project` sibling), `pathkit.decode_project_slug(slug, first_cwd, folder_usage)` picks the correct one via three-tier fallback: Tier 1 if `first_cwd` matches a candidate exactly or as a prefix-with-separator; Tier 2 if the JSONL's `folder_usage` histogram weights one candidate higher; Tier 3 (encoded-length heuristic) when neither signal matches -- preserving #19's behavior for callers without JSONL access. Path comparisons use case+separator+trailing-slash normalization (stdlib `os.path.normcase`/`normpath`) so Windows variants (`C:\Code\...` vs `c:/code/.../`) compare equal. The `derive_start_at(jsonl_path, first_cwd, folder_usage)` signature mirrors this, and `timeline._resolve_start_at` threads the signals from the existing session dict (no new indexer fields needed). Closes #23.
 
 ### Added
 - **`csb list --top N` and `csb list --all-folders` (also on `csb scan`)** -- control how many "other" folder rows display beneath the "start at" line. `--top N` shows the top N most-used cwds; `--all-folders` shows everything. Default unchanged (top 3). Mutually exclusive flags. Acceptance criteria from #21 are met. (#21)
@@ -21,10 +27,11 @@ Status: **prealpha**. Until the first alpha release, breaking changes may land b
 - **`csb scan -D PATTERN` / `--directory-only`** -- like `-d` but excludes descendants (only this folder, no subdirectories). With wildcard `-D amdead*`, matches sibling basenames at the same directory level only. Mutually exclusive with `-d`. (#20)
 - **`csb scan -s PATTERN` / `--start-dir-only`** -- path-strict on `start_folder` only; skips `folder_usage` entirely. Answers "what sessions originated here?" -- useful in a directory to ask "is there anything I can resume that started in this folder?" Trailing `*` for sibling-prefix expansion. Mutually exclusive with `-d` / `-D`. (#20)
 - **`csb scan <term>` (positional)** -- broad metadata substring search across session name, project, start_folder, and top-N folder_usage paths. Same vocabulary as `csb list <filter>` but with top-N gating to keep results coherent with what the renderer displays. Combinable with `-d` / `-D` / `-s` for "scope-then-filter" semantics. Emits an `[info]` hint to stderr if the term coincides with a cwd subfolder, suggesting `-d <term>` for path-strict search. (#20)
-- **`./dirname` and `.\dirname` shortcut** -- when the positional starts with `./` or `.\` (the conventional shell indicator for a relative path), it's auto-promoted to `-d <dirname>` path-strict mode. So `csb scan ./amdead` is equivalent to `csb scan -d amdead`, no flag-name to remember. Bare `csb scan .` is also promoted (equivalent to `csb scan -d .`). Suppressed if the user already passed `-d` or `-D` explicitly. (#20)
+- **`./dirname` and `.\dirname` shortcut** -- when the positional starts with `./` or `.\` (the conventional shell indicator for a relative path), it's auto-promoted to `-d <dirname>` path-strict mode. So `csb scan ./amdead` is equivalent to `csb scan -d amdead`, no flag-name to remember. Bare `csb scan .` is also promoted (equivalent to `csb scan -d .`). Suppressed if the user already passed `-d` or `-D` explicitly. The shortcut also composes with a term filter: `csb scan ./amdead my-paper` parses as two positionals and is equivalent to `csb scan -d amdead my-paper`. A bare two-positional form without the dot-prefix (`csb scan amdead my-paper`) is rejected with a clear error suggesting the explicit `-d` form. (#20)
 - **`csb scan` info / warning hints (stderr-routed)** -- `[info]` when a term coincides with a cwd subfolder; `[warning]` when `-d <pattern>` resolves to a path that doesn't exist (with graceful fallback to broad-term search if a term was provided). Stderr routing keeps `--json` stdout clean for tooling consumers. (#20)
 - **`find_sessions_by_directory` and `find_sessions_by_term` SQL helpers** in `claude_session_backup/index.py` with SQLite window-function-based top-N gating (`ROW_NUMBER() OVER (PARTITION BY session_id ORDER BY usage_count DESC)`). Uses `ESCAPE '|'` clause for safe LIKE-pattern composition with user-supplied paths containing `%` / `_`. Requires SQLite >= 3.25 (2018; modern Python ships 3.31+). (#20)
 - **73 new tests** -- 25 in `test_index.py` (window-function correctness, top-N gating, escape semantics, deleted-session exclusion, `start_folder_only=True` branch); 27 in `test_cli.py` covering all forms of the new scan grammar + mutex enforcement (including `-s` short/long, `-s/-d` and `-s/-D` mutex); 21 in `test_commands.py` for `_resolve_directory_pattern` (relative + absolute paths, wildcard variants, special character escaping) and `_maybe_promote_dot_prefix` (./ and .\ shortcut auto-promotion). Total: 192/192 pass.
+- **34 new tests for #23 + #24 + 2-positional fix** -- 20 in `test_pathkit.py` (`_collect_candidates` returns ALL on-disk decodings; `_disambiguate` Tier 1 / Tier 2 / Tier 3 fallback chain; path-comparison normalization for case + separator + trailing-slash; backward-compat signature for `decode_project_slug` and `derive_start_at` accepting the new `first_cwd` / `folder_usage` kwargs); 9 in `test_commands.py` for `cmd_resume` covering subprocess.run launch with `cwd=target`, returncode propagation, missing-target FileNotFoundError vs missing-claude FileNotFoundError disambiguation, session-not-found, Layer 2 slug-decoded path preference, and fallback to `start_folder` on `<unresolved:>` sentinel or missing `jsonl_path`; 1 in `test_commands.py` for `cmd_scan`'s 2-positional rejection without dot-prefix; 4 in `test_cli.py` for the new `term2` parser positional (dot-prefix + term combo, single-positional case, three-positional rejection, etc.). Total: 226/226 pass.
 
 ### Changed
 - **`extract_metadata` no longer accepts `top_n_folders`** -- the indexer always stores all rows. Callers updated. Removed the `top_n_folders` config key (was dead config now that the indexer is single-policy).
@@ -63,7 +70,8 @@ First release with the repository public. Focus: make the install path work toda
 
 First public release. `csb list --sort`, `csb scan` with folder-usage search, cross-platform Claude Code plugin with Node.js bootstrapper, two-commit backup model, timeline view with purge countdown, session resume and restore. 73/73 tests pass. See the [v0.2.0 release notes](https://github.com/DazzleML/Claude-Session-Backup/releases/tag/v0.2.0) for the full highlight list.
 
-[Unreleased]: https://github.com/DazzleML/Claude-Session-Backup/compare/v0.2.2...HEAD
+[Unreleased]: https://github.com/DazzleML/Claude-Session-Backup/compare/v0.2.3...HEAD
+[0.2.3]: https://github.com/DazzleML/Claude-Session-Backup/compare/v0.2.2...v0.2.3
 [0.2.2]: https://github.com/DazzleML/Claude-Session-Backup/compare/v0.2.1...v0.2.2
 [0.2.1]: https://github.com/DazzleML/Claude-Session-Backup/compare/v0.2.0...v0.2.1
 [0.2.0]: https://github.com/DazzleML/Claude-Session-Backup/releases/tag/v0.2.0
@@ -200,7 +200,14 @@ def build_parser():
     _add_common_flags(p_scan)
     p_scan.add_argument(
         "term", nargs="?", default=None,
-        help="Filter sessions whose name, project, or folder paths contain term (case-insensitive)",
+        help="Filter sessions whose name, project, or folder paths contain term (case-insensitive). "
+             "If this starts with `./` or `.\\` (or is a bare `.`), it's auto-promoted to implicit -d.",
+    )
+    p_scan.add_argument(
+        "term2", nargs="?", default=None,
+        help="Optional second positional. Only valid when the first positional is a "
+             "`./dirname` / `.\\dirname` shortcut -- in that case `term2` is the actual term "
+             "filter (equivalent to `csb scan -d dirname term2`). Otherwise rejected.",
     )
     p_scan.add_argument("-n", type=int, default=20, help="Number of sessions to show")
     p_scan.add_argument(
 
@@ -433,6 +433,8 @@ def cmd_config(args) -> int:
 
 def cmd_resume(args) -> int:
     """Launch claude --resume with the full session UUID."""
+    from .pathkit import derive_start_at
+
     config = _get_config(args)
     conn = open_db(config["index_path"])
     init_schema(conn)
@@ -445,23 +447,68 @@ def cmd_resume(args) -> int:
         return 1
 
     full_id = session["session_id"]
-    start_folder = session.get("start_folder")
     name = session.get("session_name") or "(unnamed)"
 
+    # Resolve cd target via pathkit (slug-decoded path = the only cwd whose
+    # slug matches the JSONL's parent directory; per the upstream-source audit,
+    # that's the only cwd from which `claude --resume <uuid>` will find the
+    # file). Falls back to start_folder for sessions without a jsonl_path
+    # (e.g., legacy index rows pre-#19).
+    target = None
+    jsonl_path = session.get("jsonl_path")
+    if jsonl_path:
+        first_cwd = session.get("start_folder")
+        folders = session.get("folders") or []
+        folder_usage = {f["folder_path"]: f.get("usage_count", 0) for f in folders}
+        decoded = derive_start_at(jsonl_path, first_cwd=first_cwd, folder_usage=folder_usage)
+        if decoded and not decoded.startswith("<"):
+            target = decoded
+    if target is None:
+        target = session.get("start_folder")
+
     print(f"Resuming: {name}")
     print(f"  ID: {full_id}")
-    if start_folder:
-        print(f"  cd {start_folder}")
+    if target:
+        print(f"  cd {target}")
     print(f"  claude --resume {full_id}")
     print()
 
-    # Execute claude --resume (replaces this process)
+    # Launch claude --resume as a child process. We use subprocess.run with
+    # cwd=target rather than os.chdir + os.execvp because Python's os.execvp
+    # on Windows is _spawnv(P_OVERLAY, ...) -- the parent process exits and
+    # spawns a child, but the controlling-TTY relationship doesn't transfer
+    # cleanly. Symptom: claude TUI renders to stdout but stdin keystrokes
+    # don't reach claude (they go into the void). subprocess.run inherits
+    # the parent's stdin/stdout/stderr handles, which are still attached to
+    # the user's terminal, so the TUI works correctly.
+    #
+    # Trade-off: the python process stays alive in memory while claude
+    # runs (~30MB cost). When claude exits, its return code propagates.
+    import subprocess
     try:
-        os.execvp("claude", ["claude", "--resume", full_id])
-    except FileNotFoundError:
+        result = subprocess.run(
+            ["claude", "--resume", full_id],
+            cwd=target if target else None,
+            check=False,
+        )
+        return result.returncode
+    except FileNotFoundError as e:
+        # FileNotFoundError can fire from two places:
+        #   (a) the cwd= path doesn't exist (target folder deleted)
+        #   (b) the `claude` binary isn't in PATH
+        # Disambiguate by checking whether the target itself is the issue.
+        if target and not os.path.isdir(target):
+            print(f"Error: cannot cd to {target}: {e}", file=sys.stderr)
+            print("The folder may have been deleted. Run manually:", file=sys.stderr)
+            print(f"  cd <correct-folder> && claude --resume {full_id}", file=sys.stderr)
+            return 1
         print("Error: 'claude' command not found in PATH.", file=sys.stderr)
         print(f"Run manually: claude --resume {full_id}", file=sys.stderr)
         return 1
+    except NotADirectoryError as e:
+        # Edge case: target exists but isn't a directory (file with same name).
+        print(f"Error: cannot cd to {target}: {e}", file=sys.stderr)
+        return 1
 
 
 def _resolve_directory_pattern(
@@ -574,13 +621,35 @@ def cmd_scan(args) -> int:
     directory_only = getattr(args, "directory_only", None)
     start_dir_only = getattr(args, "start_dir_only", None)
     term = getattr(args, "term", None)
+    term2 = getattr(args, "term2", None)
+
+    # Two positionals are only valid when the FIRST is a `./` / `.\` / `.` shortcut.
+    # In that case the second positional is the actual term filter (equivalent to
+    # `csb scan -d <dirname> <term>`). Otherwise we reject -- a bare two-positional
+    # form like `csb scan amdead my-paper` is ambiguous.
+    if term2 is not None:
+        first_is_dot_prefix = term in (".", "./", ".\\") or (
+            term and (term.startswith("./") or term.startswith(".\\"))
+        )
+        if not first_is_dot_prefix:
+            print(
+                "Error: too many positional arguments. The two-positional form requires the "
+                "first to be `./<dir>`, `.\\<dir>`, or bare `.` -- otherwise use "
+                "`csb scan -d <dir> <term>` for the explicit form.",
+                file=sys.stderr,
+            )
+            return 2
 
     # Auto-promote ./ or .\ prefixed positional to implicit -d
     # (only when -d/-D/-s are not already set explicitly).
     if directories_below is None and directory_only is None and start_dir_only is None:
         term, promoted = _maybe_promote_dot_prefix(term)
         if promoted is not None:
             directories_below = promoted
+            # If the user gave two positionals (dot-prefix + term), the SECOND is
+            # the actual term filter to apply within the path-strict scope.
+            if term2 is not None:
+                term = term2
 
     # Pattern + descendant flag (None pattern means: bare, treat as implicit "-d .")
     pattern: str | None = directories_below or directory_only or start_dir_only