cc-continuity 0.1.0__tar.gz

cc_continuity-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Eralp Erat
+
+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.

cc_continuity-0.1.0/PKG-INFO

@@ -0,0 +1,7 @@
+Metadata-Version: 2.4
+Name: cc-continuity
+Version: 0.1.0
+Summary: Zero-touch session rotation for Claude Code (local large-context model)
+Requires-Python: >=3.11
+License-File: LICENSE
+Dynamic: license-file

cc_continuity-0.1.0/README.md

@@ -0,0 +1,192 @@
+# cc-continuity
+
+Zero-touch session rotation and supervision for Claude Code.
+
+Long Claude Code sessions die when the context window fills up: the model
+forgets the plan and the user re-types it. cc-continuity watches the
+context ratio and, when it crosses a threshold, rotates the session with
+no user action:
+
+1. the agent finishes the current step,
+2. cc-continuity makes it write a validated handoff,
+3. the git tree is snapshotted non-invasively (`refs/continuity/*` refs —
+   no commits, no tags, no branches touched),
+4. the context is cleared and the session renamed,
+5. a continuation prompt is injected and the successor session starts
+   with `Continuing from cp-<NNN> (<slug>-<NNN+1>).`
+
+An optional launchd **watchdog** keeps long unattended runs recoverable
+when the model server (for example a local vLLM box) dies or freezes, and
+optional **ntfy** pushes let you watch from your phone.
+
+## How it works
+
+The whole flow in one picture — the automatic session loop, the optional
+watchdog, and the opt-in notifications:
+
+![cc-continuity flow: session loop, watchdog, notifications](docs/diagrams/flow.en.png)
+
+## Requirements
+
+- macOS (v1 — Linux/systemd is a documented seam, not yet implemented)
+- Python ≥ 3.11 (standard library only at runtime)
+- tmux, zsh, curl on PATH
+- Claude Code ≥ 2.1.209
+
+## Quick start
+
+From Git:
+
+```bash
+git clone https://github.com/pqant/claude-continuity
+cd claude-continuity
+python3 -m cc_continuity.cli install --window 262144
+exec zsh                 # reload the shell (claude() wrapper)
+cc-continuity doctor     # everything should be green
+```
+
+From PyPI:
+
+```bash
+pip install cc-continuity
+cc-continuity install
+exec zsh
+cc-continuity doctor
+```
+
+The installer touches (all as identifiable managed blocks, all reversible
+via `cc-continuity uninstall`): hooks + status line in
+`~/.claude/settings.json`, a managed block in `~/.claude/CLAUDE.md`, the
+`claude()` wrapper in `~/.zshrc`, six `/continuity-*` skills, the
+`cc-continuity` launcher on PATH, and the app copy in
+`~/.claude-continuity/app/`. A timestamped backup of
+`settings.json` is written before any merge.
+
+## Daily use
+
+```bash
+cd ~/anything
+claude                 # auto-tmux, session named <project>-001
+```
+
+Watch the status line: the context ratio climbs (default thresholds
+**55% warn → 62% rotate → 72% hard ceiling**). Rotation is zero-touch
+(quick-start list above). After a crash, sleep, or reboot: just run
+`claude` in the project and say "continue".
+
+In-session commands: `/continuity-status`, `/continuity-checkpoint`,
+`/continuity-rotate`, `/continuity-off` / `/continuity-on`,
+`/continuity-history`. Full CLI reference: `docs/USAGE.md`.
+
+## Configuration
+
+Global: `~/.claude-continuity/config.json` — start from
+`config.example.json` (all keys, placeholder values). Per-project
+override: `.claude/continuity.json` (e.g. `{"enabled": false}` to opt one
+project out). `CC_CONTINUITY=0` disables everything for one launch.
+
+## Notifications (ntfy, opt-in)
+
+cc-continuity can push lifecycle events to any ntfy-compatible server, so
+you can watch long unattended runs from your phone:
+
+```bash
+cc-continuity configure --ntfy https://ntfy.sh/your-topic   # or at install: --ntfy <url>
+cc-continuity configure --ntfy off
+```
+
+`cc-continuity doctor` sends a test message to verify the endpoint.
+
+| Event | Title | Meaning |
+|---|---|---|
+| start | `▶ session started` | a session registered itself (first hook or resume claim) |
+| warn | `⚠ context warning` | ratio crossed the warning threshold |
+| pending | `◆ rotation pending` | ratio crossed the hard threshold; rotates at turn end |
+| verified | `✓ handoff written & verified` | checkpoint finalized, sha256 verified |
+| complete | `🔄 rotation complete` | the successor session is running |
+| resumed | `↻ resumed` | successor consumed the checkpoint |
+| blocked | `🛑 BLOCKED — waiting for you` | agent hit a needs-human point (urgent) |
+| done | `✅ task complete` | agent finished the task you gave it |
+| error | `✗ … failed` | a lifecycle step failed (urgent) |
+| end | `■ session ended` | SessionEnd (rotation, /clear, or close) |
+
+**Privacy:** a push is a title + a body of at most 200 characters
+containing only the project slug, session number, context ratio, a short
+reason/summary you control, and the hostname. No file contents, no
+prompts, no secrets — recorded text is secret-redacted on the way out.
+Messages only ever go to the endpoint YOU configure, and only when
+`notify_enabled` is on.
+
+## Unattended mode (opt-in)
+
+> **⚠️ Loud warning:** `launch --unattended` (or
+> `config.json: "unattended": true` for a whole project) spawns the
+> session with `claude --dangerously-skip-permissions`: the agent edits
+> files and runs commands **without per-action approval**. Use it only
+> on machines/projects you trust with that. The `needs-human` mechanism
+> (below) is the declared safety valve, and the default mode is
+> unchanged — nothing skips permissions unless you opt in.
+
+```bash
+claude --unattended            # via the zsh wrapper (one launch)
+cc-continuity launch --unattended
+cc-continuity configure --unattended    # project setting (whole chain)
+```
+
+Because a rotation is a `/clear` inside the same process, one flag (or
+one project setting) carries the entire rotation chain — every successor
+session stays unattended.
+
+## When it blocks on you
+
+The agent signals you when it cannot safely continue (a
+destructive/irreversible operation, an ambiguous requirement, the same
+fix failing three times):
+
+```bash
+cc-continuity signal needs-human "<short reason>"
+```
+
+That pushes an **urgent** notification and marks the status line
+`⛔ BLOCKED` (machine-side truth, visible on any later attach). Remote
+in to the pane, reply in the session; the block clears on your next
+prompt. On completion the agent runs:
+
+```bash
+cc-continuity signal done "<one-line summary>"
+```
+
+## Watchdog (opt-in)
+
+A launchd daemon that keeps long runs recoverable: a health probe for
+your model server (2-fail debounce), per-session liveness classification,
+a bounded nudge state machine (the session is told WHY its turn stopped),
+an exit-hang killer, frozen-turn escalation, and optional auto
+power-cycle of the box + a log digest relayed into the active session.
+Off by default; the health URL is yours to supply. Details:
+`docs/WATCHDOG.md`.
+
+## Security
+
+Read `SECURITY.md` before installing — it states the trust model: what
+code runs with your rights, what the installer merges and how it
+uninstalls, and what data ever leaves the machine.
+
+## Limitations
+
+See `LIMITATIONS.md` (an honest list).
+
+## Development
+
+```bash
+python3 -m pytest -q     # unit + contract tests
+```
+
+Tests redirect all state through `CC_CONTINUITY_HOME` (a temp dir) and
+use throwaway git repos; they never touch the real
+`~/.claude-continuity` or `~/.claude`. Architecture:
+`docs/ARCHITECTURE.md`.
+
+## License
+
+MIT — see `LICENSE`.

