cc-session-tools 2.12.0__tar.gz → 2.12.2__tar.gz

{cc_session_tools-2.12.0/src/cc_session_tools.egg-info → cc_session_tools-2.12.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cc-session-tools
-Version: 2.12.0
+Version: 2.12.2
 Summary: Claude Code session management CLI tools (ccd, ccr, ccs, claude-code-usage, ccst) and hook library (cccs_hooks)
 Author: raffishquartan
 License: MIT License
@@ -80,7 +80,7 @@ bundled scheduled jobs:
 | **`claude-code-usage`** | Multi-dimensional usage analytics CLI: query/group/filter by project, session, model, MCP server, plugin, tool, day/week/month/year. Reconciles dollar totals against `ccusage`. |
 | **`ccst <noun> <verb>`** | Umbrella CLI for hook and skill management: install, uninstall, health-check, shell helpers, telemetry trim, global CLAUDE.md messaging block. |
 | **`ccmsg <command>`** | Inter-session messaging CLI: send, deliver, read, list, claim, and archive durable messages between Claude Code sessions. |
-| **`ccsched <command>`** | Scheduled-task CLI: register, list, edit, enable/disable, and remove recurring jobs; inspect status; one-shot sweep. |
+| **`ccsched <command>`** | Scheduled-task CLI: register, list, edit, rename, enable/disable, and remove recurring jobs; inspect status; one-shot sweep. |
 | **`ccl` (shell fn)** | Shell function wrapping `ccs` for list-mode usage. Installed by `ccst shell install`. |
 
 **Bundled skills** (installed via `ccst skills install`)
@@ -630,6 +630,7 @@ loser exits).
 | `edit` | Edit a job field (cadence, command, coalesce, etc.) in-place. |
 | `enable` / `disable` | Toggle a job on or off without removing it. |
 | `remove` | Delete a job from the registry. |
+| `rename` | Rename a job's id; its run state and ledger history carry over to the new id. Refuses while the job is running. |
 | `run` | Run a job immediately (foreground; bypasses cadence). |
 | `status` | Show recent ledger history for a job (or all jobs). |
 | `sweep` | One-shot reconcile + launch from the shell. |
@@ -1073,6 +1074,12 @@ Claude Code lets multiple sessions share a single task list if they all set the
 
 This means you can pick up a task created in yesterday's session from today's session in the same project, without any extra setup.
 
+Both `ccd` and `ccr` also unconditionally set `CLAUDE_CODE_ENABLE_TODO_TOOLS=1` in the launched
+session's environment. Claude Code >=2.1.233 hides the TodoWrite/TaskCreate/TaskGet/TaskUpdate/
+TaskList tools by default on Opus 4.8, Sonnet 5, Fable 5, Mythos 5 and later unless this is set -
+without it, the task list machinery above would be wired up but the tools that use it would be
+invisible to the model.
+
 ## Typo protection (strict root only)
 
 When you start a session under the **strict** (`PROJ_ROOT`) root, `ccd` checks whether your tag's first dash-separated term looks like a typo of the project directory name (Levenshtein distance ≤ 2):

{cc_session_tools-2.12.0 → cc_session_tools-2.12.2}/README.md

@@ -23,7 +23,7 @@ bundled scheduled jobs:
 | **`claude-code-usage`** | Multi-dimensional usage analytics CLI: query/group/filter by project, session, model, MCP server, plugin, tool, day/week/month/year. Reconciles dollar totals against `ccusage`. |
 | **`ccst <noun> <verb>`** | Umbrella CLI for hook and skill management: install, uninstall, health-check, shell helpers, telemetry trim, global CLAUDE.md messaging block. |
 | **`ccmsg <command>`** | Inter-session messaging CLI: send, deliver, read, list, claim, and archive durable messages between Claude Code sessions. |
-| **`ccsched <command>`** | Scheduled-task CLI: register, list, edit, enable/disable, and remove recurring jobs; inspect status; one-shot sweep. |
+| **`ccsched <command>`** | Scheduled-task CLI: register, list, edit, rename, enable/disable, and remove recurring jobs; inspect status; one-shot sweep. |
 | **`ccl` (shell fn)** | Shell function wrapping `ccs` for list-mode usage. Installed by `ccst shell install`. |
 
 **Bundled skills** (installed via `ccst skills install`)
