sessionsteward 0.1.0__py3-none-any.whl

sessionsteward/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

sessionsteward/cli.py

@@ -0,0 +1,244 @@
+"""Session steward: versioned snapshots for agent working state.
+
+Coding agents silently degrade: compaction drops constraints, and one
+"remember this" can overwrite your 30-line CLAUDE.md with a single
+bullet — no warning, no undo. sessionsteward git-versions your agent
+config + memory files on every change. Instant undo, pre-compaction
+snapshots, and a context-diet report.
+
+Scope note: this is *session ops* (snapshots, undo, compaction guard).
+Memory *storage* is OneMemory's job — the boundary stays clean.
+
+  sessionsteward init                  # set up the snapshots repo
+  sessionsteward watch --add CLAUDE.md # watch extra paths (also: ~/..., /abs/...)
+  sessionsteward snap -m "before refactor"
+  sessionsteward precompact            # snapshot before compaction
+  sessionsteward log                   # list snapshots
+  sessionsteward diff [sha1] [sha2]    # what changed (e.g. what compaction dropped)
+  sessionsteward undo                  # restore the previous snapshot
+  sessionsteward restore <sha>         # restore a specific snapshot
+  sessionsteward diet                  # what's eating the context window
+  sessionsteward install-hooks [--write]  # Claude Code hooks JSON
+  sessionsteward watch                 # daemon: auto-snapshot on change
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+import time
+
+from . import core as core_mod
+from . import diet as diet_mod
+
+VERSION = "0.1.0"
+
+CLAUDE_SETTINGS = os.path.expanduser("~/.claude/settings.json")
+
+
+def cmd_init(args) -> int:
+    repo = core_mod.init_repo()
+    print(f"snapshots repo: {repo}")
+    print("watching (defaults): " + ", ".join(core_mod.DEFAULT_WATCH))
+    print("add more: sessionsteward watch --add <path>")
+    return 0
+
+
+def cmd_watch_add(args) -> int:
+    core_mod.init_repo()
+    cfg = core_mod.load_config()
+    for p in args.add:
+        if p not in cfg["watch"]:
+            cfg["watch"].append(p)
+    core_mod.save_config(cfg)
+    print("watching: " + ", ".join(cfg["watch"] or core_mod.DEFAULT_WATCH))
+    return 0
+
+
+def cmd_snap(args) -> int:
+    sha = core_mod.snap(args.root, args.message or "manual snapshot")
+    print(f"snapshot {sha[:7]}")
+    return 0
+
+
+def cmd_precompact(args) -> int:
+    sha = core_mod.snap(args.root, "pre-compaction snapshot")
+    print(f"pre-compaction snapshot {sha[:7]} — "
+          f"`sessionsteward diff {sha[:7]}` after, to see what was dropped")
+    return 0
+
+
+def cmd_log(args) -> int:
+    if not core_mod.repo_ready():
+        print("no snapshots yet — run `sessionsteward init` first")
+        return 0
+    for s in core_mod.log(args.limit, project_root=args.root):
+        print(f"{s['sha'][:7]}  {s['date'][:16]}  {s['message']}")
+    return 0
+
+
+def cmd_diff(args) -> int:
+    if not core_mod.repo_ready():
+        print("no snapshots yet")
+        return 2
+    snaps = core_mod.log(50, project_root=args.root)
+    sha1 = args.sha1 or (snaps[1]["sha"] if len(snaps) > 1 else None)
+    sha2 = args.sha2 or "HEAD"
+    if not sha1:
+        print("only one snapshot — nothing to diff")
+        return 0
+    out = core_mod.diff(sha1, sha2)
+    kept = [ln for ln in out.splitlines() if ln[:1] in "+-"
+            and not ln.startswith(("+++", "---"))]
+    sys.stdout.write("\n".join(kept[:200]) + ("\n" if kept else "(no changes)\n"))
+    return 0
+
+
+def cmd_undo(args) -> int:
+    if not core_mod.repo_ready():
+        print("no snapshots yet")
+        return 2
+    snaps = core_mod.log(50, project_root=args.root)
+    if not snaps:
+        print("nothing to restore — no snapshots yet")
+        return 1
+    if core_mod.worktree_matches_snapshot(snaps[0]["sha"], args.root):
+        # Clean state: the current state is already snapshotted, so undo
+        # needs no pre-snap and redo is just `restore` of snaps[0].
+        if len(snaps) < 2:
+            print("only one snapshot — nothing to undo to")
+            return 0
+        target = snaps[min(args.steps, len(snaps) - 1)]["sha"]
+    else:
+        # Dirty state: snapshot it first ("pre-undo") so undo is
+        # reversible — redo is `restore` of the pre-undo snapshot.
+        core_mod.snap(args.root, "pre-undo")
+        snaps = core_mod.log(50, project_root=args.root)
+        target = snaps[min(args.steps, len(snaps) - 1)]["sha"]
+    try:
+        restored = core_mod.restore(target, project_root=args.root)
+    except core_mod.NothingToRestoreError as e:
+        print(e)
+        return 1
+    except core_mod.CrossProjectError as e:
+        print(f"error: {e}")
+        return 1
+    print(f"undone {args.steps} step(s) -> {target[:7]}")
+    for r in restored:
+        print(f"  {r}")
+    return 0
+
+
+def cmd_restore(args) -> int:
+    if not core_mod.repo_ready():
+        print("no snapshots yet")
+        return 2
+    # Validate before the pre-restore snap so a bad sha doesn't pollute log.
+    try:
+        core_mod.check_restore(args.sha, args.root)
+    except core_mod.NothingToRestoreError as e:
+        print(e)
+        return 1
+    except core_mod.CrossProjectError as e:
+        print(f"error: {e}")
+        return 1
+    # Redo support: if the current state isn't snapshotted yet, snapshot
+    # it first ("pre-restore") so the restore is reversible.
+    snaps = core_mod.log(50, project_root=args.root)
+    if snaps and not core_mod.worktree_matches_snapshot(snaps[0]["sha"],
+                                                        args.root):
+        core_mod.snap(args.root, "pre-restore")
+    restored = core_mod.restore(args.sha, project_root=args.root)
+    print(f"restored {args.sha[:7]}")
+    for r in restored:
+        print(f"  {r}")
+    return 0
+
+
+def cmd_diet(args) -> int:
+    print(diet_mod.render(diet_mod.analyze(args.root)))
+    return 0
+
+
+def cmd_install_hooks(args) -> int:
+    payload = core_mod.build_hooks_json()
+    print(json.dumps(payload, indent=2))
+    print()
+    print("Copy the JSON above into the \"hooks\" section of "
+          "~/.claude/settings.json, or re-run with --write to merge it "
+          "automatically (existing settings are preserved).")
+    print("Wiring: PreCompact -> `sessionsteward precompact`, "
+          "SessionStart -> `sessionsteward snap -m \"session start\"`.")
+    if args.write:
+        path = core_mod.write_hooks_file(CLAUDE_SETTINGS)
+        print(f"merged hooks into {path}")
+    return 0
+
+
+def cmd_watch(args) -> int:
+    core_mod.init_repo()
+    print(f"watching for changes (every {args.interval}s, Ctrl-C to stop)…")
+    mtimes = core_mod.file_mtimes(core_mod.watched_paths(args.root))
+    try:
+        while True:
+            time.sleep(args.interval)
+            now = core_mod.file_mtimes(core_mod.watched_paths(args.root))
+            if now != mtimes:
+                sha = core_mod.snap(args.root, "auto: files changed")
+                print(f"change detected -> snapshot {sha[:7]}")
+                mtimes = now
+    except KeyboardInterrupt:
+        print("\nstopped.")
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(prog="sessionsteward", description=__doc__)
+    p.add_argument("--version", action="version", version=f"%(prog)s {VERSION}")
+    p.add_argument("--root", default=os.getcwd(),
+                   help="Project root for relative watch paths.")
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    sub.add_parser("init", help="Set up the snapshots repo.")
+    wa = sub.add_parser("watch", help="Watch daemon / manage watch list.")
+    wa.add_argument("--add", nargs="+", default=None,
+                    help="Add paths to the watch list (then exit).")
+    wa.add_argument("--interval", type=float, default=5.0,
+                    help="Poll seconds for the daemon.")
+    sn = sub.add_parser("snap", help="Snapshot now.")
+    sn.add_argument("-m", "--message", default=None)
+    sub.add_parser("precompact", help="Snapshot before compaction.")
+    lg = sub.add_parser("log", help="List snapshots.")
+    lg.add_argument("--limit", type=int, default=20)
+    df = sub.add_parser("diff", help="Diff two snapshots.")
+    df.add_argument("sha1", nargs="?")
+    df.add_argument("sha2", nargs="?", default="HEAD")
+    un = sub.add_parser("undo", help="Restore the previous snapshot.")
+    un.add_argument("--steps", type=int, default=1)
+    rs = sub.add_parser("restore", help="Restore a specific snapshot.")
+    rs.add_argument("sha")
+    sub.add_parser("diet", help="Context-diet report.")
+    ih = sub.add_parser("install-hooks",
+                        help="Print (or --write) Claude Code hooks JSON.")
+    ih.add_argument("--write", action="store_true",
+                    help="Merge the hooks into ~/.claude/settings.json.")
+    return p
+
+
+def main(argv=None) -> int:
+    args = build_parser().parse_args(argv)
+    if args.cmd == "watch" and args.add:
+        return cmd_watch_add(args)
+    cmds = {
+        "init": cmd_init, "watch": cmd_watch, "snap": cmd_snap,
+        "precompact": cmd_precompact, "log": cmd_log, "diff": cmd_diff,
+        "undo": cmd_undo, "restore": cmd_restore, "diet": cmd_diet,
+        "install-hooks": cmd_install_hooks,
+    }
+    return cmds[args.cmd](args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

sessionsteward/core.py

@@ -0,0 +1,468 @@
+"""Snapshot backend: git-versions watched files. Every snap is a commit.
+
+Layout inside the snapshots repo:
+  files/<rel>          mirrored watched files
+  manifest.json        {rel: abspath} for the latest snap
+
+rel = path relative to project root, or __home/... for home files.
+"""
+
+from __future__ import annotations
+
+import fnmatch
+import json
+import os
+import shutil
+import subprocess
+import tempfile
+import time
+
+REPO_DIR = os.path.expanduser("~/.sessionsteward/snapshots")
+CONFIG_PATH = os.path.expanduser("~/.sessionsteward/config.json")
+TRASH_DIR = os.path.expanduser("~/.sessionsteward/trash")
+
+DEFAULT_WATCH = ["CLAUDE.md", ".claude", "AGENTS.md"]
+
+# Names skipped when walking watched directories (snap + watch daemon).
+# Transcripts and logs balloon the snapshots repo; they are never
+# snapshotted. `.git` is always skipped too.
+IGNORE_PATTERNS = ["*.log", "*transcript*", "__pycache__", ".git",
+                   "node_modules"]
+
+
+class StewardError(Exception):
+    """Base for clean, user-facing sessionsteward errors."""
+
+
+class NothingToRestoreError(StewardError):
+    """Raised when a snapshot has no file manifest (e.g. the init commit)."""
+
+
+class CrossProjectError(StewardError):
+    """Raised when a snapshot belongs to a different project root."""
+
+
+def _ignored_name(name: str) -> bool:
+    return any(fnmatch.fnmatch(name, pat) for pat in IGNORE_PATTERNS)
+
+
+def _norm_root(root: str | None) -> str | None:
+    if root is None:
+        return None
+    return os.path.abspath(os.path.expanduser(root))
+
+
+def _git(repo: str, *args: str) -> str:
+    p = subprocess.run(["git", "-C", repo, *args], capture_output=True,
+                       text=True, timeout=60)
+    if p.returncode != 0:
+        raise RuntimeError(f"git {' '.join(args)} failed: "
+                           f"{p.stderr.strip()[:200]}")
+    return p.stdout
+
+
+def repo_ready() -> bool:
+    return os.path.isdir(os.path.join(REPO_DIR, ".git"))
+
+
+def init_repo() -> str:
+    os.makedirs(REPO_DIR, exist_ok=True)
+    if not repo_ready():
+        _git(REPO_DIR, "init", "-qb", "main")
+        _git(REPO_DIR, "config", "user.email", "sessionsteward@local")
+        _git(REPO_DIR, "config", "user.name", "sessionsteward")
+        _git(REPO_DIR, "commit", "-q", "--allow-empty", "-m", "init")
+    if not os.path.exists(CONFIG_PATH):
+        save_config({"watch": []})
+    return REPO_DIR
+
+
+def load_config() -> dict:
+    try:
+        with open(CONFIG_PATH) as f:
+            return json.load(f)
+    except (OSError, ValueError):
+        return {"watch": []}
+
+
+def save_config(cfg: dict) -> None:
+    os.makedirs(os.path.dirname(CONFIG_PATH), exist_ok=True)
+    with open(CONFIG_PATH, "w") as f:
+        json.dump(cfg, f, indent=2)
+
+
+def watched_paths(project_root: str) -> list[str]:
+    """Absolute paths of watched files that currently exist."""
+    cfg = load_config()
+    rels = cfg.get("watch") or list(DEFAULT_WATCH)
+    out = []
+    for rel in rels:
+        if rel.startswith("~/"):
+            p = os.path.expanduser(rel)
+        elif os.path.isabs(rel):
+            p = rel
+        else:
+            p = os.path.join(project_root, rel)
+        if os.path.exists(p):
+            out.append(os.path.abspath(p))
+    return out
+
+
+def _rel(abspath: str, project_root: str) -> str:
+    home = os.path.expanduser("~")
+    if abspath == home or abspath.startswith(home + os.sep):
+        return os.path.join("__home", os.path.relpath(abspath, home))
+    try:
+        return os.path.relpath(abspath, project_root)
+    except ValueError:
+        return abspath.lstrip(os.sep).replace(os.sep, "_")
+
+
+def snap(project_root: str, message: str) -> str:
+    """Copy watched files into the repo and commit. Returns commit sha."""
+    if not repo_ready():
+        init_repo()
+    paths = watched_paths(project_root)
+    manifest = {}
+    files_dir = os.path.join(REPO_DIR, "files")
+    for ap in paths:
+        rel = _rel(ap, project_root)
+        manifest[rel] = ap
+        dest = os.path.join(files_dir, rel)
+        os.makedirs(os.path.dirname(dest), exist_ok=True)
+        if os.path.isdir(ap):
+            if os.path.exists(dest):
+                shutil.rmtree(dest)
+            shutil.copytree(ap, dest,
+                            ignore=shutil.ignore_patterns(*IGNORE_PATTERNS))
+        else:
+            shutil.copy2(ap, dest)
+    with open(os.path.join(REPO_DIR, "manifest.json"), "w") as f:
+        json.dump({"project_root": _norm_root(project_root), "files": manifest,
+                   "at": int(time.time())}, f, indent=2)
+    _git(REPO_DIR, "add", "-A")
+    # skip empty commits (nothing changed)
+    status = _git(REPO_DIR, "status", "--porcelain")
+    if not status.strip():
+        return _git(REPO_DIR, "rev-parse", "HEAD").strip()
+    _git(REPO_DIR, "commit", "-q", "-m", message)
+    return _git(REPO_DIR, "rev-parse", "HEAD").strip()
+
+
+def log(limit: int = 20, project_root: str | None = None) -> list[dict]:
+    """List snapshots, newest first.
+
+    When project_root is given, only snapshots whose manifest records
+    that project root are returned (manifest-less commits like the
+    initial `init` commit belong to no project and are excluded).
+    """
+    # When filtering by project we must scan past other projects'
+    # commits; fetch a wider window (documented bound for v1).
+    fetch = max(limit * 5, 100) if project_root else limit
+    out = _git(REPO_DIR, "log", f"-{fetch}",
+               "--pretty=format:%H|%ad|%s", "--date=iso")
+    want = _norm_root(project_root)
+    snaps = []
+    for line in out.splitlines():
+        sha, date, msg = line.split("|", 2)
+        entry = {"sha": sha, "date": date, "message": msg}
+        if want is not None:
+            m = _manifest_at(sha)
+            if not m or _norm_root(m.get("project_root")) != want:
+                continue
+            entry["project_root"] = m.get("project_root")
+        snaps.append(entry)
+        if len(snaps) >= limit:
+            break
+    return snaps
+
+
+def _manifest_at(sha: str) -> dict:
+    try:
+        raw = _git(REPO_DIR, "show", f"{sha}:manifest.json")
+    except RuntimeError:
+        return {}
+    return json.loads(raw)
+
+
+def _read_snapshot_file(sha: str, rel: str) -> tuple[bytes | None, bool]:
+    """(content, is_dir) for files/<rel> at sha."""
+    ls = _git(REPO_DIR, "ls-tree", sha, f"files/{rel}").strip()
+    if not ls:
+        return None, False
+    if ls.startswith("040000"):
+        return None, True
+    p = subprocess.run(["git", "-C", REPO_DIR, "show", f"{sha}:files/{rel}"],
+                       capture_output=True, timeout=60)
+    return (p.stdout if p.returncode == 0 else None), False
+
+
+def _move_to_trash(ap: str, trash_dir: str) -> str:
+    """Move a path into the trash dir; returns the trash destination."""
+    os.makedirs(trash_dir, exist_ok=True)
+    base = os.path.basename(ap) + f".{int(time.time())}"
+    dest = os.path.join(trash_dir, base)
+    n = 1
+    while os.path.lexists(dest):
+        n += 1
+        dest = os.path.join(trash_dir, f"{base}.{n}")
+    shutil.move(ap, dest)
+    return dest
+
+
+def check_restore(sha: str, project_root: str | None = None) -> dict:
+    """Validate that sha is restorable for project_root.
+
+    Returns the snapshot's manifest. Raises NothingToRestoreError for a
+    manifest-less snapshot (e.g. the `init` commit) or an unknown sha,
+    and CrossProjectError when project_root is given and the snapshot
+    belongs to a different project.
+    """
+    manifest = _manifest_at(sha)
+    if not manifest:
+        p = subprocess.run(
+            ["git", "-C", REPO_DIR, "rev-parse", "--verify", "--quiet",
+             f"{sha}^{{commit}}"], capture_output=True, timeout=60)
+        if p.returncode == 0:
+            raise NothingToRestoreError(
+                f"nothing to restore — no snapshots yet "
+                f"(snapshot {sha[:7]} has no file manifest)")
+        raise NothingToRestoreError(f"no such snapshot: {sha[:7]}")
+    if project_root is not None:
+        want = _norm_root(project_root)
+        got = _norm_root(manifest.get("project_root"))
+        if got != want:
+            raise CrossProjectError(
+                f"refusing cross-project restore: snapshot {sha[:7]} "
+                f"belongs to project {manifest.get('project_root')!r}, "
+                f"not the current project {want!r}")
+    return manifest
+
+
+def _dir_matches(sha: str, rel: str, ap: str) -> bool:
+    """True if the on-disk dir matches the snapshot's recorded tree."""
+    if not os.path.isdir(ap) or os.path.islink(ap):
+        return False
+    prefix = f"files/{rel}/"
+    snap_names = set()
+    for line in _git(REPO_DIR, "ls-tree", "-r", "--name-only",
+                     sha, f"files/{rel}").splitlines():
+        if line.startswith(prefix):
+            snap_names.add(line[len(prefix):])
+    disk_names = set()
+    for root, dirs, files in os.walk(ap):
+        dirs[:] = [d for d in dirs if not _ignored_name(d)]
+        for fn in files:
+            if _ignored_name(fn):
+                continue
+            fp = os.path.join(root, fn)
+            name = os.path.relpath(fp, ap)
+            disk_names.add(name)
+            p = subprocess.run(
+                ["git", "-C", REPO_DIR, "show", f"{sha}:{prefix}{name}"],
+                capture_output=True, timeout=60)
+            if p.returncode != 0:
+                return False
+            try:
+                with open(fp, "rb") as f:
+                    if f.read() != p.stdout:
+                        return False
+            except OSError:
+                return False
+    return snap_names == disk_names
+
+
+def worktree_matches_snapshot(sha: str, project_root: str) -> bool:
+    """True if the current watched files are byte-identical to the
+    snapshot's recorded state (redo is possible without a pre-snap)."""
+    manifest = _manifest_at(sha)
+    if not manifest:
+        return False
+    snap_files = manifest.get("files", {})
+    current = {os.path.abspath(p) for p in watched_paths(project_root)}
+    if set(snap_files.values()) != current:
+        return False
+    for rel, ap in snap_files.items():
+        data, is_dir = _read_snapshot_file(sha, rel)
+        if is_dir:
+            if not _dir_matches(sha, rel, ap):
+                return False
+        elif data is None:
+            return False
+        else:
+            try:
+                with open(ap, "rb") as f:
+                    if f.read() != data:
+                        return False
+            except OSError:
+                return False
+    return True
+
+
+def _latest_manifest_for_project(project_root: str | None) -> dict:
+    """Manifest of the newest snapshot, scoped to project_root.
+
+    The snapshots repo is shared between projects, so global HEAD may
+    belong to a different project. The trash sweep in restore() must
+    compare extra files against the current project's latest state,
+    never another project's — otherwise undo in project A would yank
+    project B's watched files into trash. Returns {} when no snapshot
+    exists for the project; when project_root is None (unscoped API
+    use) falls back to the global HEAD manifest (legacy behavior).
+    """
+    if project_root is None:
+        return _manifest_at("HEAD")
+    snaps = log(1, project_root=project_root)
+    if not snaps:
+        return {}
+    return _manifest_at(snaps[0]["sha"])
+
+
+def restore(sha: str, trash_dir: str | None = None,
+            project_root: str | None = None) -> list[str]:
+    """Restore watched files from a snapshot. Files that exist now but
+    didn't in the snapshot are moved to trash instead of deleted —
+    directories included (never `rmtree`'d).
+
+    Raises NothingToRestoreError for a manifest-less snapshot (e.g. the
+    `init` commit) and CrossProjectError when project_root is given and
+    the snapshot belongs to a different project.
+    """
+    manifest = check_restore(sha, project_root)
+    restored = []
+    # Scope the extra-file sweep to the current project: global HEAD may
+    # belong to another project, and sweeping against it would trash
+    # that project's watched files (cross-project clobbering).
+    latest = _latest_manifest_for_project(project_root)
+    trash_dir = trash_dir or TRASH_DIR
+    for rel, ap in latest.get("files", {}).items():
+        if rel not in manifest["files"] and os.path.lexists(ap):
+            dest = _move_to_trash(ap, trash_dir)
+            restored.append(f"moved {ap} -> {dest}")
+    for rel, ap in manifest["files"].items():
+        data, is_dir = _read_snapshot_file(sha, rel)
+        if is_dir:
+            tmp = tempfile.mkdtemp(prefix="steward-restore-")
+            try:
+                arch = subprocess.run(
+                    ["git", "-C", REPO_DIR, "archive", sha, f"files/{rel}"],
+                    capture_output=True, timeout=60)
+                if arch.returncode != 0:
+                    continue
+                subprocess.run(["tar", "-x", "-C", tmp], input=arch.stdout,
+                               capture_output=True, timeout=60)
+                src = os.path.join(tmp, "files", rel)
+                if os.path.lexists(ap):
+                    # Never delete: move the existing path (dir, file or
+                    # link) to trash before restoring the snapshot copy.
+                    dest = _move_to_trash(ap, trash_dir)
+                    restored.append(f"moved {ap} -> {dest}")
+                shutil.copytree(src, ap)
+                restored.append(ap)
+            finally:
+                shutil.rmtree(tmp, ignore_errors=True)
+        elif data is not None:
+            os.makedirs(os.path.dirname(ap), exist_ok=True)
+            with open(ap, "wb") as f:
+                f.write(data)
+            restored.append(ap)
+    return restored
+
+
+def diff(sha1: str, sha2: str = "HEAD") -> str:
+    return _git(REPO_DIR, "diff", f"{sha1}..{sha2}", "--", "files/")
+
+
+def file_mtimes(paths: list[str]) -> dict[str, float]:
+    mtimes = {}
+    for ap in paths:
+        if os.path.isdir(ap):
+            for root, dirs, files in os.walk(ap):
+                dirs[:] = [d for d in dirs if not _ignored_name(d)]
+                for fn in files:
+                    if _ignored_name(fn):
+                        continue
+                    fp = os.path.join(root, fn)
+                    try:
+                        mtimes[fp] = os.path.getmtime(fp)
+                    except OSError:
+                        pass
+        elif os.path.exists(ap):
+            mtimes[ap] = os.path.getmtime(ap)
+    return mtimes
+
+
+# ---------------------------------------------------------------------------
+# Claude Code hook wiring (`install-hooks`)
+# ---------------------------------------------------------------------------
+
+HOOK_PRECOMPACT_CMD = "sessionsteward precompact"
+HOOK_SESSIONSTART_CMD = 'sessionsteward snap -m "session start"'
+
+
+def build_hooks_json() -> dict:
+    """The hooks payload for Claude Code's settings.json `hooks` section."""
+    return {
+        "hooks": {
+            "PreCompact": [
+                {"matcher": "",
+                 "hooks": [{"type": "command",
+                            "command": HOOK_PRECOMPACT_CMD}]}
+            ],
+            "SessionStart": [
+                {"matcher": "",
+                 "hooks": [{"type": "command",
+                            "command": HOOK_SESSIONSTART_CMD}]}
+            ],
+        }
+    }
+
+
+def _hook_commands(entries: list) -> list[str]:
+    """Extract command strings from hook entries, defensively."""
+    cmds = []
+    for e in entries:
+        if not isinstance(e, dict):
+            continue
+        for h in e.get("hooks", []) or []:
+            if isinstance(h, dict) and "command" in h:
+                cmds.append(h["command"])
+    return cmds
+
+
+def merge_hooks(settings: dict) -> dict:
+    """Merge our hooks into a settings dict without clobbering anything.
+
+    Existing keys, events and hook entries are preserved; our entries are
+    appended only if no existing entry already runs the same command
+    (re-running is idempotent).
+    """
+    ours = build_hooks_json()["hooks"]
+    hooks = settings.setdefault("hooks", {})
+    for event, entries in ours.items():
+        existing = hooks.setdefault(event, [])
+        have = set(_hook_commands(existing))
+        for entry in entries:
+            cmd = entry["hooks"][0]["command"]
+            if cmd in have:
+                continue
+            existing.append(entry)
+            have.add(cmd)
+    return settings
+
+
+def write_hooks_file(settings_path: str) -> str:
+    """Merge hooks into the settings file at settings_path. Returns it."""
+    try:
+        with open(settings_path) as f:
+            settings = json.load(f)
+    except (OSError, ValueError):
+        settings = {}
+    if not isinstance(settings, dict):
+        settings = {}
+    merge_hooks(settings)
+    os.makedirs(os.path.dirname(settings_path) or ".", exist_ok=True)
+    with open(settings_path, "w") as f:
+        json.dump(settings, f, indent=2)
+        f.write("\n")
+    return settings_path