cc_continuity-0.1.0/cc_continuity/__init__.py

@@ -0,0 +1,7 @@
+"""cc-continuity — zero-touch session rotation for Claude Code.
+
+Spec: docs/PRD.md (v1.0). Platform facts verified in docs/VERIFICATION.md.
+Standard library only at runtime; pytest is dev-only.
+"""
+
+__version__ = "0.1.0"

cc_continuity-0.1.0/cc_continuity/__main__.py

@@ -0,0 +1,8 @@
+"""``python -m cc_continuity`` → the cc-continuity CLI (PRD §16)."""
+
+import sys
+
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

cc_continuity-0.1.0/cc_continuity/atomic.py

@@ -0,0 +1,62 @@
+"""Race-safe file writes (PRD §14: write temp → fsync → os.replace).
+
+Hooks run concurrently (a single model message can fire many parallel tool
+calls — Phase 0, S1/N1), so every write goes through a unique temp file in the
+same directory, is fsync'd, then swapped into place with ``os.replace``. A
+reader always sees either the old or the new complete content, never a torn
+mix. A crash may leave a ``.<name>.*.tmp`` residue; ``doctor`` cleans those.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import tempfile
+from pathlib import Path
+
+
+def fsync_dir(path: Path) -> None:
+    """fsync a directory so the rename itself is durable (best effort)."""
+    try:
+        dfd = os.open(path, os.O_RDONLY)
+    except OSError:
+        return
+    try:
+        os.fsync(dfd)
+    except OSError:
+        pass
+    finally:
+        os.close(dfd)
+
+
+def atomic_write(path: str | Path, data: bytes) -> None:
+    """Atomically write ``data`` to ``path``. Parent directory must exist."""
+    path = Path(path)
+    parent = path.parent
+    fd, tmp_name = tempfile.mkstemp(
+        prefix=f".{path.name}.", suffix=".tmp", dir=parent
+    )
+    try:
+        with os.fdopen(fd, "wb") as f:
+            f.write(data)
+            f.flush()
+            os.fsync(f.fileno())
+        os.replace(tmp_name, path)
+    except BaseException:
+        # "Crash" mid-write: never leave the target half-updated; drop the temp.
+        try:
+            os.unlink(tmp_name)
+        except OSError:
+            pass
+        raise
+    fsync_dir(parent)
+
+
+def atomic_write_text(path: str | Path, text: str, encoding: str = "utf-8") -> None:
+    atomic_write(path, text.encode(encoding))
+
+
+def atomic_write_json(path: str | Path, obj: object, indent: int = 2) -> None:
+    """Write a JSON document atomically (2-space indent, trailing newline)."""
+    text = json.dumps(obj, indent=indent, ensure_ascii=False) + "\n"
+    atomic_write_text(path, text)

cc_continuity-0.1.0/cc_continuity/bootstrap.py

@@ -0,0 +1,274 @@
+"""Bootstrap / claim in the new session (PRD §9 SessionStart, §12, §18).
+
+``try_claim`` (caller holds the project lock) finds the latest session in a
+claimable state (``ROTATING`` / ``AWAITING_MANUAL_CLEAR`` /
+``CHECKPOINT_VERIFIED``, ``successor`` unset — plan P6-D2), creates the
+successor session record (``BOOTSTRAPPING``), marks the old session claimed
+(``successor`` set) and moves it to ``ROTATED`` (terminal), consumes the
+matching checkpoint, runs ``validate_checkpoint`` (PRD §12) and returns the
+C.4 bootstrap text. Called from the ``SessionStart(clear)`` hook and from
+the ``UserPromptSubmit`` ``CONTINUITY RESUME`` fallback (P6-D5).
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+from datetime import datetime, timezone
+from pathlib import Path
+
+from . import (atomic, checkpoint, ledger, naming, notify, paths,
+               project, state, thresholds, validate)
+
+
+def _now() -> str:
+    return datetime.now(timezone.utc).replace(microsecond=0).isoformat()
+
+
+#: States from which SessionStart(clear) may claim a rotation (P6-D2: CV
+#: included so a manual /clear after checkpoint verification — e.g. after a
+#: failed injection, PRD §18 — still bootstraps).
+CLAIMABLE_STATES = frozenset({
+    "ROTATING", "AWAITING_MANUAL_CLEAR", "CHECKPOINT_VERIFIED",
+})
+
+
+def find_claimable(key: str) -> dict | None:
+    """The latest project session a claim may take over (P6-D2).
+
+    Caller holds the project lock. Returns the state record, or None.
+    A project with no record yet (first /clear before any registration,
+    P6-D3) and sessions whose state file is missing (crash residue) are
+    skipped.
+    """
+    pfile = paths.project_dir(key) / "project.json"
+    try:
+        pref = json.loads(pfile.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return None
+    best = None
+    for s in pref.get("sessions") or []:
+        try:
+            rec = state.load_state(key, int(s["nnn"]))
+        except (state.StateNotFoundError, ValueError, KeyError):
+            continue
+        if rec["state"] in CLAIMABLE_STATES and rec.get("successor") is None:
+            best = rec
+    return best
+
+
+def write_started(session_id: str) -> Path:
+    """``runtime/<sid>.started`` marker for the rotator (PRD §14)."""
+    path = paths.runtime_dir() / f"{session_id}.started"
+    atomic.atomic_write_text(path, "started\n")
+    return path
+
+
+def pending_checkpoint(key: str) -> dict | None:
+    """``latest_checkpoint`` while ``pending_consumption`` (else None)."""
+    try:
+        rec = json.loads(
+            (paths.project_dir(key) / "project.json").read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return None
+    cp = rec.get("latest_checkpoint")
+    if isinstance(cp, dict) and cp.get("pending_consumption"):
+        return cp
+    return None
+
+
+def _decide_name(key: str, slug: str,
+                 allow_env: bool = True) -> tuple[str, int]:
+    """Wrapper-supplied name wins when it ends in ``-<digits>`` (PRD §13).
+
+    ``allow_env=False`` (Phase 27 resume/fork, Phase 28 CLI late attach):
+    the env name belongs to the ABANDONED startup process — the counter
+    name wins, or the dead startup's name would be reused.
+    """
+    if allow_env:
+        env_name = os.environ.get("CC_CONTINUITY_NAME", "").strip()
+        _base, seq = naming.split_name(env_name)
+        if seq is not None:
+            return env_name, project.next_counter(key, requested=seq)
+    nnn = project.next_counter(key)
+    return naming.logical_name(slug, nnn), nnn
+
+
+def _tmux_bin() -> str:
+    return os.environ.get("CC_CONTINUITY_TMUX_BIN") or "tmux"
+
+
+def record_tmux_session(key: str, nnn: int) -> None:
+    """P10-D9.1: record the pane's tmux session name (the watchdog's
+    primary nudge target).
+
+    Only when ``$TMUX`` is set; one fast subprocess (2 s timeout — the
+    hook keeps its ~100 ms budget in the common case); every failure
+    path is swallowed — this must never break the hook (P10-D12).
+    """
+    if not os.environ.get("TMUX"):
+        return
+    try:
+        proc = subprocess.run(
+            [_tmux_bin(), "display-message", "-p", "#{session_name}"],
+            capture_output=True, timeout=2)
+    except (OSError, subprocess.SubprocessError):
+        return
+    if proc.returncode != 0:
+        return
+    name = proc.stdout.decode(errors="replace").strip()
+    if not name:
+        return
+    try:
+        state.update_fields(key, nnn, tmux_session=name)
+    except Exception:
+        pass
+
+
+def register_session(cwd, session_id: str, *, cfg: dict,
+                     source: str = "manual",
+                     allow_env: bool = False) -> tuple[str, int]:
+    """Register a conversation that has no record (late attach).
+
+    Phase 28: ``cc-continuity checkpoint`` / ``request-rotation`` run in
+    a session whose conversation was never registered (e.g. a process
+    started before the Phase 27 resume registration — 2026-10-03
+    connector a7c36f64, unmonitored at 72%). Creates its record the way
+    the SessionStart hook does — per-operation locking, since the helpers
+    take the project lock themselves and a wrapping ``lock.held`` would
+    self-deadlock (flock is not re-entrant): counter name (unless
+    ``allow_env``), state ACTIVE (BOOTSTRAPPING when a checkpoint is
+    pending), one ``session_start`` ledger entry, the
+    ``session_started`` push, tmux re-record.
+    Returns ``(key, nnn)``.
+    """
+    root = project.resolve_root(Path(cwd))
+    key = project.project_key_for_root(root)
+    record = project.ensure_project(str(cwd))
+    sessions = record.get("sessions") or []
+    predecessor = sessions[-1]["name"] if sessions else None
+    name, nnn = _decide_name(key, record["slug"], allow_env=allow_env)
+    initial = "BOOTSTRAPPING" if pending_checkpoint(key) else "ACTIVE"
+    state.create_session_state(key, name, nnn, session_id,
+                               predecessor=predecessor,
+                               initial_state=initial)
+    project.record_session(key, name, session_id, nnn)
+    ledger.append(paths.session_dir(key, nnn),
+                  {"type": "session_start", "source": source,
+                   "name": name, "nnn": nnn})
+    notify.safe_send(cfg, "session_started",
+                     slug=notify.project_slug(key), nnn=nnn, name=name,
+                     host=notify.host())
+    record_tmux_session(key, nnn)
+    return key, nnn
+
+
+def _new_work_since_handoff(cp_dir: Path, key: str,
+                            old_nnn: int) -> list[str]:
+    """The user prompts typed AFTER the checkpoint snapshot was written —
+    the rotation window (handoff finalizing / old session still live):
+    they land in the OLD session's live ledger, but the handoff is already
+    frozen and can no longer contain them, so they would be lost to the
+    successor (the rotation-window bug: new prompts landing after the handoff froze).
+
+    Marker: the snapshot's ``created`` (epoch; falls back to the
+    checkpoint dir mtime when missing). The snapshot's ``user_prompts``
+    marks what the handoff already captured, so a prompt present in BOTH
+    (``ts >= created`` and captured — the same-second race) is not
+    re-sent: no double-count. ``CONTINUITY RESUME`` prompts (bootstrap
+    hand-off) and subagent prompts (``agent_id``) are not user work.
+    Bounded: the last 5, each cut to the snapshot's own prompt width.
+    Never raises."""
+    try:
+        snap = json.loads((cp_dir / "snapshot.json")
+                          .read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        snap = {}
+    captured = {str(p) for p in snap.get("user_prompts") or []}
+    cut = int(getattr(checkpoint, "PROMPT_CHARS", 500))
+    try:
+        created = datetime.fromisoformat(str(snap["created"])).timestamp()
+    except (KeyError, TypeError, ValueError):
+        try:
+            created = cp_dir.stat().st_mtime
+        except OSError:
+            return []
+    out: list[str] = []
+    try:
+        entries = ledger.read(paths.session_dir(key, old_nnn))
+    except OSError:
+        return []
+    for e in entries:
+        if e.get("type") != "user_prompt" or e.get("agent_id"):
+            continue
+        ts = e.get("ts")
+        if not isinstance(ts, (int, float)) or ts < created:
+            continue
+        text = str(e.get("text", ""))
+        if text.startswith("CONTINUITY RESUME"):
+            continue
+        if text[:cut] in captured:
+            continue
+        out.append(text[:cut])
+    return out[-5:]
+
+
+def try_claim(key: str, *, new_session_id: str, cfg: dict) -> dict | None:
+    """Claim the latest claimable session for a fresh session (PRD §9).
+
+    Caller holds the project lock. Returns ``None`` when nothing is
+    claimable (idempotent: a second claim sees ``successor`` set). On
+    success returns ``{"old_name", "old_nnn", "new_name", "new_nnn",
+    "validation", "details", "bootstrap_text"}`` and has: created the
+    successor state (BOOTSTRAPPING, predecessor = old name, nnn = old+1 at
+    least), set the old session's ``successor`` and moved it to ROTATED,
+    cleared ``pending_consumption`` on the matching latest_checkpoint,
+    appended one ``session_start`` ledger entry to the successor, and
+    updated project.json (counter / sessions / checkpoint) in one atomic
+    write.
+    """
+    old = find_claimable(key)
+    if old is None:
+        return None
+    pfile = paths.project_dir(key) / "project.json"
+    pref = json.loads(pfile.read_text(encoding="utf-8"))
+    root = Path(pref["root"])
+    old_nnn = int(old["nnn"])
+    nnn_new = max(int(pref["counter"]), old_nnn) + 1
+    name_new = naming.logical_name(naming.split_name(old["name"])[0], nnn_new)
+    state.create_session_state(key, name_new, nnn_new, new_session_id,
+                               predecessor=old["name"],
+                               initial_state="BOOTSTRAPPING")
+    state.update_fields_unlocked(key, old_nnn, successor=name_new)
+    state._transition_unlocked(key, old_nnn, "ROTATED")
+    cp = pref.get("latest_checkpoint")
+    if isinstance(cp, dict) and cp.get("nnn") == old_nnn \
+            and cp.get("pending_consumption"):
+        cp = dict(cp)
+        cp["pending_consumption"] = False
+        cp["consumed_by"] = name_new
+        pref["latest_checkpoint"] = cp
+    pref["counter"] = nnn_new
+    pref["sessions"].append({"name": name_new, "session_id": new_session_id,
+                             "nnn": nnn_new, "created": _now()})
+    atomic.atomic_write_json(pfile, pref)
+    cp_dir = paths.session_dir(key, old_nnn) / "checkpoint"
+    status, details = validate.validate_checkpoint(cp_dir, cfg, root=root)
+    handoff_file = cp_dir / "handoff.md"
+    try:
+        handoff = handoff_file.read_text(encoding="utf-8")
+    except OSError:
+        handoff = ""
+    text = thresholds.c4_text(
+        new_name=name_new, old_name=old["name"], status=status,
+        details=details, handoff=handoff, handoff_path=str(handoff_file),
+        inline_max=int(cfg.get("inline_handoff_max_chars", 12000)),
+        new_work=_new_work_since_handoff(cp_dir, key, old_nnn))
+    ledger.append(paths.session_dir(key, nnn_new),
+                  {"type": "session_start", "source": "clear",
+                   "claimed": old["name"], "validation": status})
+    return {"old_name": old["name"], "old_nnn": old_nnn,
+            "new_name": name_new, "new_nnn": nnn_new,
+            "validation": status, "details": details,
+            "bootstrap_text": text}