@@ -573,6 +573,7 @@ loser exits).
 | `edit` | Edit a job field (cadence, command, coalesce, etc.) in-place. |
 | `enable` / `disable` | Toggle a job on or off without removing it. |
 | `remove` | Delete a job from the registry. |
+| `rename` | Rename a job's id; its run state and ledger history carry over to the new id. Refuses while the job is running. |
 | `run` | Run a job immediately (foreground; bypasses cadence). |
 | `status` | Show recent ledger history for a job (or all jobs). |
 | `sweep` | One-shot reconcile + launch from the shell. |
@@ -1016,6 +1017,12 @@ Claude Code lets multiple sessions share a single task list if they all set the
 
 This means you can pick up a task created in yesterday's session from today's session in the same project, without any extra setup.
 
+Both `ccd` and `ccr` also unconditionally set `CLAUDE_CODE_ENABLE_TODO_TOOLS=1` in the launched
+session's environment. Claude Code >=2.1.233 hides the TodoWrite/TaskCreate/TaskGet/TaskUpdate/
+TaskList tools by default on Opus 4.8, Sonnet 5, Fable 5, Mythos 5 and later unless this is set -
+without it, the task list machinery above would be wired up but the tools that use it would be
+invisible to the model.
+
 ## Typo protection (strict root only)
 
 When you start a session under the **strict** (`PROJ_ROOT`) root, `ccd` checks whether your tag's first dash-separated term looks like a typo of the project directory name (Levenshtein distance ≤ 2):