sessionsteward/diet.py

@@ -0,0 +1,86 @@
+"""Context diet: what's eating the agent's context window.
+
+Reports per-file sizes and finds duplicated content across watched
+files — the usual bloat: the same instructions pasted into CLAUDE.md,
+.claude/, and the project README.
+"""
+
+from __future__ import annotations
+
+import os
+from collections import Counter
+
+from . import core as core_mod
+
+MIN_LINE_LEN = 40  # ignore short lines when hunting duplicates
+
+
+def _read_text(path: str) -> str | None:
+    try:
+        with open(path, encoding="utf-8", errors="replace") as f:
+            return f.read()
+    except OSError:
+        return None
+
+
+def _all_files(paths: list[str]) -> list[str]:
+    out = []
+    for ap in paths:
+        if os.path.isdir(ap):
+            for root, dirs, files in os.walk(ap):
+                dirs[:] = [d for d in dirs if d != ".git"]
+                out.extend(os.path.join(root, f) for f in files)
+        elif os.path.isfile(ap):
+            out.append(ap)
+    return out
+
+
+def analyze(project_root: str, top_dupes: int = 10) -> dict:
+    paths = core_mod.watched_paths(project_root)
+    files = _all_files(paths)
+    per_file = []
+    line_owners: dict[str, set[str]] = {}
+    for fp in files:
+        text = _read_text(fp)
+        if text is None:
+            continue
+        lines = text.splitlines()
+        per_file.append({"path": fp, "chars": len(text), "lines": len(lines)})
+        seen = set()
+        for ln in lines:
+            s = ln.strip()
+            if len(s) >= MIN_LINE_LEN and s not in seen:
+                seen.add(s)
+                line_owners.setdefault(s, set()).add(fp)
+    dupes = [{"line": ln[:100], "files": sorted(owners), "count": len(owners)}
+             for ln, owners in line_owners.items() if len(owners) > 1]
+    dupes.sort(key=lambda d: (-d["count"], -len(d["line"])))
+    per_file.sort(key=lambda f: -f["chars"])
+    total = sum(f["chars"] for f in per_file)
+    return {"files": per_file, "total_chars": total,
+            "duplicates": dupes[:top_dupes],
+            "n_duplicates": len(dupes)}
+
+
+def render(report: dict) -> str:
+    lines = ["\n# Context diet\n",
+             f"Watched files: {len(report['files'])}, "
+             f"total ~{report['total_chars']:,} chars "
+             f"(~{report['total_chars'] // 4:,} tokens)\n",
+             "## Biggest files",
+             "| file | chars | lines |",
+             "|---|---|---|"]
+    for f in report["files"][:10]:
+        lines.append(f"| `{f['path']}` | {f['chars']:,} | {f['lines']} |")
+    lines.append("")
+    if report["duplicates"]:
+        lines.append(f"## Duplicated content "
+                     f"({report['n_duplicates']} lines in 2+ files)")
+        for d in report["duplicates"]:
+            lines.append(f"- _{d['line']}_ …")
+            for fp in d["files"]:
+                lines.append(f"  - `{fp}`")
+    else:
+        lines.append("No significant duplication across watched files. 🎉")
+    lines.append("")
+    return "\n".join(lines)

