cc-session-tools 2.3.0__tar.gz → 2.5.0__tar.gz

{cc_session_tools-2.3.0/src/cc_session_tools.egg-info → cc_session_tools-2.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cc-session-tools
-Version: 2.3.0
+Version: 2.5.0
 Summary: Claude Code session management CLI tools (ccd, ccr, ccs, claude-code-usage, ccst) and hook library (cccs_hooks)
 Author: raffishquartan
 License: MIT License
@@ -142,7 +142,16 @@ It runs `ccst doctor` at the end so you can see the health check immediately. Re
 > **Options:** `--from-source` reinstalls from the local clone rather than
 > PyPI. `--upgrade` forces an upgrade of an existing install.
 
-> **Note:** `install-everything.sh` handles steps 1–5 of setup. Step 6 — adding broader CCST guidance to your global `~/.claude/CLAUDE.md` (session management, 8-digit gate, etc.) — is interactive and must be run separately afterwards. See [Configure your global CLAUDE.md](#configure-your-global-claudemd) below.
+> **Note:** `install-everything.sh` does everything except one interactive step — adding broader
+> CCST guidance to your global `~/.claude/CLAUDE.md` (session management, 8-digit gate, etc.),
+> which must be run separately afterwards. See [Configure your global
+> CLAUDE.md](#configure-your-global-claudemd) below.
+
+> **After upgrading** (`uv tool install --reinstall`/`--upgrade`, or `pip`/`pipx` equivalents):
+> nothing to do. The next `ccst` command notices that the installed version doesn't match the
+> version your config was last synced to, runs `install-everything --apply` itself, and tells you
+> on stderr that it did. See [Automatic install sync](#automatic-install-sync) below for the exempt
+> commands, the `CCST_NO_AUTO_SYNC=1` escape hatch, and what happens when the sync fails.
 
 **Manual path — step by step:**
 
@@ -151,11 +160,9 @@ It runs `ccst doctor` at the end so you can see the health check immediately. Re
 uv tool install cc-session-tools          # recommended
 # pipx install cc-session-tools           # alternative
 
-# 2. Install bundled skills, hooks, and the ccl shell function (each command is
-#    idempotent — safe to re-run after upgrades)
-ccst skills install --apply               # symlinks skills into ~/.claude/skills/
-ccst hooks install --apply                # merges all bundled hooks into ~/.claude/settings.json
-ccst shell install --apply                # writes ccl() to ~/.shellrc.d/ccl.sh
+# 2. Install bundled skills, hooks, the ccl shell function, the CLAUDE.md
+#    messaging block and the scheduled jobs (idempotent — safe to re-run)
+ccst install-everything --apply
 
 # 3. Verify everything is wired up
 ccst doctor
@@ -195,10 +202,8 @@ shell (or re-source your rc file) to activate `ccl`.
 uv tool upgrade cc-session-tools          # recommended
 # pipx upgrade cc-session-tools           # alternative
 
-# 2. Pick up any new bundled skills, hooks, and shell helpers
-ccst skills install --apply
-ccst hooks install --apply
-ccst shell install --apply
+# 2. Optional — the next ccst command does this for you automatically
+ccst install-everything --apply
 
 # 3. Verify
 ccst doctor
@@ -213,6 +218,40 @@ source ~/.bashrc   # bash
 source ~/.zshrc    # zsh
 ```
 
+### Automatic install sync
+
+`uv`, `pip` and `pipx` run no code after unpacking a wheel, so nothing at install time can wire a
+newly-added skill or hook into `~/.claude`. Code is fine — skills symlinks and `ccst hooks run`
+resolve into the tools path the installer reuses in place — but *registration* isn't: a hook added
+in a newer version isn't in `settings.json` until `install-everything` runs, so it silently never
+fires.
+
+`ccst` closes that gap itself. Before dispatching any command, it compares the installed version
+against the version your config was last synced to. On a mismatch it runs the five install steps
+(skills, hooks, shell, CLAUDE.md, scheduled jobs), prints two lines to **stderr**, and then runs
+the command you actually asked for:
+
+```
+ccst: install config is out of sync (installed 2.5.0, last synced 2.4.0) — syncing…
+ccst: install config synced to 2.5.0.
+```
+
+- **Nothing is written to stdout**, so `--json` output and scripted callers are unaffected, and
+  **your command's exit code is never changed** by the sync.
+- **Exempt commands** (never trigger a sync): `ccst hooks run <verb>` (fires on every tool call in
+  every open Claude Code session), `install-everything`, `doctor`, `repair`, `migrate`, and any
+  `install`/`uninstall` verb — those are you driving install state by hand, possibly with your own
+  `--target`, and a default-target sync underneath them would be self-contradictory.
+- **`CCST_NO_AUTO_SYNC=1`** disables it entirely, for CI, bisecting, or any environment where
+  `~/.claude` must not be touched.
+- **If a sync fails** (for example `~/.claude/skills/<name>` exists as a real directory rather than
+  a symlink), the full step output is printed to stderr, the failure is remembered, and it backs
+  off for six hours rather than retrying on every command — printing one warning line each time
+  instead. `ccst doctor` reports that state as a **FAIL**, since it will not recover on its own.
+  Run `ccst install-everything --apply` to see the whole thing and fix it.
+- **If you never run `ccst` by hand**, the bundled daily `pdata-verify-all` scheduled job does, so
+  a machine syncs itself within about 24 hours with no user action.
+
 ## Configure your global CLAUDE.md
 
 This is the final required setup step — not included in `install-everything.sh` because it is interactive. Without it, Claude Code sessions have no guidance to use CCST's CLIs or skills, and the 8-digit confirmation gate has no action list to enforce.
@@ -508,7 +547,7 @@ The `send-session-message` skill guides you through choosing a recipient, compos
 
 `ccst claude-md install --apply` adds a managed proactive-messaging block to your global `~/.claude/CLAUDE.md`, telling every Claude Code session how to recognise and act on incoming message digests. `ccst claude-md uninstall --apply` removes it. Both commands are idempotent.
 
-The `install-everything.sh` script runs `ccst claude-md install --apply` automatically as part of the standard installation sequence.
+The `install-everything.sh` script runs this step for you, via `ccst install-everything --apply`, as part of the standard installation sequence.
 
 ## Scheduled-task catch-up
 
@@ -742,6 +781,10 @@ The `ccst` umbrella CLI provides hook and skill management, shell helper install
 
 ### `ccst hooks install`
 
+> You normally don't need this: `ccst install-everything --apply` runs it, and `ccst` runs that
+> for you automatically after an upgrade. Use it directly for a custom `--source`/`--hook`/
+> `--target`, or to dry-run one category on its own.
+
 Brings `~/.claude/settings.json` into line with a source `settings.json`: adds
 the hooks it is missing, and removes any entry naming a hook this build of CCST
 cannot run. With no `--source`, auto-discovers the bundled
@@ -794,6 +837,10 @@ Run a Claude Code hook by name. See the table above for the supported names.
 
 ### `ccst skills install`
 
+> You normally don't need this: `ccst install-everything --apply` runs it, and `ccst` runs that
+> for you automatically after an upgrade. Use it directly for a custom `--source`/`--target`/
+> `--force`, or to dry-run one category on its own.
+
 Symlink all bundled skills into `~/.claude/skills/`.
 
 ```sh
@@ -825,6 +872,10 @@ ccst skills uninstall --skill move-session --apply
 
 ### `ccst shell install`
 
+> You normally don't need this: `ccst install-everything --apply` runs it, and `ccst` runs that
+> for you automatically after an upgrade. Use it directly for a custom `--fragments-dir`, or to
+> dry-run one category on its own.
+
 Write a `ccl()` shell function fragment to `~/.shellrc.d/ccl.sh` (or
 `--fragments-dir`). ccst does not edit `~/.bashrc`/`~/.zshrc` directly — those
 files may be managed by something else (e.g. chezmoi). Your shell rc is
@@ -862,6 +913,10 @@ ccst shell uninstall --apply
 
 ### `ccst claude-md install`
 
+> You normally don't need this: `ccst install-everything --apply` runs it, and `ccst` runs that
+> for you automatically after an upgrade. Use it directly for a custom `--target`, or to dry-run
+> one category on its own.
+
 Add or update the inter-session-messaging block in the global `~/.claude/CLAUDE.md`. Idempotent — re-running replaces the existing block rather than appending.
 
 ```sh
@@ -884,14 +939,21 @@ ccst claude-md uninstall --apply
 
 Run a full health check: PATH for all six CLIs, env vars (`REPO_ROOT`/`PROJ_ROOT`),
 `~/.claude/settings.json` JSON validity, expected hook registrations present,
-skill symlinks correct and pointing at the installed source, version drift
-between installed `ccst` and the latest release on PyPI.
+skill symlinks correct and pointing at the installed source, whether your
+config is in sync with the installed version (WARN if not — the next `ccst`
+command fixes it; FAIL if an automatic sync already tried and failed, which
+needs you), and version drift between installed `ccst` and the latest release
+on PyPI.
 
 ```sh
 ccst doctor           # checks everything, including PyPI version check
 ccst doctor --no-pypi # skip the network version check (useful in CI)
+ccst doctor --all     # also print OK checks (default: only WARN/FAIL)
 ```
 
+By default only WARN/FAIL results are printed — a clean machine is otherwise dozens of `[OK]`
+lines to scroll past. Use `--all` to see the full check list, including everything that passed.
+
 Exit `0` if all checks are OK. Exit `1` if any check is WARN or FAIL.
 
 ### `ccst telemetry trim`

{cc_session_tools-2.3.0 → cc_session_tools-2.5.0}/README.md

@@ -85,7 +85,16 @@ It runs `ccst doctor` at the end so you can see the health check immediately. Re
 > **Options:** `--from-source` reinstalls from the local clone rather than
 > PyPI. `--upgrade` forces an upgrade of an existing install.
 
-> **Note:** `install-everything.sh` handles steps 1–5 of setup. Step 6 — adding broader CCST guidance to your global `~/.claude/CLAUDE.md` (session management, 8-digit gate, etc.) — is interactive and must be run separately afterwards. See [Configure your global CLAUDE.md](#configure-your-global-claudemd) below.
+> **Note:** `install-everything.sh` does everything except one interactive step — adding broader
+> CCST guidance to your global `~/.claude/CLAUDE.md` (session management, 8-digit gate, etc.),
+> which must be run separately afterwards. See [Configure your global
+> CLAUDE.md](#configure-your-global-claudemd) below.
+
+> **After upgrading** (`uv tool install --reinstall`/`--upgrade`, or `pip`/`pipx` equivalents):
+> nothing to do. The next `ccst` command notices that the installed version doesn't match the
+> version your config was last synced to, runs `install-everything --apply` itself, and tells you
+> on stderr that it did. See [Automatic install sync](#automatic-install-sync) below for the exempt
+> commands, the `CCST_NO_AUTO_SYNC=1` escape hatch, and what happens when the sync fails.
 
 **Manual path — step by step:**
 
@@ -94,11 +103,9 @@ It runs `ccst doctor` at the end so you can see the health check immediately. Re
 uv tool install cc-session-tools          # recommended
 # pipx install cc-session-tools           # alternative
 
-# 2. Install bundled skills, hooks, and the ccl shell function (each command is
-#    idempotent — safe to re-run after upgrades)
-ccst skills install --apply               # symlinks skills into ~/.claude/skills/
-ccst hooks install --apply                # merges all bundled hooks into ~/.claude/settings.json
-ccst shell install --apply                # writes ccl() to ~/.shellrc.d/ccl.sh
+# 2. Install bundled skills, hooks, the ccl shell function, the CLAUDE.md
+#    messaging block and the scheduled jobs (idempotent — safe to re-run)
+ccst install-everything --apply
 
 # 3. Verify everything is wired up
 ccst doctor
@@ -138,10 +145,8 @@ shell (or re-source your rc file) to activate `ccl`.
 uv tool upgrade cc-session-tools          # recommended
 # pipx upgrade cc-session-tools           # alternative
 
-# 2. Pick up any new bundled skills, hooks, and shell helpers
-ccst skills install --apply
-ccst hooks install --apply
-ccst shell install --apply
+# 2. Optional — the next ccst command does this for you automatically
+ccst install-everything --apply
 
 # 3. Verify
 ccst doctor
@@ -156,6 +161,40 @@ source ~/.bashrc   # bash
 source ~/.zshrc    # zsh
 ```
 
+### Automatic install sync
+
+`uv`, `pip` and `pipx` run no code after unpacking a wheel, so nothing at install time can wire a
+newly-added skill or hook into `~/.claude`. Code is fine — skills symlinks and `ccst hooks run`
+resolve into the tools path the installer reuses in place — but *registration* isn't: a hook added
+in a newer version isn't in `settings.json` until `install-everything` runs, so it silently never
+fires.
+
+`ccst` closes that gap itself. Before dispatching any command, it compares the installed version
+against the version your config was last synced to. On a mismatch it runs the five install steps
+(skills, hooks, shell, CLAUDE.md, scheduled jobs), prints two lines to **stderr**, and then runs
+the command you actually asked for:
+
+```
+ccst: install config is out of sync (installed 2.5.0, last synced 2.4.0) — syncing…
+ccst: install config synced to 2.5.0.
+```
+
+- **Nothing is written to stdout**, so `--json` output and scripted callers are unaffected, and
+  **your command's exit code is never changed** by the sync.
+- **Exempt commands** (never trigger a sync): `ccst hooks run <verb>` (fires on every tool call in
+  every open Claude Code session), `install-everything`, `doctor`, `repair`, `migrate`, and any
+  `install`/`uninstall` verb — those are you driving install state by hand, possibly with your own
+  `--target`, and a default-target sync underneath them would be self-contradictory.
+- **`CCST_NO_AUTO_SYNC=1`** disables it entirely, for CI, bisecting, or any environment where
+  `~/.claude` must not be touched.
+- **If a sync fails** (for example `~/.claude/skills/<name>` exists as a real directory rather than
+  a symlink), the full step output is printed to stderr, the failure is remembered, and it backs
+  off for six hours rather than retrying on every command — printing one warning line each time
+  instead. `ccst doctor` reports that state as a **FAIL**, since it will not recover on its own.
+  Run `ccst install-everything --apply` to see the whole thing and fix it.
+- **If you never run `ccst` by hand**, the bundled daily `pdata-verify-all` scheduled job does, so
+  a machine syncs itself within about 24 hours with no user action.
+
 ## Configure your global CLAUDE.md
 
 This is the final required setup step — not included in `install-everything.sh` because it is interactive. Without it, Claude Code sessions have no guidance to use CCST's CLIs or skills, and the 8-digit confirmation gate has no action list to enforce.
@@ -451,7 +490,7 @@ The `send-session-message` skill guides you through choosing a recipient, compos
 
 `ccst claude-md install --apply` adds a managed proactive-messaging block to your global `~/.claude/CLAUDE.md`, telling every Claude Code session how to recognise and act on incoming message digests. `ccst claude-md uninstall --apply` removes it. Both commands are idempotent.
 
-The `install-everything.sh` script runs `ccst claude-md install --apply` automatically as part of the standard installation sequence.
+The `install-everything.sh` script runs this step for you, via `ccst install-everything --apply`, as part of the standard installation sequence.
 
 ## Scheduled-task catch-up
 
@@ -685,6 +724,10 @@ The `ccst` umbrella CLI provides hook and skill management, shell helper install
 
 ### `ccst hooks install`
 
+> You normally don't need this: `ccst install-everything --apply` runs it, and `ccst` runs that
+> for you automatically after an upgrade. Use it directly for a custom `--source`/`--hook`/
+> `--target`, or to dry-run one category on its own.
+
 Brings `~/.claude/settings.json` into line with a source `settings.json`: adds
 the hooks it is missing, and removes any entry naming a hook this build of CCST
 cannot run. With no `--source`, auto-discovers the bundled
@@ -737,6 +780,10 @@ Run a Claude Code hook by name. See the table above for the supported names.
 
 ### `ccst skills install`
 
+> You normally don't need this: `ccst install-everything --apply` runs it, and `ccst` runs that
+> for you automatically after an upgrade. Use it directly for a custom `--source`/`--target`/
+> `--force`, or to dry-run one category on its own.
+
 Symlink all bundled skills into `~/.claude/skills/`.
 
 ```sh
@@ -768,6 +815,10 @@ ccst skills uninstall --skill move-session --apply
 
 ### `ccst shell install`
 
+> You normally don't need this: `ccst install-everything --apply` runs it, and `ccst` runs that
+> for you automatically after an upgrade. Use it directly for a custom `--fragments-dir`, or to
+> dry-run one category on its own.
+
 Write a `ccl()` shell function fragment to `~/.shellrc.d/ccl.sh` (or
 `--fragments-dir`). ccst does not edit `~/.bashrc`/`~/.zshrc` directly — those
 files may be managed by something else (e.g. chezmoi). Your shell rc is
@@ -805,6 +856,10 @@ ccst shell uninstall --apply
 
 ### `ccst claude-md install`
 
+> You normally don't need this: `ccst install-everything --apply` runs it, and `ccst` runs that
+> for you automatically after an upgrade. Use it directly for a custom `--target`, or to dry-run
+> one category on its own.
+
 Add or update the inter-session-messaging block in the global `~/.claude/CLAUDE.md`. Idempotent — re-running replaces the existing block rather than appending.
 
 ```sh
@@ -827,14 +882,21 @@ ccst claude-md uninstall --apply
 
 Run a full health check: PATH for all six CLIs, env vars (`REPO_ROOT`/`PROJ_ROOT`),
 `~/.claude/settings.json` JSON validity, expected hook registrations present,
-skill symlinks correct and pointing at the installed source, version drift
-between installed `ccst` and the latest release on PyPI.
+skill symlinks correct and pointing at the installed source, whether your
+config is in sync with the installed version (WARN if not — the next `ccst`
+command fixes it; FAIL if an automatic sync already tried and failed, which
+needs you), and version drift between installed `ccst` and the latest release
+on PyPI.
 
 ```sh
 ccst doctor           # checks everything, including PyPI version check
 ccst doctor --no-pypi # skip the network version check (useful in CI)
+ccst doctor --all     # also print OK checks (default: only WARN/FAIL)
 ```
 
+By default only WARN/FAIL results are printed — a clean machine is otherwise dozens of `[OK]`
+lines to scroll past. Use `--all` to see the full check list, including everything that passed.
+
 Exit `0` if all checks are OK. Exit `1` if any check is WARN or FAIL.
 
 ### `ccst telemetry trim`

{cc_session_tools-2.3.0 → cc_session_tools-2.5.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "cc-session-tools"
-version = "2.3.0"
+version = "2.5.0"
 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.3.0 → cc_session_tools-2.5.0}/src/cc_session_tools/cli/ccst.py

@@ -63,6 +63,7 @@ Current subcommands:
 from __future__ import annotations
 
 import argparse
+import contextlib
 import datetime
 import importlib
 import json
@@ -70,7 +71,7 @@ import os
 import sys
 from enum import Enum
 from pathlib import Path
-from typing import Any, cast
+from typing import Any, TextIO, cast
 
 from cc_session_tools import __version__
 from cc_session_tools.hooks_install import (
@@ -653,6 +654,7 @@ def _cmd_doctor(args: argparse.Namespace) -> int:
 
     from cc_session_tools.lib.pdata import verify as _pdata_verify
     from cc_session_tools.lib.pdata.init_paths import default_projects_root
+    from cc_session_tools.lib import install_sync
 
     results = run_all_checks(
         installed_version=__version__,
@@ -667,6 +669,8 @@ def _cmd_doctor(args: argparse.Namespace) -> int:
         projects_root=default_projects_root(),
         pdata_verify_projects=_pdata_verify.discover_projects(),
         sessions_db_path=store_paths["sessions"],
+        synced_version=install_sync.get_synced_version(),
+        failed_attempt=install_sync.get_failed_attempt(),
     )
 
     if args.drift or getattr(args, "mode", None) == "drift":
@@ -677,7 +681,7 @@ def _cmd_doctor(args: argparse.Namespace) -> int:
             print(report)
         return 1 if unmuted else 0
 
-    print(format_results(results))
+    print(format_results(results, show_all=getattr(args, "all", False)))
 
     any_issue = any(r.status in (Status.WARN, Status.FAIL) for r in results)
     return 1 if any_issue else 0
@@ -1239,6 +1243,8 @@ def _cmd_sessions_list(args: argparse.Namespace) -> int:
 
 
 def _cmd_repair_sessions(args: argparse.Namespace) -> int:
+    import sqlite3
+
     from cc_session_tools.lib import db as db_lib
     from cc_session_tools.lib import sessions_db, sessions_repair
     from cc_session_tools.lib.roots import RootsConfigError, load_session_roots
@@ -1250,21 +1256,32 @@ def _cmd_repair_sessions(args: argparse.Namespace) -> int:
         print(str(e), file=sys.stderr)
         return 1
 
-    if args.execute:
-        if not db_path.exists():
-            # sqlite3.connect() auto-creates an empty file, so without this check
-            # db_lib.backup_to() below would silently back up (and repair() would open)
-            # a brand-new, empty sessions.db instead of failing loudly on the mistake.
-            print(f"No sessions.db found at {db_path} — nothing to back up or repair.", file=sys.stderr)
-            return 1
-        backup_dir = db_path.parent / "repair-backups"
-        backup_dir.mkdir(parents=True, exist_ok=True)
-        stamp = datetime.datetime.now(datetime.timezone.utc).strftime("%Y%m%dT%H%M%SZ")
-        backup_path = backup_dir / f"sessions-{stamp}.db"
-        db_lib.backup_to(db_path, backup_path)
-        print(f"Backed up sessions.db to {backup_path}")
-
-    report = sessions_repair.repair(roots, path=db_path, dry_run=not args.execute)
+    # sqlite3.connect() (and the online backup API below) open lazily and
+    # only fail once a statement actually touches the file, so a corrupt-
+    # but-existing sessions.db reaches this try, not the exists() check
+    # above. This is the tool users are told to run to fix store corruption
+    # - both the backup step and the repair itself must fail loudly with a
+    # clear message here, not a raw traceback.
+    try:
+        if args.execute:
+            if not db_path.exists():
+                # sqlite3.connect() auto-creates an empty file, so without this
+                # check db_lib.backup_to() below would silently back up (and
+                # repair() would open) a brand-new, empty sessions.db instead
+                # of failing loudly on the mistake.
+                print(f"No sessions.db found at {db_path} — nothing to back up or repair.", file=sys.stderr)
+                return 1
+            backup_dir = db_path.parent / "repair-backups"
+            backup_dir.mkdir(parents=True, exist_ok=True)
+            stamp = datetime.datetime.now(datetime.timezone.utc).strftime("%Y%m%dT%H%M%SZ")
+            backup_path = backup_dir / f"sessions-{stamp}.db"
+            db_lib.backup_to(db_path, backup_path)
+            print(f"Backed up sessions.db to {backup_path}")
+
+        report = sessions_repair.repair(roots, path=db_path, dry_run=not args.execute)
+    except sqlite3.DatabaseError as exc:
+        print(f"{db_path} exists but failed to open: {exc}", file=sys.stderr)
+        return 1
     if not any((report.repaired, report.unresolved, report.ambiguous, report.conflicts)):
         print("No non-absolute project_dir rows found in sessions.db.")
         return 0
@@ -1421,17 +1438,38 @@ def _cmd_ccsched_jobs_install(args: argparse.Namespace) -> int:
 # ---------- install-everything ----------
 
 
-def _cmd_install_everything(args: argparse.Namespace) -> int:
-    """Run all install steps in sequence, then health-check."""
-    apply: bool = args.apply
-    no_pypi: bool = args.no_pypi
-
-    skills_target = getattr(args, "skills_target", None)
-    hooks_target = getattr(args, "hooks_target", None) or str(
-        Path.home() / ".claude" / "settings.json"
-    )
-    fragments_dir = getattr(args, "fragments_dir", None)
-    claude_md_target = getattr(args, "claude_md_target", None)
+def run_install_everything(
+    *,
+    apply: bool,
+    stream: TextIO,
+    health_check: bool,
+    no_pypi: bool = False,
+    skills_target: str | None = None,
+    hooks_target: str | None = None,
+    fragments_dir: str | None = None,
+    claude_md_target: str | None = None,
+) -> int:
+    """Run the five install steps, optionally followed by a health check.
+
+    Returns the worst rc the five steps produced; the health check's own rc is
+    deliberately not part of it, matching the diagnostic-not-gate role it has
+    always had here.
+
+    `stream` receives every step's progress output. The five step functions
+    print to stdout directly, so the loop runs under
+    contextlib.redirect_stdout(stream): the CLI adapter passes sys.stdout (a
+    no-op passthrough) and install_sync.ensure_synced passes a StringIO it
+    discards on success. Auto-apply must not write to stdout at all -
+    `ccst sessions list --json` emits machine-readable stdout, and
+    scheduler/worker.py carries a job's stdout into the ledger as its recorded
+    findings.
+
+    `health_check=False` is what auto-apply uses: the five steps are 16.8 ms,
+    the trailing `ccst doctor` is ~1.55 s dominated by its PyPI network call.
+    An auto-apply is not a diagnostic run and must not take a network
+    dependency on someone else's command.
+    """
+    hooks_target = hooks_target or str(Path.home() / ".claude" / "settings.json")
 
     steps: list[tuple[str, str, object]] = [
         (
@@ -1477,37 +1515,73 @@ def _cmd_install_everything(args: argparse.Namespace) -> int:
         "ccsched-jobs": _cmd_ccsched_jobs_install,
     }
 
-    # +1 accounts for the trailing health check below, which isn't itself a `steps` entry.
-    total_steps = len(steps) + 1
+    # +1 accounts for the trailing health check, which isn't itself a `steps` entry.
+    total_steps = len(steps) + (1 if health_check else 0)
     overall_rc = 0
-    for i, (label, key, step_args) in enumerate(steps, start=1):
-        print(f"\n=== {i}/{total_steps}  {label} ===")
-        rc = dispatch[key](step_args)  # type: ignore[operator]
-        if rc != 0:
-            overall_rc = rc
+    with contextlib.redirect_stdout(stream):
+        for i, (label, key, step_args) in enumerate(steps, start=1):
+            print(f"\n=== {i}/{total_steps}  {label} ===")
+            rc = dispatch[key](step_args)  # type: ignore[operator]
+            if rc != 0:
+                overall_rc = rc
+
+        if apply and overall_rc == 0:
+            import sqlite3
+
+            from cc_session_tools.lib import install_sync
+            try:
+                install_sync.record_synced(__version__)
+            except sqlite3.DatabaseError as exc:
+                # A corrupt sessions.db must not erase the five install steps'
+                # already-successful work (and their printed summary) that ran
+                # just above - print a clear warning and continue. Letting this
+                # propagate would also be self-defeating: this is the exact
+                # command the out-of-sync warning tells a user to run.
+                print(
+                    f"  warning: could not record the install-everything sync marker "
+                    f"({exc}) - sessions.db may be corrupt; run `ccst repair sessions` "
+                    "to investigate",
+                    file=sys.stderr,
+                )
 
-    print(f"\n=== {total_steps}/{total_steps}  Health check ===")
-    _cmd_doctor(
-        argparse.Namespace(
-            settings=None,
-            skills_dir=None,
-            no_pypi=no_pypi,
-            drift=False,
-            mute=None,
-            unmute=None,
-            list_mutes=False,
-            mutes_file=None,
-            mode=None,
-        )
-    )
+        if health_check:
+            print(f"\n=== {total_steps}/{total_steps}  Health check ===")
+            _cmd_doctor(
+                argparse.Namespace(
+                    settings=None,
+                    skills_dir=None,
+                    no_pypi=no_pypi,
+                    drift=False,
+                    mute=None,
+                    unmute=None,
+                    list_mutes=False,
+                    mutes_file=None,
+                    mode=None,
+                )
+            )
 
-    if not apply:
-        print("\nDry run complete — re-run with --apply to write all changes.")
-    else:
-        print("\nAll install steps complete.")
+        if not apply:
+            print("\nDry run complete — re-run with --apply to write all changes.")
+        else:
+            print("\nAll install steps complete.")
     return overall_rc
 
 
+def _cmd_install_everything(args: argparse.Namespace) -> int:
+    """argparse adapter for run_install_everything: the interactive CLI path,
+    which streams to stdout and always ends with the health check."""
+    return run_install_everything(
+        apply=args.apply,
+        stream=sys.stdout,
+        health_check=True,
+        no_pypi=args.no_pypi,
+        skills_target=getattr(args, "skills_target", None),
+        hooks_target=getattr(args, "hooks_target", None),
+        fragments_dir=getattr(args, "fragments_dir", None),
+        claude_md_target=getattr(args, "claude_md_target", None),
+    )
+
+
 # ---------- arg parser ----------
 
 
@@ -1674,6 +1748,11 @@ def _build_parser() -> argparse.ArgumentParser:
         action="store_true",
         help="Skip the PyPI version-drift check",
     )
+    doctor_parser.add_argument(
+        "--all",
+        action="store_true",
+        help="Show every check result, including OK (default: only non-OK)",
+    )
     doctor_parser.add_argument(
         "--drift",
         action="store_true",
@@ -2136,7 +2215,10 @@ def _build_parser() -> argparse.ArgumentParser:
         "install-everything",
         help=(
             "Run all install steps (skills, hooks, shell, claude-md, scheduled jobs) then "
-            "health-check. Dry run by default; pass --apply to write changes."
+            "health-check. Dry run by default; pass --apply to write changes. ccst runs "
+            "this for you automatically after an upgrade — use it directly to preview the "
+            "changes, to pass per-category target overrides, or to see why an automatic "
+            "sync failed."
         ),
     )
     ie_parser.add_argument(
@@ -2181,6 +2263,35 @@ def main() -> None:
         parser.print_help(sys.stderr)
         sys.exit(1)
 
+    from cc_session_tools.lib import install_sync
+
+    # Bring ~/.claude's registration into line with the installed version
+    # before dispatching. What goes stale on an upgrade is registration, not
+    # code: skills symlinks and `ccst hooks run`'s dynamic import both resolve
+    # into the uv tools path that --reinstall reuses in place, but a hook or
+    # skill added in a newer version isn't wired into settings.json /
+    # ~/.claude/skills until install-everything runs, so it silently never
+    # fires. Wheels have no post-install hook, so the first ccst process after
+    # an upgrade is the earliest possible moment.
+    #
+    # Cost on a carrier invocation is one readonly SQLite open/read/close,
+    # 0.56 ms against a 94 ms bare process start. `ccst hooks run <verb>` is
+    # exempt and doesn't pay even that - not for the per-call cost but for the
+    # invocation count (every tool call in every open session) and because
+    # rewriting settings.json from inside a hook Claude Code invoked from
+    # settings.json is a race no atomic write makes tidy. See
+    # install_sync.is_auto_sync_exempt for the full exempt set.
+    #
+    # Placement is after parse_args and after the usage check on purpose: an
+    # invalid command line still fails at argparse without triggering an
+    # apply, --version/--help/bare ccst never trigger one, and a successful
+    # apply is in place before the requested command runs.
+    install_sync.ensure_synced(
+        noun=args.noun,
+        verb=getattr(args, "verb", None),
+        installed_version=__version__,
+    )
+
     if args.noun == "hooks":
         if args.verb == "install":
             sys.exit(_cmd_hooks_install(args))