{cc_session_tools-2.12.0 → cc_session_tools-2.12.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "cc-session-tools"
-version = "2.12.0"
+version = "2.12.2"
 description = "Claude Code session management CLI tools (ccd, ccr, ccs, claude-code-usage, ccst) and hook library (cccs_hooks)"
 readme = "README.md"
 license = { file = "LICENSE" }

{cc_session_tools-2.12.0 → cc_session_tools-2.12.2}/src/cc_session_tools/cli/ccd.py

@@ -200,6 +200,10 @@ def main(argv: list[str] | None = None) -> int:
     env["CLD_SESSION_TAG"] = tag
     env["CLD_SESSION_DIR"] = str(session_dir)
     env["CLD_SESSION_MODE"] = "new"
+    # Claude Code >=2.1.233 hides TodoWrite/TaskCreate/TaskGet/TaskUpdate/TaskList
+    # on Opus 4.8, Sonnet 5, Fable 5, Mythos 5+ unless this is set, regardless of
+    # whether a task list ID resolves below.
+    env["CLAUDE_CODE_ENABLE_TODO_TOOLS"] = "1"
     task_list_id = id_for_project(real_pwd)
     if task_list_id is not None:
         env["CLAUDE_CODE_TASK_LIST_ID"] = task_list_id

{cc_session_tools-2.12.0 → cc_session_tools-2.12.2}/src/cc_session_tools/cli/ccr.py

@@ -221,6 +221,10 @@ def main(argv: list[str] | None = None) -> int:
     env["CLD_SESSION_TAG"] = tag
     env["CLD_SESSION_DIR"] = str(m.session_dir)
     env["CLD_SESSION_MODE"] = "resume"
+    # Claude Code >=2.1.233 hides TodoWrite/TaskCreate/TaskGet/TaskUpdate/TaskList
+    # on Opus 4.8, Sonnet 5, Fable 5, Mythos 5+ unless this is set, regardless of
+    # whether a task list ID resolves below.
+    env["CLAUDE_CODE_ENABLE_TODO_TOOLS"] = "1"
     task_list_id = id_for_project(m.project_dir)
     if task_list_id is not None:
         env["CLAUDE_CODE_TASK_LIST_ID"] = task_list_id

{cc_session_tools-2.12.0 → cc_session_tools-2.12.2}/src/cc_session_tools/cli/ccsched.py

@@ -25,9 +25,11 @@ from cc_session_tools.lib.scheduler.duration import parse_duration
 from cc_session_tools.lib.scheduler.jobspec import (
     JobSpec,
     JobValidationError,
+    check_job_id,
     parse_success_exit_codes,
     validate_job_fields,
 )
+from cc_session_tools.lib.scheduler.lock import InFlightLockHeld, in_flight_lock
 from cc_session_tools.lib.scheduler.runner import run_command
 
 
@@ -137,6 +139,18 @@ def _build_parser() -> argparse.ArgumentParser:
         sp = sub.add_parser(verb, help=f"{verb.capitalize()} a job.")
         sp.add_argument("id")
 
+    rename_p = sub.add_parser(
+        "rename",
+        help="Rename a job, keeping its run history under the new id.",
+    )
+    rename_p.add_argument("old_id", metavar="old-id", help="The job's current id.")
+    rename_p.add_argument(
+        "new_id", metavar="new-id",
+        help="The new id, lowercase kebab-case [a-z0-9-]. Run state (last_success, "
+             "consecutive_failures, suspended, ...) and ledger history (`ccsched status`) "
+             "carry over. Refuses while the job is currently running.",
+    )
+
     run_p = sub.add_parser("run", help="Run one job now.")
     run_p.add_argument("id")
 
@@ -303,6 +317,25 @@ def _cmd_remove(job_id: str) -> int:
     return 0
 
 
+def _cmd_rename(args: argparse.Namespace) -> int:
+    if args.new_id == args.old_id:
+        return _err("new id is the same as the current id")
+    try:
+        check_job_id(args.new_id)
+    except JobValidationError as exc:
+        return _err(str(exc))
+    try:
+        with in_flight_lock(args.old_id):
+            registry.rename_job(args.old_id, args.new_id)
+            ledger.rename_job(args.old_id, args.new_id)
+    except InFlightLockHeld:
+        return _err(f"job {args.old_id!r} is currently running; try again once it finishes")
+    except registry.RegistryError as exc:
+        return _err(str(exc))
+    print(f"renamed {args.old_id} -> {args.new_id}")
+    return 0
+
+
 def _cmd_run(
     args: argparse.Namespace, *, notify_push: worker.NotifyPush = notify.push_outcome,
 ) -> int:
@@ -340,6 +373,9 @@ def _cmd_status(args: argparse.Namespace) -> int:
     for r in rows:
         print(f"{r.get('ts','')} {r.get('job_id',''):<24} {r.get('event',''):<12} "
               f"ran={r.get('ran')} exit={r.get('exit_code')}")
+        error = r.get("error")
+        if error:
+            print(f"    {error}")
     return 0
 
 
@@ -380,6 +416,8 @@ def main(argv: list[str] | None = None) -> int:
         return _cmd_set_enabled(args.id, False)
     if args.command == "remove":
         return _cmd_remove(args.id)
+    if args.command == "rename":
+        return _cmd_rename(args)
     if args.command == "run":
         return _cmd_run(args)
     if args.command == "status":

{cc_session_tools-2.12.0 → cc_session_tools-2.12.2}/src/cc_session_tools/cli/ccst.py

@@ -1156,6 +1156,11 @@ def _cmd_pdata_init(args: argparse.Namespace) -> int:
             print(f"ccst pdata: {exc}", file=sys.stderr)
             return 2
         print(result.report)
+        if result.would_adopt_from_dump:
+            # No proposal was written and there's nothing to classify - the reminders below are
+            # about updating project docs after a real classify/import cutover, which doesn't
+            # apply here.
+            return 0
         print(f"\nProposal: {result.proposal_path}")
         _print_migration_prompt_reminders(
             result.proposal_path.parent,
@@ -1407,6 +1412,35 @@ def _cmd_pdata_verify(args: argparse.Namespace) -> int:
             print(f"ccst pdata verify: {project}: {exc}", file=sys.stderr)
             worst = max(worst, 2)
             continue
+        except Exception as exc:
+            # run_verify crashed before persisting anything for this project - a
+            # per-project issue (its own except ValueError above) is the only
+            # *expected* failure shape; anything else is a bug or a transient
+            # race (e.g. a concurrent writer) worth surfacing in full rather than
+            # letting it silently take the whole --all-projects sweep down with
+            # no diagnostic trail. Rerun once, in --full mode, as a one-shot
+            # diagnostic: exactly one retry, never chained further even if the
+            # retry crashes too, so a persistently broken project reports once
+            # and moves on instead of turning into a retry loop.
+            print(f"ccst pdata verify: {project}: crashed: {exc}", file=sys.stderr)
+            worst = max(worst, 1)
+            flagged.append(project)
+            try:
+                diag = verify.run_verify(project=project, full=True)
+            except Exception as diag_exc:
+                print(
+                    f"ccst pdata verify: {project}: diagnostic rerun also crashed: {diag_exc}",
+                    file=sys.stderr,
+                )
+            else:
+                print(
+                    f"ccst pdata verify: {project}: diagnostic rerun: {diag.status} "
+                    f"({len(diag.issues)} issue(s))",
+                    file=sys.stderr,
+                )
+                for issue in diag.issues:
+                    print(f"  [{issue.severity}] {issue.check}: {issue.message}", file=sys.stderr)
+            continue
         if summary.status != "OK":
             worst = max(worst, 1)
             flagged.append(project)

cc_session_tools-2.12.2/src/cc_session_tools/lib/occupancy.py

@@ -0,0 +1,168 @@
+"""Is a live `claude` process currently working in a given project (spec: "Process safety").
+
+Fails safe: any error enumerating `claude` processes, or resolving a PID's cwd, counts as
+occupied, never as clear - see is_occupied()'s single try/except around both steps. Letting
+either failure fall through to "not occupied" would be indistinguishable from the legitimate
+"no claude process right now" case to every caller, which is exactly the false "clear to
+rehydrate" signal this module exists to prevent.
+"""
+from __future__ import annotations
+
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+
+def _claude_pids() -> list[int]:
+    """Every running `claude` process's PID. Raises (OSError, subprocess.SubprocessError) on any
+    genuine failure to enumerate them - does not swallow these into an empty list, since an
+    empty list here is indistinguishable from "pgrep ran fine and found nothing" to is_occupied().
+    A *clean* "no matches" from pgrep itself (exit code 1, empty stdout, no exception) is not a
+    failure and correctly produces []."""
+    out = subprocess.run(
+        ["pgrep", "-x", "claude"],
+        capture_output=True,
+        text=True,
+        timeout=5,
+    ).stdout
+    # str.split() with no args already splits on whitespace and drops empty
+    # tokens, so each token is already stripped — no further .strip() needed.
+    return [int(p) for p in out.split() if p.isdigit()]
+
+
+def _cwd_of_pid(pid: int) -> Path:
+    """pid's current working directory. Raises (OSError, subprocess.SubprocessError) on any
+    failure - callers must catch both, not just OSError (a nonzero lsof exit, e.g. the ordinary
+    race where the process has already exited, raises CalledProcessError, not OSError)."""
+    if sys.platform == "darwin":
+        # lsof's field-output mode ("man lsof", OUTPUT FOR OTHER PROGRAMS)
+        # always emits the PID ('p') field, then whichever other fields were
+        # requested — here just the name ('n') field — each on its own line,
+        # prefixed by its field character. So scanning for the line that
+        # starts with 'n' and stripping that one character is documented
+        # lsof behaviour, not a guess.
+        out = subprocess.run(
+            ["lsof", "-a", "-p", str(pid), "-d", "cwd", "-Fn"],
+            capture_output=True,
+            text=True,
+            timeout=5,
+            check=True,
+        ).stdout
+        for line in out.splitlines():
+            if line.startswith("n"):
+                return Path(line[1:])
+        raise OSError(f"lsof returned no cwd line for pid {pid}")
+    if sys.platform.startswith("linux"):
+        return Path(os.readlink(f"/proc/{pid}/cwd"))
+    # A third platform (e.g. Windows-native Python, not WSL) has no /proc and isn't darwin -
+    # raise explicitly rather than silently falling into the Linux branch and failing with a
+    # confusing FileNotFoundError. Still caught by is_occupied()'s fail-safe handler below.
+    raise OSError(f"occupancy check not implemented for platform {sys.platform!r}")
+
+
+def _ppid_of(pid: int) -> int | None:
+    """`pid`'s parent PID, or None if it can't be determined (already exited, permission error,
+    or an unsupported platform) - every failure degrades to None rather than raising, since the
+    only caller, `launching_claude_pid`, already treats "can't climb any further" as a normal
+    stopping condition, not an error."""
+    if sys.platform.startswith("linux"):
+        try:
+            status = Path(f"/proc/{pid}/status").read_text()
+        except OSError:
+            return None
+        for line in status.splitlines():
+            if line.startswith("PPid:"):
+                return int(line.split()[1])
+        return None
+    if sys.platform == "darwin":
+        try:
+            out = subprocess.run(
+                ["ps", "-o", "ppid=", "-p", str(pid)],
+                capture_output=True, text=True, timeout=5, check=True,
+            ).stdout.strip()
+        except (OSError, subprocess.SubprocessError):
+            return None
+        return int(out) if out.isdigit() else None
+    return None
+
+
+def _comm_of(pid: int) -> str | None:
+    """`pid`'s process name (`/proc/<pid>/comm`'s exact contents on Linux - the same field
+    `pgrep -x` matches against), or None if it can't be read."""
+    if sys.platform.startswith("linux"):
+        try:
+            return Path(f"/proc/{pid}/comm").read_text().strip()
+        except OSError:
+            return None
+    if sys.platform == "darwin":
+        try:
+            out = subprocess.run(
+                ["ps", "-o", "comm=", "-p", str(pid)],
+                capture_output=True, text=True, timeout=5, check=True,
+            ).stdout.strip()
+        except (OSError, subprocess.SubprocessError):
+            return None
+        return out or None
+    return None
+
+
+def launching_claude_pid(start_pid: int, *, max_hops: int = 5) -> int | None:
+    """The nearest ancestor of `start_pid` (inclusive) whose process name is `claude`, or None if
+    none is found within `max_hops` steps.
+
+    Exists because a hook's `command` is not run as a direct child of the `claude` process: Claude
+    Code spawns every command hook via `/bin/sh -c "<command>"`, and on any system where `/bin/sh`
+    is dash rather than bash - the Debian/Ubuntu/WSL2 default - dash does not replace itself with
+    the command it's running the way bash does for a single simple `-c` script. That leaves a real
+    `sh` process between `claude` and the hook's own process, confirmed empirically (not assumed)
+    by installing a diagnostic `SessionStart` hook in a scratch project and inspecting
+    `/proc/<pid>/{comm,status}` for the whole ancestor chain: `ccst` (the hook) -> `sh -c ...` ->
+    `claude` -> the shell that launched it, exactly two hops from `os.getppid()`'s immediate
+    parent to the real `claude` process, not one. A caller that naively used `os.getppid()` as
+    "the launching claude process's PID" (as this hook's `main()` used to) would therefore be
+    excluding the wrong PID from `is_occupied()`'s check every time - one that will never actually
+    appear in `_claude_pids()`'s `pgrep -x claude` results - so the exclusion silently never
+    matches anything, and a SessionStart hook checking its own just-started project reports it as
+    occupied by itself on every single invocation.
+
+    Bounded to `max_hops` (comfortably above the 2 hops seen in the confirmed case, to tolerate
+    extra wrapping such as a `timeout` command) so an unrecognised process-tree shape degrades to
+    None rather than looping forever; a caller receiving None should exclude nothing, matching
+    this module's existing bias toward reporting occupied over silently under-excluding.
+
+    Unconfirmed on macOS's own `/bin/sh` (Apple's bash 3.2 build) - it may already perform the
+    single-command replacement bash does elsewhere, making the extra hop unnecessary there; this
+    function is safe either way since it stops as soon as it finds a `claude` ancestor, however
+    many hops that takes."""
+    pid = start_pid
+    for _ in range(max_hops):
+        if _comm_of(pid) == "claude":
+            return pid
+        parent = _ppid_of(pid)
+        if parent is None or parent == pid:
+            return None
+        pid = parent
+    return None
+
+
+def is_occupied(project_root: Path, *, exclude_pid: int | None = None) -> bool:
+    """True if any live `claude` process (other than `exclude_pid`) has its cwd resolved to
+    exactly `project_root` - matching Claude Code's own behaviour of keeping a session's cwd
+    fixed at the project root for its whole lifetime (see e.g. ccd.py's os.chdir(real_pwd)),
+    never a cc-sessions/<tag>/ subdirectory."""
+    resolved_root = project_root.resolve()
+    try:
+        pids = _claude_pids()
+    except (OSError, subprocess.SubprocessError):
+        return True  # can't even enumerate claude processes - fail safe, never fail open
+    for pid in pids:
+        if pid == exclude_pid:
+            continue
+        try:
+            cwd = _cwd_of_pid(pid).resolve()
+        except (OSError, subprocess.SubprocessError):
+            return True  # fail safe, never fail open
+        if cwd == resolved_root:
+            return True
+    return False

{cc_session_tools-2.12.0 → cc_session_tools-2.12.2}/src/cc_session_tools/lib/pdata/init_service.py

@@ -32,11 +32,43 @@ class DryRunResult:
     manifest: Manifest
     report: str
     proposal_path: Path
+    # True iff --write would adopt from an existing sync dump rather than classify/import this
+    # machine's flat files - see _pending_adoption. When True, `report` already describes the
+    # adoption and no proposal file was written; `proposal_path` is still populated (where one
+    # *would* go) for callers that print it unconditionally, but shouldn't be treated as pointing
+    # at a real file.
+    would_adopt_from_dump: bool = False
 
 
 def dry_run(*, project: str, rehearse: Path | None = None) -> DryRunResult:
     project_root = init_paths.resolve_project_root(project, rehearse=rehearse)
+    proposal_path = project_root / init_paths.PROPOSAL_FILENAME
     with init_paths.project_db_dir_override(rehearse):
+        # Checked before anything below opens/creates this project's .db (repository.connect()'s
+        # own DDL does that as a side effect - see _already_locally_migrated): a dry run must
+        # never create persistent state that could itself go on to poison a later adopt-from-dump
+        # decision, which is exactly what happened before this check existed - see that
+        # function's docstring for the real incident.
+        pending = _pending_adoption(project=project, project_root=project_root)
+        if pending is not None:
+            latest_path = project_root / ".pdata-db-dump" / "latest.sql"
+            published_at = _format_published_at(pending, latest_path)
+            report = (
+                f"ccst pdata init --project {project}: a published sync dump already exists "
+                f"(from {pending.machine_id}, at {published_at}) and this machine has no local "
+                f"pdata content for this project yet.\n\n`--write` will adopt that dump directly "
+                f"(same mechanism as the ongoing sync trigger) instead of classifying/importing "
+                f"this machine's current flat files, which would create a second, disconnected "
+                f"history for this project.\n\nRun `ccst pdata init --project {project} --write` "
+                f"to adopt it."
+            )
+            return DryRunResult(
+                manifest=Manifest(project=project, entries=[]),
+                report=report,
+                proposal_path=proposal_path,
+                would_adopt_from_dump=True,
+            )
+
         # repository.connect() runs the base-schema DDL (CREATE TABLE IF NOT
         # EXISTS) on every call — this is what "safe to run against an empty
         # folder... also how a genuinely new project gets its .db" (spec §5) means.
@@ -50,7 +82,6 @@ def dry_run(*, project: str, rehearse: Path | None = None) -> DryRunResult:
         existing_record_groups = frozenset(
             str(group["record_group"]) for group in service.schema_list(project=project)
         )
-    proposal_path = project_root / init_paths.PROPOSAL_FILENAME
     m = manifest.load_or_create(
         project_root, project, proposal_path,
         existing_record_groups=existing_record_groups,
@@ -209,26 +240,40 @@ def _format_published_at(info: dump.DumpInfo, latest_path: Path) -> str:
     return dump.format_dumped_at(int(latest_path.stat().st_mtime))
 
 
-def _adopt_from_dump(
-    *, project: str, project_root: Path, on_progress: Callable[[str], None] | None,
-) -> WriteResult | None:
-    """Spec "ccst pdata init on a second machine (adopt-from-dump)": a project already migrated
-    to pdata on another machine publishes a dump into <project_root>/.pdata-db-dump/latest.sql —
-    a machine with no local .db for this project yet must adopt that dump directly (same
-    mechanism as the ongoing rehydrate trigger) rather than classifying/importing this machine's
-    current flat files as if this were a first-ever migration, which would produce a DB
-    disconnected from the dump's vector-clock history and likely duplicate content already
-    captured elsewhere.
+def _already_locally_migrated(project: str) -> bool:
+    """True iff this machine already has real pdata content for `project` - not merely an empty
+    schema-only `.db` file. `repository.connect()`'s own DDL (`CREATE TABLE IF NOT EXISTS`)
+    creates that file as a side effect of any read-only operation that opens a connection -
+    `dry_run()`'s own schema lookup, `ccst pdata verify`, and others - well before any real
+    migration ever happens on this machine. A bare `store.db_path(project).exists()` check
+    can't tell that empty file apart from a genuine prior migration, and would misread it as
+    "already migrated here" - silently and permanently skipping adopt-from-dump. Confirmed live,
+    not hypothetical: a second machine's `ccst pdata init` (no `--write`) created exactly this
+    empty file, and the very next `--write` on the same machine then skipped adoption because of
+    it, falling through to an ordinary classify/import that failed for unrelated reasons."""
+    if not store.db_path(project).exists():
+        return False
+    conn = repository.connect(project)
+    try:
+        return repository.has_any_records(conn)
+    finally:
+        conn.close()
+
 
-    Returns the early WriteResult to hand straight back from write() when adoption ran; None when
-    there is nothing to adopt (no dump has ever been published for this project — the ordinary
-    classify/import flow proceeds exactly as before this feature existed) or when this machine
-    already has its own local .db for the project (already adopted/migrated here previously —
-    ccst pdata rehydrate, not ccst pdata init, is the ongoing sync path for that case).
+def _pending_adoption(*, project: str, project_root: Path) -> dump.DumpInfo | None:
+    """Is there a published dump this machine should adopt instead of classifying/importing its
+    own flat files? Returns the validated `DumpInfo` when adoption applies; `None` when there is
+    nothing to adopt (no dump has ever been published for this project - the ordinary
+    classify/import flow proceeds exactly as before this feature existed) or this machine is
+    already genuinely migrated (see `_already_locally_migrated` - ccst pdata rehydrate, not ccst
+    pdata init, is the ongoing sync path for that case).
 
-    Checked via the dump file's own existence, not DumpInfo.checksum_valid alone: read_latest()
-    returns checksum_valid=False both when no dump was ever published and when one exists but is
-    corrupt, and those two cases must not be treated the same — the first is the ordinary
+    Shared by `dry_run()` (reports what `--write` would do) and `_adopt_from_dump()` (does it) -
+    one check, so the two can never disagree about whether adoption applies.
+
+    Checked via the dump file's own existence, not `DumpInfo.checksum_valid` alone: `read_latest`
+    returns `checksum_valid=False` both when no dump was ever published and when one exists but is
+    corrupt, and those two cases must not be treated the same - the first is the ordinary
     first-ever migration, the second is a real problem that must be surfaced, never silently
     papered over by falling through to classification."""
     latest_path = project_root / ".pdata-db-dump" / "latest.sql"
@@ -243,8 +288,26 @@ def _adopt_from_dump(
             "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 store.db_path(project).exists():
+    if _already_locally_migrated(project):
         return None
+    return info
+
+
+def _adopt_from_dump(
+    *, project: str, project_root: Path, on_progress: Callable[[str], None] | None,
+) -> WriteResult | None:
+    """Spec "ccst pdata init on a second machine (adopt-from-dump)": a project already migrated
+    to pdata on another machine publishes a dump into <project_root>/.pdata-db-dump/latest.sql —
+    a machine with no local pdata content for this project yet must adopt that dump directly
+    (same mechanism as the ongoing rehydrate trigger) rather than classifying/importing this
+    machine's current flat files as if this were a first-ever migration, which would produce a DB
+    disconnected from the dump's vector-clock history and likely duplicate content already
+    captured elsewhere. Returns the early WriteResult to hand straight back from write() when
+    adoption ran; None when `_pending_adoption` finds nothing to adopt."""
+    info = _pending_adoption(project=project, project_root=project_root)
+    if info is None:
+        return None
+    latest_path = project_root / ".pdata-db-dump" / "latest.sql"
     published_at = _format_published_at(info, latest_path)
     message = (
         f"Adopting existing pdata from sync dump (published by {info.machine_id}, "

{cc_session_tools-2.12.0 → cc_session_tools-2.12.2}/src/cc_session_tools/lib/pdata/repository.py

@@ -108,6 +108,23 @@ def get_base_record(conn: sqlite3.Connection, record_id: int) -> sqlite3.Row | N
     return row
 
 
+def has_any_records(conn: sqlite3.Connection) -> bool:
+    """True iff `records` has at least one row NOT soft-deleted. Existence check, not a count -
+    `LIMIT 1` so this stays cheap regardless of table size. Distinguishes a genuinely-populated
+    .db from an empty schema-only one that `connect()`'s own DDL can create as an incidental side
+    effect of a read-only operation, well before any real content is ever written.
+
+    Excludes soft-deleted rows deliberately, not an oversight: a rolled-back `ccst pdata init
+    --write` (`init_service._rollback`) soft-deletes every row it inserted rather than hard
+    deleting them - "no hard delete, full auditability" - so a failed write attempt leaves the
+    `records` table non-empty with nothing but tombstones. Counting those as "real content" would
+    make a failed, fully-rolled-back --write permanently block adopt-from-dump on this exact
+    machine, which is the opposite of what a rollback is supposed to mean."""
+    return conn.execute(
+        "SELECT 1 FROM records WHERE deleted_at IS NULL LIMIT 1"
+    ).fetchone() is not None
+
+
 def ensure_extension_table(conn: sqlite3.Connection, record_group: str) -> None:
     """CREATE ext_<group> (record_id INTEGER PRIMARY KEY REFERENCES records(id)) if it doesn't
     exist yet — record_group is validated by naming.extension_table_name(). Caller owns the

{cc_session_tools-2.12.0 → cc_session_tools-2.12.2}/src/cc_session_tools/lib/scheduler/jobspec.py

@@ -38,7 +38,10 @@ class JobSpec:
     success_exit_codes: tuple[int, ...] = (0,)
 
 
-def _check_id(job_id: str) -> None:
+def check_job_id(job_id: str) -> None:
+    """Boundary validator for a bare job id, used both by validate_job_fields
+    (a full spec) and by callers that only need to validate an id on its own
+    - e.g. ccsched's `rename` command, which never builds a JobSpec."""
     if not _KEBAB_RE.match(job_id):
         raise JobValidationError(
             f"invalid job id {job_id!r}: must be lowercase kebab-case [a-z0-9-], "
@@ -107,7 +110,7 @@ def validate_job_fields(
     timeout: str,
     success_exit_codes: tuple[int, ...] = (0,),
 ) -> JobSpec:
-    _check_id(job_id)
+    check_job_id(job_id)
     try:
         parse_cadence(cadence)
     except CadenceError as exc:

{cc_session_tools-2.12.0 → cc_session_tools-2.12.2}/src/cc_session_tools/lib/scheduler/ledger.py

@@ -78,6 +78,23 @@ def record(entry: LedgerEntry) -> None:
         print(f"[telemetry-warn] ledger write failed: {e}", file=sys.stderr)
 
 
+def rename_job(old_id: str, new_id: str) -> None:
+    """Repoint every catchup_events row from old_id to new_id, so `ccsched
+    status` and the surfacing pass keep showing continuous history under a
+    job's new name. Unlike record(), this raises on failure rather than
+    swallowing it - it's a foreground CLI operation (ccsched rename), not
+    best-effort logging, so a caller that already renamed the job in
+    ccsched.db needs to know if history did not follow."""
+    conn = telemetry_store.connect()
+    try:
+        conn.execute(
+            "UPDATE catchup_events SET job_id=? WHERE job_id=?", (new_id, old_id)
+        )
+        conn.commit()
+    finally:
+        conn.close()
+
+
 def read_recent(job_id: str | None = None, *, limit: int = 50) -> list[dict[str, object]]:
     """Return up to ``limit`` recent catch-up rows, oldest-first within that
     slice, optionally filtered by job_id."""

{cc_session_tools-2.12.0 → cc_session_tools-2.12.2}/src/cc_session_tools/lib/scheduler/registry.py

@@ -112,6 +112,31 @@ def set_enabled(job_id: str, enabled: bool) -> None:
         conn.close()
 
 
+def rename_job(old_id: str, new_id: str) -> None:
+    """Repoint a job's id everywhere it's a row key in ccsched.db - the `jobs`
+    spec row, its `job_state` row (so registered_at/last_success/etc. carry
+    over), and its `bundled_job_installs` row if it has one - in a single
+    transaction. Callers that also want run history to follow (telemetry.db's
+    catchup_events) call ledger.rename_job separately; the two stores are
+    never truly atomic together, matching how the rest of this package treats
+    them as independent."""
+    conn = store.connect()
+    try:
+        cur = conn.execute("UPDATE jobs SET job_id=? WHERE job_id=?", (new_id, old_id))
+        if cur.rowcount == 0:
+            conn.commit()
+            raise RegistryError(f"unknown job id: {old_id!r}")
+        conn.execute("UPDATE job_state SET job_id=? WHERE job_id=?", (new_id, old_id))
+        conn.execute(
+            "UPDATE bundled_job_installs SET job_id=? WHERE job_id=?", (new_id, old_id)
+        )
+        conn.commit()
+    except sqlite3.IntegrityError as exc:
+        raise RegistryError(f"job id already exists: {new_id!r}") from exc
+    finally:
+        conn.close()
+
+
 def mark_bundled_installed(job_id: str, installed_at: str) -> None:
     """Record that a CCST-bundled job (lib/scheduler/bundled_jobs.py) has been installed on this
     machine, so a later `ccsched remove` can be told apart from "never installed" by