sessionsteward-0.1.0.dist-info/METADATA

@@ -0,0 +1,130 @@
+Metadata-Version: 2.4
+Name: sessionsteward
+Version: 0.1.0
+Summary: Versioned snapshots for agent working state: instant undo for CLAUDE.md and friends.
+Author: Calas Automations Inc.
+License: MIT
+Project-URL: Homepage, https://github.com/calasdan-sketch/sessionsteward
+Project-URL: Issues, https://github.com/calasdan-sketch/sessionsteward/issues
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# Session Steward (`sessionsteward`)
+
+Versioned snapshots for agent working state. Coding agents silently
+degrade: compaction drops constraints, and one "remember this" can
+overwrite your 30-line CLAUDE.md with a single bullet — no warning, no
+undo. sessionsteward git-versions your agent config + memory files on
+every change: instant undo, pre-compaction snapshots, and a context-diet
+report showing what's eating the window.
+
+**Scope:** session *ops* (snapshots, undo, compaction guard) — not memory
+*storage*. That boundary stays clean.
+
+## Install
+
+Zero dependencies — Python 3.10+ stdlib only (uses your system's git).
+
+```bash
+git clone <repo> && cd sessionsteward
+# no-install alias (run from the repo root):
+alias sessionsteward="python3 -m sessionsteward"
+```
+
+Or install it properly (console script `sessionsteward`):
+
+```bash
+pip install .
+```
+
+## Usage
+
+```bash
+sessionsteward init                        # set up the snapshots repo
+sessionsteward watch --add NOTES.md ~/x.md # watch extra paths
+
+sessionsteward snap -m "before refactor"   # snapshot now
+sessionsteward precompact                  # snapshot before compaction
+sessionsteward watch                       # daemon: auto-snapshot on change
+
+sessionsteward log                         # list snapshots (this project only)
+sessionsteward diff                        # what changed (e.g. what compaction dropped)
+sessionsteward undo                        # restore the previous snapshot
+sessionsteward restore <sha>               # restore a specific snapshot
+sessionsteward diet                        # what's eating the context window
+sessionsteward install-hooks               # print Claude Code hooks JSON
+sessionsteward install-hooks --write       # merge it into ~/.claude/settings.json
+```
+
+The horror-story scenario, fixed:
+
+```bash
+$ sessionsteward snap -m "before letting the agent edit memory"
+$ # agent overwrites your 30-line CLAUDE.md with one bullet
+$ sessionsteward undo
+undone 1 step(s) -> a3f9c21
+  /home/you/proj/CLAUDE.md
+```
+
+Safety rules: empty snaps are skipped (no noise commits); `undo`/`restore`
+never delete — files that didn't exist in the target snapshot are moved to
+`~/.sessionsteward/trash/` instead, **directories included**.
+`log`/`diff`/`undo`/`restore` are scoped to the current project (`--root`,
+default: cwd): snapshots record their project root, and a `restore` of a
+snapshot from another project is refused rather than clobbering your files.
+Undoing (or restoring) with unsaved changes first snapshots the current
+state as `pre-undo`/`pre-restore`, so every undo is reversible — redo is
+`restore` of that snapshot.
+
+Ignored on every snap and by the watch daemon: `*.log`, `*transcript*`,
+`__pycache__`, `.git`, `node_modules` (transcripts would otherwise balloon
+the snapshots repo).
+
+## Claude Code hooks
+
+```bash
+sessionsteward install-hooks            # print the hooks JSON + where it goes
+sessionsteward install-hooks --write   # merge into ~/.claude/settings.json
+```
+
+This wires **PreCompact** → `sessionsteward precompact` and **SessionStart**
+→ `sessionsteward snap -m "session start"`. `--write` merges into the
+existing settings file without clobbering your other hooks (re-running is
+a no-op).
+
+## Context diet
+
+```
+# Context diet
+
+Watched files: 3, total ~12,400 chars (~3,100 tokens)
+
+## Biggest files
+| file | chars | lines |
+...
+## Duplicated content (4 lines in 2+ files)
+- _Be helpful and concise in all responses_ …
+  - `/proj/CLAUDE.md`
+  - `/proj/.claude/settings.json`
+```
+
+## Suggested hook wiring
+
+- **Pre-compaction:** run `sessionsteward precompact` (or add it to your
+  agent's pre-compact hook) — then `sessionsteward diff` afterwards to see
+  exactly what the compaction dropped.
+- **Session start:** `sessionsteward snap -m "session start"`.
+- **Memory writes:** point the steward at the same files your agent's
+  memory hook writes.
+
+## Tests
+
+```bash
+python3 -m unittest discover -s tests   # 24 tests, temp dirs only
+```
+
+## License
+
+TBD

sessionsteward-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+sessionsteward/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+sessionsteward/__main__.py,sha256=MHKZ_ae3fSLGTLUUMOx15fWdeOnJSHhq-zslRP5F5Lc,79
+sessionsteward/cli.py,sha256=--QdBFFarCGVYYhX_OFPtNTgm3K0kF4xC45qME2490Y,9158
+sessionsteward/core.py,sha256=r8cep6Sh2qC54ax47Au9YV53HjqHKAi9etE1jDxfMAI,16917
+sessionsteward/diet.py,sha256=O6UTsnlxXqoK_TGtrc_I6ODJVnCMBuX3pb5VeI4VMQc,2954
+sessionsteward-0.1.0.dist-info/licenses/LICENSE,sha256=f-qFLkEfvZidBgKv2YINOOKS7Trk_gj1c6Cy718D8F0,1079
+sessionsteward-0.1.0.dist-info/METADATA,sha256=9bRlF8LQcG_oDtejtwnkk3IVRIp8kveR8GuEeYUL46A,4463
+sessionsteward-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+sessionsteward-0.1.0.dist-info/entry_points.txt,sha256=Ou0wQQdM0Hci2C4bC672mdMFu3oftX7uff5y7L3opCc,59
+sessionsteward-0.1.0.dist-info/top_level.txt,sha256=nwNSjQxhH7HmIuDQgWqPLgxnN4xVoPOKmWfDyuJxRDk,15
+sessionsteward-0.1.0.dist-info/RECORD,,

sessionsteward-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

sessionsteward-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+sessionsteward = sessionsteward.cli:main

sessionsteward-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Calas Automations Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

sessionsteward-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+sessionsteward