cc-session-tools 3.9.0__tar.gz → 3.10.0__tar.gz

{cc_session_tools-3.9.0/src/cc_session_tools.egg-info → cc_session_tools-3.10.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cc-session-tools
-Version: 3.9.0
+Version: 3.10.0
 Summary: Claude Code session management CLI tools (ccd, ccr, ccs, claude-code-usage, ccst) and hook library (hooks package)
 Author: raffishquartan
 License: MIT License
@@ -192,8 +192,8 @@ Messages can also be addressed to a specific session (`--to-session`) or to a fr
 description for whichever session picks it up first (`--to-description`) - project-
 addressed is by far the most common pattern in practice.
 
-The easiest way to use sessions is just to tell your session to send a message to
-another session (e.g. by name tag and/or location).
+The easiest way to use messages when you need them is just to tell your session to send 
+a message to another session (e.g. by name tag and/or location).
 
 ## Scheduled housekeeping: `ccsched`
 

{cc_session_tools-3.9.0 → cc_session_tools-3.10.0}/README.md

@@ -135,8 +135,8 @@ Messages can also be addressed to a specific session (`--to-session`) or to a fr
 description for whichever session picks it up first (`--to-description`) - project-
 addressed is by far the most common pattern in practice.
 
-The easiest way to use sessions is just to tell your session to send a message to
-another session (e.g. by name tag and/or location).
+The easiest way to use messages when you need them is just to tell your session to send 
+a message to another session (e.g. by name tag and/or location).
 
 ## Scheduled housekeeping: `ccsched`
 

{cc_session_tools-3.9.0 → cc_session_tools-3.10.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "cc-session-tools"
-version = "3.9.0"
+version = "3.10.0"
 description = "Claude Code session management CLI tools (ccd, ccr, ccs, claude-code-usage, ccst) and hook library (hooks package)"
 readme = "README.md"
 license = { file = "LICENSE" }
@@ -62,11 +62,11 @@ where = ["src"]
 # only filters within the file's *own* discovered package, and a wrongly
 # auto-discovered "cc_session_tools.skills.<name>.tests" package was never
 # covered by an exclude-package-data entry keyed just "cc_session_tools").
-exclude = ["cc_session_tools.skills", "cc_session_tools.skills.*", "cc_session_tools.config", "cc_session_tools.config.*", "cc_session_tools.prompts", "cc_session_tools.prompts.*"]
+exclude = ["cc_session_tools.skills", "cc_session_tools.skills.*", "cc_session_tools.config", "cc_session_tools.config.*"]
 
 [tool.setuptools.package-data]
 claude_code_usage = ["data/*.json"]
-cc_session_tools = ["skills/**/*", "config/*", "prompts/**/*"]
+cc_session_tools = ["skills/**/*", "config/*"]
 
 [tool.setuptools.exclude-package-data]
 cc_session_tools = ["**/tests/*", "**/__pycache__/*"]

{cc_session_tools-3.9.0 → cc_session_tools-3.10.0}/src/cc_session_tools/cli/ccst.py

@@ -160,56 +160,25 @@ def _discover_bundle() -> Path:
     )
 
 
-def _discover_prompts_dir() -> Path:
-    """Return the bundled prompts/ directory (pdata-migration follow-up prompts).
-
-    prompts/ is packaged inside cc_session_tools the same way skills/ and config/ are (see
-    _discover_source_dir) - src/cc_session_tools/cli/ccst.py -> ../prompts. No install-location
-    fallback, same reasoning as the other two: a fallback here would just mask a broken install.
-    """
-    candidate = Path(__file__).resolve().parent.parent / "prompts"
-    if candidate.is_dir():
-        return candidate
-    raise FileNotFoundError(
-        "Cannot locate bundled prompts/ directory. Run from the source tree or reinstall ccst."
-    )
-
-
-def _print_migration_prompt_reminders(
-    project_root: Path, *labeled_filenames: tuple[str, str]
+def _print_post_migration_skill_reminders(
+    project_root: Path, *labeled_skills: tuple[str, str]
 ) -> None:
-    """Print one "<label>: <path>" reminder line per (label, filename) pair, for the bundled
-    prompts/ directory, followed by a line telling the user to run it in a fresh context (a new
-    Claude Code session, or a dispatched Agent subagent) started in project_root.
-
-    Each prompt's own "Run it via" section already spells out the `cd <project> && claude -p
-    ...` invocation (see e.g. pdata-migration-skills-update.md) - that only works if the
-    session's cwd is the project root, since every prompt's Step 1 checks for it and aborts
-    otherwise. What the fresh-context requirement is actually protecting against is an
-    orchestrating session rationalizing away a stale reference it half-remembers writing
-    earlier in the same conversation - a dispatched Agent subagent (same cwd) gets that same
-    benefit without shelling out to a literal second process, so both are offered here rather
-    than only the `claude -p` invocation. Printing the reminder without saying so reads as "open
-    this file", which invites running it inline in whatever session called `ccst pdata init` -
-    the wrong cwd entirely.
-
-    Best-effort, deliberately swallowing a missing prompts/ directory: these reminders are a
-    nicety layered on top of an otherwise-already-completed classification or migration, not
-    the operation itself — a broken/partial install must never turn a successful --write (rows
-    already written, files already cut over) or dry-run (proposal already written) into a
-    reported failure just because this follow-up reminder couldn't be printed.
+    """Print one "<label>: <skill-name>" reminder per (label, skill) pair, each followed by a
+    line telling the user to run it in a fresh context rooted at project_root.
+
+    Each skill's Step 1 checks that cwd is the project root and aborts otherwise, so a bare skill
+    name invites running it inline in whatever session called `ccst pdata init` - the wrong cwd,
+    and the wrong context: the fresh-context requirement protects against an orchestrating
+    session rationalizing away a stale reference it half-remembers writing earlier in the same
+    conversation. A dispatched Agent subagent whose prompt starts with a `cd` into project_root
+    gets that same benefit as a new Claude Code session, so both are offered.
     """
-    try:
-        prompts_dir = _discover_prompts_dir()
-    except FileNotFoundError as exc:
-        print(f"({exc})", file=sys.stderr)
-        return
-    for label, filename in labeled_filenames:
-        print(f"{label}: {prompts_dir / filename}")
+    for label, skill in labeled_skills:
+        print(f"{label}: {skill}")
         print(
-            f"  Run in a new Claude Code session started in {project_root} (its own "
-            f"\"Run it via\" section has the exact command), or dispatch it as an Agent "
-            f"subagent with the same cwd - not inline in this session."
+            f"  Run it in a fresh context rooted at {project_root}: dispatch an Agent subagent "
+            f"whose prompt starts with `cd {project_root}`, or start a new Claude Code session "
+            f"there - not inline in this session."
         )
 
 
@@ -1236,9 +1205,9 @@ def _cmd_pdata_init(args: argparse.Namespace) -> int:
             # apply here.
             return 0
         print(f"\nProposal: {result.proposal_path}")
-        _print_migration_prompt_reminders(
+        _print_post_migration_skill_reminders(
             result.proposal_path.parent,
-            ("After a successful --write, update project docs", "pdata-migration-claude-md-update.md"),
+            ("After a successful --write, update project docs", "pm-pdata-do-update-project-docs"),
         )
         return 0
 
@@ -1286,10 +1255,10 @@ def _cmd_pdata_init(args: argparse.Namespace) -> int:
         print()
         print(write_result.report)  # spec §7.1 step 4's diff report, for review
         print(f"\nVerify: ccst pdata verify --project {args.project} --full")
-        _print_migration_prompt_reminders(
+        _print_post_migration_skill_reminders(
             project_root,
-            ("Update project docs", "pdata-migration-claude-md-update.md"),
-            ("Update consuming skills", "pdata-migration-skills-update.md"),
+            ("Update project docs", "pm-pdata-do-update-project-docs"),
+            ("Update consuming skills", "pm-pdata-do-update-consuming-skills"),
         )
         print("SUCCESS")
         return 0
@@ -2340,12 +2309,44 @@ _MIGRATE_ALL_BANNER = (
 )
 
 
+def _migrate_all_sessions_step(args: argparse.Namespace) -> int:
+    """The sessions step of `migrate all`: the legacy import writes uuid-keyed rows, so a
+    pre-uuid `sessions.db` is rebuilt first (`sessions migrate-uuid`, with its own backup and
+    concurrent-writer guard). A failed or refused rebuild skips the import."""
+    import sqlite3
+
+    from cc_session_tools.cli.migrate_sessions_db import migrate_uuid
+    from cc_session_tools.lib import sessions_db
+
+    db_path = sessions_db.default_db_path()
+    try:
+        pre_uuid = sessions_db.pre_uuid_sessions_table(db_path)
+    except sqlite3.DatabaseError as exc:
+        print(f"cannot read {db_path}: {exc} - not a valid sessions.db; nothing was changed",
+              file=sys.stderr)
+        return 1
+    if pre_uuid:
+        print(f"{db_path} is on the pre-3.0.0 schema - rebuilding it first "
+              "(`ccst sessions migrate-uuid`) so the legacy import can write to it.")
+        try:
+            rc = migrate_uuid(db_path=db_path, dry_run=args.dry_run)
+        except ValueError as exc:
+            print(str(exc), file=sys.stderr)
+            return 1
+        if rc != 0:
+            return rc
+        if args.dry_run:
+            print("The legacy import's own dry-run is skipped until the rebuild has run.")
+            return 0
+    return _cmd_sessions_migrate(argparse.Namespace(
+        dry_run=args.dry_run, sessions_db=None, tags_dir=None, mutes_file=None))
+
+
 def _cmd_migrate_all(args: argparse.Namespace) -> int:
     print(_MIGRATE_ALL_BANNER)
 
     steps: list[tuple[str, object]] = [
-        ("sessions", lambda: _cmd_sessions_migrate(argparse.Namespace(
-            dry_run=args.dry_run, sessions_db=None, tags_dir=None, mutes_file=None))),
+        ("sessions", lambda: _migrate_all_sessions_step(args)),
         ("ccmsg", lambda: _cmd_migrate_ccmsg(argparse.Namespace(
             old_root=None, backup_dir=None, dry_run=args.dry_run))),
         ("ccsched", lambda: _cmd_migrate_ccsched(argparse.Namespace(
@@ -2355,14 +2356,19 @@ def _cmd_migrate_all(args: argparse.Namespace) -> int:
     ]
 
     overall_rc = 0
+    failed: list[str] = []
     for name, step in steps:
         print(f"\n=== {name} ===")
         rc = step()  # type: ignore[operator]
         if rc != 0:
             overall_rc = rc
+            failed.append(name)
 
     print()
-    if args.dry_run:
+    if failed:
+        print(f"Steps that failed: {', '.join(failed)}. Review the ERROR/ABORT/refusal lines "
+              "above; a failed step leaves its own old files untouched and is safe to re-run.")
+    elif args.dry_run:
         print("Dry run complete — re-run without --dry-run once you're satisfied.")
     else:
         print("All migrations attempted. Review any ERROR/ABORT lines above; a "

{cc_session_tools-3.9.0 → cc_session_tools-3.10.0}/src/cc_session_tools/cli/migrate_sessions_db.py

@@ -114,10 +114,15 @@ def _read_legacy_sessions_rows(conn: sqlite3.Connection) -> list[sqlite3.Row]:
     """Every row from the pre-3.0.0 (project_dir, basename) `sessions` table, via raw SQL -
     not sessions_db.list_sessions()/_row_to_session, which require the `uuid` column this
     migration is the one adding. Safe to call against either schema shape: only the columns
-    that exist pre-3.0.0 are selected."""
+    that exist pre-3.0.0 are selected; `updated_at` (absent from v1.0.0 through v2.12.x) is read
+    as NULL when the table has no such column."""
+    updated_at = (
+        "updated_at" if "updated_at" in sessions_db.sessions_column_names(conn)
+        else "NULL AS updated_at"
+    )
     return conn.execute(
         "SELECT project_dir, basename, start_date, last_opened, last_active, "
-        "discovered_at, updated_at FROM sessions"
+        f"discovered_at, {updated_at} FROM sessions"
     ).fetchall()
 
 
@@ -162,6 +167,26 @@ def print_uuid_migration_dry_run(plan: UuidMigrationPlan, *, db_path: Path) -> N
     print("backing up: this rebuilds the sessions table and is a one-way schema change.")
 
 
+def _record_uuid_marker_only(db_path: Path, *, dry_run: bool) -> int:
+    """`sessions` is already uuid-keyed, or there is no `sessions` table to rebuild: there is
+    nothing to rebuild, only the completion marker to record (creating the current schema first
+    if the table is missing)."""
+    if dry_run:
+        print(f"{db_path} needs no rebuild - only its 3.0.0 completion marker would be "
+              "recorded. Re-run with --write to record it.")
+        return 0
+    conn = sessions_db.connect(path=db_path)
+    try:
+        db.record_migration(
+            conn, sessions_db.SESSIONS_UUID_MIGRATION, applied_at=sessions_db._now_iso()
+        )
+        conn.commit()
+    finally:
+        conn.close()
+    print(f"{db_path} needed no rebuild - recorded its 3.0.0 completion marker.")
+    return 0
+
+
 def migrate_uuid(*, db_path: Path, dry_run: bool, backup_dir: Path | None = None) -> int:
     """The 3.0.0 schema migration: rebuild `sessions` from the pre-3.0.0
     (project_dir, basename) primary key to (project_dir, basename, uuid), backfilling each
@@ -185,15 +210,35 @@ def migrate_uuid(*, db_path: Path, dry_run: bool, backup_dir: Path | None = None
     # be held by a live hook write, defeating the point of checking before touching anything.
     conn = db.connect(db_path)
     try:
-        if sessions_db.sessions_schema_is_uuid_keyed(conn) and db.migration_applied(
-            conn, sessions_db.SESSIONS_UUID_MIGRATION
-        ):
-            print(f"{db_path} is already migrated to the uuid-aware schema - nothing to do.")
-            return 0
-        legacy_rows = _read_legacy_sessions_rows(conn)
+        if not sessions_db.sessions_table_exists(conn):
+            marker_only = True
+            legacy_rows: list[sqlite3.Row] = []
+        else:
+            keyed = sessions_db.sessions_schema_is_uuid_keyed(conn)
+            recorded = sessions_db.migration_marker_recorded(
+                conn, sessions_db.SESSIONS_UUID_MIGRATION
+            )
+            if keyed and recorded:
+                print(f"{db_path} is already migrated to the uuid-aware schema - nothing to do.")
+                return 0
+            marker_only = keyed
+            if not keyed:
+                missing = sessions_db.missing_rebuild_columns(conn)
+                if missing:
+                    print(
+                        f"cannot migrate {db_path}: its `sessions` table is missing "
+                        f"column(s) the rebuild copies: {', '.join(missing)}. Nothing was "
+                        "changed; restore the file from a backup or repair it by hand.",
+                        file=sys.stderr,
+                    )
+                    return 1
+            legacy_rows = [] if keyed else _read_legacy_sessions_rows(conn)
     finally:
         conn.close()
 
+    if marker_only:
+        return _record_uuid_marker_only(db_path, dry_run=dry_run)
+
     plan = plan_uuid_migration(legacy_rows)
 
     if dry_run:
@@ -418,6 +463,30 @@ def _tar_backup(sources: list[Path], *, backup_dir: Path) -> Path | None:
     return dest
 
 
+def refuse_if_sessions_db_pre_uuid(db_path: Path) -> int | None:
+    """Pre-flight for the legacy import: it writes uuid-keyed rows, which a `sessions.db` still
+    on the pre-3.0.0 schema cannot accept. Returns a non-zero exit code (after printing the
+    fix) when the import must not run, else None. Read-only; must run before anything that could
+    connect-with-DDL, write, or back up."""
+    try:
+        pre_uuid = sessions_db.pre_uuid_sessions_table(db_path)
+    except sqlite3.DatabaseError as exc:
+        print(f"cannot read {db_path}: {exc} - not a valid sessions.db; nothing was changed",
+              file=sys.stderr)
+        return 1
+    if not pre_uuid:
+        return None
+    print(
+        f"cannot run the legacy flat-file import: {db_path} is still on the pre-3.0.0 schema "
+        "(no uuid column), which the import cannot write to. Nothing was changed. First run "
+        "`ccst sessions migrate-uuid --write` from a plain terminal with no other `claude` "
+        "session running (it takes a backup first), then re-run this - or run `ccst migrate "
+        "all`, which does both in order.",
+        file=sys.stderr,
+    )
+    return 1
+
+
 def run_migration(
     *,
     dry_run: bool,
@@ -427,6 +496,10 @@ def run_migration(
     roots: list[Path],
     backup_dir: Path,
 ) -> int:
+    refusal = refuse_if_sessions_db_pre_uuid(db_path)
+    if refusal is not None:
+        return refusal
+
     print(f"Sessions DB  : {db_path}")
     print(f"Tags source  : {tags_dir}")
     print(f"Mutes source : {mutes_file}")

{cc_session_tools-3.9.0 → cc_session_tools-3.10.0}/src/cc_session_tools/lib/doctor.py

@@ -675,7 +675,26 @@ def _migration_recorded(db_path: Path, marker_name: str) -> bool:
         conn.close()
 
 
-def check_pending_data_store_migration(paths: LegacyMigrationPaths) -> list[CheckResult]:
+def _sessions_marker() -> str:
+    from cc_session_tools.lib.sessions_db import LEGACY_FLAT_FILE_MIGRATION
+
+    return LEGACY_FLAT_FILE_MIGRATION
+
+
+def _sessions_db_is_pre_uuid(db_path: Path) -> bool:
+    """`sessions_db.pre_uuid_sessions_table`, with an unreadable file counting as not pre-uuid
+    (other checks already report a database that fails to open)."""
+    from cc_session_tools.lib import sessions_db
+
+    try:
+        return sessions_db.pre_uuid_sessions_table(db_path)
+    except sqlite3.DatabaseError:
+        return False
+
+
+def check_pending_data_store_migration(
+    paths: LegacyMigrationPaths, *, sessions_db_path: Path | None = None,
+) -> list[CheckResult]:
     """Detect legacy flat-file data left over from a pre-1.0.0 install.
 
     :func:`check_data_stores` can't distinguish a fresh install (nothing to
@@ -696,6 +715,10 @@ def check_pending_data_store_migration(paths: LegacyMigrationPaths) -> list[Chec
     fills from the first hook fire after install, so counting rows reported "already
     migrated" for anyone who opened a session before migrating, and the FAIL that should
     have prompted them never fired.
+
+    `sessions_db_path` is the sessions.db the `sessions` finding reads; pass the same path the
+    3.0.0 uuid check uses so the two findings can never describe different files (defaults to
+    `paths.data_home / "sessions.db"`).
     """
     from cc_session_tools.lib.messaging.repository import (
         LEGACY_FLAT_FILE_MIGRATION as _CCMSG_MIGRATION,
@@ -724,7 +747,7 @@ def check_pending_data_store_migration(paths: LegacyMigrationPaths) -> list[Chec
         "sessions": (
             (paths.tags_dir, paths.mutes_file),
             _count_legacy_sessions(paths.tags_dir, paths.mutes_file),
-            paths.data_home / "sessions.db",
+            sessions_db_path if sessions_db_path is not None else paths.data_home / "sessions.db",
             _SESSIONS_MIGRATION,
         ),
         "telemetry": (
@@ -748,6 +771,13 @@ def check_pending_data_store_migration(paths: LegacyMigrationPaths) -> list[Chec
         already_migrated = _migration_recorded(new_db_path, marker_name)
         evidence = f"the import is recorded in {new_db_path.name}"
         if not already_migrated:
+            rebuild_note = ""
+            if store_name == "sessions" and _sessions_db_is_pre_uuid(new_db_path):
+                rebuild_note = (
+                    f" It will first rebuild {new_db_path.name} to the 3.0.0 uuid schema "
+                    "(taking a backup; close any running `claude` sessions first) - the "
+                    "import cannot write to the old schema."
+                )
             results.append(
                 CheckResult(
                     name=name,
@@ -756,7 +786,7 @@ def check_pending_data_store_migration(paths: LegacyMigrationPaths) -> list[Chec
                         f"{legacy_count} unmigrated item(s) at {existing}; run "
                         "`ccst migrate all` from a plain terminal (NOT inside a Claude Code "
                         "session — the delete step is blocked by bash-hard-deny) to migrate "
-                        f"into {new_db_path}"
+                        f"into {new_db_path}.{rebuild_note}"
                     ),
                 )
             )
@@ -942,7 +972,9 @@ def check_sessions_project_dir_absolute(sessions_db_path: Path) -> list[CheckRes
     )]
 
 
-def check_sessions_uuid_migration(sessions_db_path: Path) -> list[CheckResult]:
+def check_sessions_uuid_migration(
+    sessions_db_path: Path, *, legacy_sessions_pending: bool = False,
+) -> list[CheckResult]:
     """FAIL if sessions.db still has the pre-3.0.0 (project_dir, basename) primary key -
     forked sessions (Ctrl-L) silently clobber each other's activity rows until
     `ccst sessions migrate-uuid --write` runs. Distinguishes "never migrated" from
@@ -956,7 +988,10 @@ def check_sessions_uuid_migration(sessions_db_path: Path) -> list[CheckResult]:
     A sessions.db that doesn't exist yet reads OK: connect() records the migration
     marker at creation time for any brand-new file (sessions_db.py), so a genuinely
     fresh install is never in a pending state - there is simply nothing to check here
-    yet, and this check must not create the file itself just to inspect it."""
+    yet, and this check must not create the file itself just to inspect it.
+
+    `legacy_sessions_pending` says the 1.0.0 flat-file import is also still pending; the two FAIL
+    branches then note that `ccst migrate all` performs both, in the order that works."""
     import sqlite3
 
     from cc_session_tools.lib import db as db_lib
@@ -1000,6 +1035,11 @@ def check_sessions_uuid_migration(sessions_db_path: Path) -> list[CheckResult]:
         "run `ccst sessions migrate-uuid --write` from a plain terminal with no other "
         "`claude` session running (it takes a backup first; see --help)"
     )
+    if legacy_sessions_pending:
+        remediation += (
+            "; the legacy import is also pending, and `ccst migrate all` performs both in "
+            "the order that works"
+        )
     if not pk_is_uuid_keyed and not marker_present:
         return [CheckResult(
             name=name, status=Status.FAIL,
@@ -1158,7 +1198,8 @@ def run_all_checks(
 
     # Pending legacy-data migration
     if legacy_migration_paths is not None:
-        results.extend(check_pending_data_store_migration(legacy_migration_paths))
+        results.extend(check_pending_data_store_migration(
+            legacy_migration_paths, sessions_db_path=sessions_db_path))
 
     # Pending ccst pdata init cutover (spec §7.1 step 7)
     if projects_root is not None:
@@ -1172,7 +1213,15 @@ def run_all_checks(
     # since project-dir-absolute's own check degrades to a WARN pointing back at it when
     # the uuid migration hasn't run yet (a pre-migration schema can't be queried the same way).
     if sessions_db_path is not None:
-        results.extend(check_sessions_uuid_migration(sessions_db_path))
+        legacy_sessions_pending = (
+            legacy_migration_paths is not None
+            and _count_legacy_sessions(
+                legacy_migration_paths.tags_dir, legacy_migration_paths.mutes_file
+            ) > 0
+            and not _migration_recorded(sessions_db_path, _sessions_marker())
+        )
+        results.extend(check_sessions_uuid_migration(
+            sessions_db_path, legacy_sessions_pending=legacy_sessions_pending))
         results.extend(check_sessions_project_dir_absolute(sessions_db_path))
 
     # Optional dependencies for claude-code-usage's reconcile / ccusage blocks

{cc_session_tools-3.9.0 → cc_session_tools-3.10.0}/src/cc_session_tools/lib/pdata/init_paths.py

@@ -112,13 +112,41 @@ def project_db_dir_override(rehearse: Path | None) -> Iterator[None]:
     override_dir = rehearse / REHEARSAL_DB_DIRNAME
     previous = os.environ.get(store.PROJECT_DB_DIR_ENV)
     os.environ[store.PROJECT_DB_DIR_ENV] = str(override_dir)
+    _live_db_dir_env_stack.append(previous)
     try:
         yield
     finally:
-        if previous is None:
-            os.environ.pop(store.PROJECT_DB_DIR_ENV, None)
-        else:
-            os.environ[store.PROJECT_DB_DIR_ENV] = previous
+        _live_db_dir_env_stack.pop()
+        _restore_db_dir_env(previous)
+
+
+# The CCST_PROJECT_DB_DIR value in effect before each active project_db_dir_override (None =
+# unset), outermost first - what live_project_db_dir() restores.
+_live_db_dir_env_stack: list[str | None] = []
+
+
+def _restore_db_dir_env(value: str | None) -> None:
+    if value is None:
+        os.environ.pop(store.PROJECT_DB_DIR_ENV, None)
+    else:
+        os.environ[store.PROJECT_DB_DIR_ENV] = value
+
+
+@contextmanager
+def live_project_db_dir() -> Iterator[None]:
+    """Inside a project_db_dir_override block, temporarily point store.db_path() back at the
+    real per-project .db dir. For questions about the machine rather than the rehearsal copy
+    (e.g. "is this project already migrated here?"): a `cp -r` rehearsal copy never contains the
+    real .db, so the sandbox always answers "no". No-op outside an override."""
+    if not _live_db_dir_env_stack:
+        yield
+        return
+    inside = os.environ.get(store.PROJECT_DB_DIR_ENV)
+    _restore_db_dir_env(_live_db_dir_env_stack[0])
+    try:
+        yield
+    finally:
+        _restore_db_dir_env(inside)
 
 
 @contextmanager

{cc_session_tools-3.9.0 → cc_session_tools-3.10.0}/src/cc_session_tools/lib/pdata/init_service.py

@@ -324,7 +324,11 @@ def _pending_adoption(*, project: str, project_root: Path) -> dump.DumpInfo | No
             "project. Publish a fresh dump from a known-good machine (ccst pdata dump --force) "
             "or reconcile manually (ccst pdata resolve) once those commands exist."
         )
-    if _already_locally_migrated(project):
+    # The live .db, not a --rehearse sandbox's: a rehearsal copy never contains the real .db, so
+    # the sandbox would always look unmigrated and rehearsal would never reach classification.
+    with init_paths.live_project_db_dir():
+        already_migrated = _already_locally_migrated(project)
+    if already_migrated:
         return None
     return info
 

{cc_session_tools-3.9.0 → cc_session_tools-3.10.0}/src/cc_session_tools/lib/sessions_db.py

@@ -153,6 +153,53 @@ def sessions_schema_is_uuid_keyed(conn: sqlite3.Connection) -> bool:
     )
 
 
+# Columns of the pre-3.0.0 `sessions` table that the uuid rebuild copies into the new table.
+# `updated_at` is deliberately absent: databases from v1.0.0 through v2.12.x never had it.
+REBUILD_REQUIRED_COLUMNS = (
+    "project_dir", "basename", "start_date", "last_opened", "last_active", "discovered_at",
+)
+
+
+def sessions_table_exists(conn: sqlite3.Connection) -> bool:
+    return conn.execute(
+        "SELECT 1 FROM sqlite_master WHERE type='table' AND name='sessions'"
+    ).fetchone() is not None
+
+
+def sessions_column_names(conn: sqlite3.Connection) -> set[str]:
+    return {row["name"] for row in conn.execute("PRAGMA table_info(sessions)")}
+
+
+def missing_rebuild_columns(conn: sqlite3.Connection) -> list[str]:
+    """Columns the 3.0.0 rebuild must copy that the existing `sessions` table lacks."""
+    present = sessions_column_names(conn)
+    return [c for c in REBUILD_REQUIRED_COLUMNS if c not in present]
+
+
+def migration_marker_recorded(conn: sqlite3.Connection, name: str) -> bool:
+    """`db.migration_applied`, but False (not an error) on a database that predates the
+    `migrations` table (v1.0.0 through roughly v2.8)."""
+    try:
+        return db.migration_applied(conn, name)
+    except sqlite3.OperationalError:
+        return False
+
+
+def pre_uuid_sessions_table(path: Path) -> bool:
+    """True iff `path` exists, has a `sessions` table, and that table is not uuid-keyed - the
+    one state in which the 1.0.0 legacy import cannot write. A missing file or a missing
+    `sessions` table is False: `connect()` creates the current schema for both. Read-only, so it
+    never creates or alters anything; raises sqlite3.DatabaseError for a file that is not a
+    valid database."""
+    if not path.exists():
+        return False
+    conn = db.connect(path, readonly=True)
+    try:
+        return sessions_table_exists(conn) and not sessions_schema_is_uuid_keyed(conn)
+    finally:
+        conn.close()
+
+
 def connect(*, path: Path | None = None, readonly: bool = False) -> sqlite3.Connection:
     """Open sessions.db (or an explicit override path — used by tests and by
     ccst doctor --mutes-file). readonly=True skips schema creation; callers

{cc_session_tools-3.9.0 → cc_session_tools-3.10.0}/src/cc_session_tools/skills/pm-pdata-do-init/SKILL.md

@@ -210,6 +210,22 @@ Step 3's garbled-header recipe) - so anything else in the project citing the old
 a live signpost instead of a silent 404. Pass `--leave-no-pointer-files` if this run shouldn't
 leave one (e.g. a rehearsal, or a project convention against extra files at migrated paths).
 
+### Then run both post-migration skills
+
+After a successful `--write` (not after a dry-run or a rehearsal), update everything that still
+describes or uses the old flat-file layout. Run these in order, each in its own fresh-context
+`Agent` subagent whose prompt begins with `cd ~/cc/<project>` - not inline in this session, which
+has just written the migration and would rationalize away stale references it remembers:
+
+1. `pm-pdata-do-update-project-docs` - rewrites the project's `CLAUDE.md` and other top-level docs
+   to name the pdata record_groups and `ccst pdata` commands, and reports folder-layout drift.
+2. `pm-pdata-do-update-consuming-skills` - finds skills that literally reference the old paths and
+   rewrites direct reads/writes to `ccst pdata` commands, flagging anything it cannot rewrite
+   mechanically.
+
+Relay each subagent's report to the user, including anything flagged for a human decision. If a
+later `--write` round adds more record groups, run both again; they are safe to re-run.
+
 ## 8. Rollback, if something's found wrong post-cutover
 
 There is no `--rollback` flag. Recover by hand: