cc-continuity 0.2.0__tar.gz → 0.3.0__tar.gz

{cc_continuity-0.2.0 → cc_continuity-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cc-continuity
-Version: 0.2.0
+Version: 0.3.0
 Summary: Zero-touch session rotation for Claude Code (local large-context model)
 Requires-Python: >=3.11
 License-File: LICENSE

{cc_continuity-0.2.0 → cc_continuity-0.3.0}/cc_continuity/__init__.py

@@ -4,4 +4,4 @@ Spec: docs/PRD.md (v1.0). Platform facts verified in docs/VERIFICATION.md.
 Standard library only at runtime; pytest is dev-only.
 """
 
-__version__ = "0.2.0"
+__version__ = "0.3.0"

cc_continuity-0.3.0/cc_continuity/blink.py

@@ -0,0 +1,278 @@
+"""Waiting-blink primitives (issue #11).
+
+Thin, self-contained layer: the OSC 6 tab-color escape sequences (spike
+proven on iTerm2 3.7.6 and Terminal.app), the gate markers the blink
+reacts to, and the tmux/tty helpers the ``Blinker`` state machine uses.
+
+Import direction rule: ``progress_pane`` and ``statusline`` import from
+here; this module only leans on leaf modules (``config``, ``paths``) and
+never on ``progress_pane`` or ``statusline``, so a blink failure can
+never drag the animator down.
+"""
+
+import subprocess
+import time
+
+from . import config, paths
+
+OSC6_RESET = b"\x1b]6;1;bg;*;default\x07"
+
+RED_FILL = (235, 20, 20)
+BLACK_FILL = (0, 0, 0)
+
+# Single source of truth for the gate markers. statusline.py composes its
+# suffixes from these constants (composing its own leading spaces) so the
+# writer and the gate can never drift apart silently.
+MARKER_BLOCKED = "⛔ BLOCKED"
+MARKER_ASK = "⚠ ASK"
+GATE_MARKERS = (MARKER_BLOCKED, MARKER_ASK)
+
+
+def osc6_fill(rgb: tuple[int, int, int]) -> bytes:
+    """One write carrying the three OSC 6 background-channel fills.
+
+    ``ESC ] 6 ; 1 ; bg ; <chan> ; brightness ; N BEL`` for red, green and
+    blue in order (byte order pinned by tests; spike-proven format).
+    """
+    red, green, blue = rgb
+    out = bytearray()
+    for chan, val in (("red", red), ("green", green), ("blue", blue)):
+        out += (b"\x1b]6;1;bg;" + chan.encode("ascii")
+                + b";brightness;" + str(int(val)).encode("ascii") + b"\x07")
+    return bytes(out)
+
+
+def blink_gate(text: str | None) -> bool:
+    """True when the per-window progress text carries a listed gate marker."""
+    if not text:
+        return False
+    return any(marker in text for marker in GATE_MARKERS)
+
+
+def _tmux(runner, bin_: str, argv_tail: list, timeout: float = 2.0):
+    """Run one tmux command via ``runner``; stripped stdout or None on failure."""
+    try:
+        proc = runner([bin_, *argv_tail], capture_output=True, timeout=timeout)
+    except Exception:
+        return None
+    if proc.returncode != 0:
+        return None
+    return proc.stdout.decode("utf-8", "replace").strip()
+
+
+def list_client_ttys(runner, bin_: str, target: str) -> list[str]:
+    """ttys of the clients attached to ``target`` ([] when none/unreachable).
+
+    tmux prints the literal ``not a tty`` for clients without a tty; those
+    lines (and blanks) are dropped. One tty per line, never whitespace
+    split inside a path.
+    """
+    out = _tmux(runner, bin_, ["list-clients", "-t", target,
+                               "-F", "#{client_tty}"])
+    if out is None:
+        return []
+    return [line.strip() for line in out.splitlines()
+            if line.strip() and line.strip() != "not a tty"]
+
+
+def get_window_name(runner, bin_: str, target: str) -> str | None:
+    """Current window name for ``target``, None when unreadable."""
+    return _tmux(runner, bin_, ["display-message", "-p", "-t", target,
+                                "#{window_name}"])
+
+
+def rename_window(runner, bin_: str, target: str, name: str) -> bool:
+    """Rename the window at ``target``; False on any tmux failure."""
+    return _tmux(runner, bin_, ["rename-window", "-t", target, name]) is not None
+
+
+def write_tty(path: str, data: bytes, *, _open=open) -> bool:
+    """Write raw bytes to a client tty; False (never raise) on OSError.
+
+    tmux never sees these bytes: the OSC sequences bypass the pane and go
+    straight to the terminal emulator on the client's own tty.
+    """
+    try:
+        fh = _open(path, "wb")
+    except OSError:
+        return False
+    try:
+        fh.write(data)
+        return True
+    except OSError:
+        return False
+    finally:
+        try:
+            fh.close()
+        except OSError:
+            pass
+
+
+def _debug_line(msg: str) -> None:
+    """Append one diagnostic line to the blink log (never raises).
+
+    The package has no stdlib logging module; the rotator/watchdogd
+    file-line pattern is its convention, and the pane stdout is occupied
+    by animation frames. One file keeps a non-blinking tab diagnosable.
+    """
+    try:
+        log_path = paths.logs_dir() / "blink.log"
+        log_path.parent.mkdir(parents=True, exist_ok=True)
+        with open(log_path, "a", encoding="utf-8") as fh:
+            fh.write(f"{time.strftime('%Y-%m-%dT%H:%M:%S')} {msg}\n")
+    except Exception:
+        pass
+
+
+class Blinker:
+    """Waiting-blink state machine driven by the animator's frame tick.
+
+    ``on_text(text, now)`` arrives every animator frame with the current
+    progress text and clock; ``on_exit()`` runs when the animator
+    returns. The clock rides in on the call so tests fake it per tick.
+    Every tmux/tty path swallows failures: the blink is decoration and
+    must never break the progress animation.
+    """
+
+    def __init__(self, window_id: str, cfg: dict, *, store,
+                 runner=subprocess.run, bin_: str = "tmux", tty_open=open,
+                 log=None):
+        self.window_id = window_id
+        self._store = store
+        self._runner = runner
+        self._bin_ = bin_
+        self._tty_open = tty_open
+        self._log = log if log is not None else _debug_line
+        self.enabled = config.blink_enabled(cfg)
+        self._interval = config.blink_interval(cfg)
+        self._fill = osc6_fill(
+            RED_FILL if config.blink_no_color(cfg) else BLACK_FILL)
+        self._blinking = False
+        self._phase_own = True    # True: own color + original name showing
+        self._last_toggle = 0.0
+        self._original = None
+        self._ttys: list[str] = []
+        self._restored_logged = False
+        # the sweep is deliberately NOT gated on enabled: a blink stranded
+        # by a crash must heal even if blink was turned off since. With an
+        # empty store it is a zero-call no-op, so "disabled restores
+        # today's behavior exactly" still holds.
+        self._startup_sweep()
+
+    # -- internals ------------------------------------------------------
+
+    def _startup_sweep(self) -> None:
+        """Self-heal a blink stranded by a crashed animator (once per start)."""
+        try:
+            stored = self._store("blink_name")
+            if not stored:
+                return
+            current = get_window_name(self._runner, self._bin_, self.window_id)
+            if current and current.startswith("WAIT"):
+                restored = rename_window(self._runner, self._bin_,
+                                         self.window_id, stored)
+                for tty in list_client_ttys(self._runner, self._bin_,
+                                            self.window_id):
+                    write_tty(tty, OSC6_RESET, _open=self._tty_open)
+                if restored:
+                    # keep the stored name on failure: the next animator
+                    # start sweeps again
+                    self._store("blink_name", None)
+                    self._log(f"blink sweep window={self.window_id} "
+                              f"restored stranded '{current}'")
+        except Exception:
+            pass
+
+    def _start(self, now: float) -> None:
+        name = get_window_name(self._runner, self._bin_, self.window_id)
+        if name is None:
+            self._log(f"blink skip window={self.window_id} "
+                      f"reason=window name unreadable")
+            return
+        self._original = name
+        self._store("blink_name", name)
+        # Resolved per blink START (never cached across blinks): clients
+        # attach and detach between waits.
+        self._ttys = list_client_ttys(self._runner, self._bin_,
+                                      self.window_id)
+        self._blinking = True
+        self._phase_own = True
+        self._last_toggle = now
+        self._restored_logged = False
+        if self._ttys:
+            self._log(f"blink start window={self.window_id} "
+                      f"ttys={len(self._ttys)}")
+        else:
+            self._log(f"blink skip window={self.window_id} "
+                      f"reason=no attached clients")
+
+    def _wait_name(self, text: str | None) -> str:
+        n = sum(text.count(m) for m in GATE_MARKERS) if text else 0
+        return "WAIT" if n <= 1 else f"WAIT[{n}]"
+
+    def _apply(self, text: str | None) -> None:
+        if self._phase_own:
+            rename_window(self._runner, self._bin_, self.window_id,
+                          self._original)
+            for tty in self._ttys:
+                write_tty(tty, OSC6_RESET, _open=self._tty_open)
+        else:
+            rename_window(self._runner, self._bin_, self.window_id,
+                          self._wait_name(text))
+            for tty in self._ttys:
+                write_tty(tty, self._fill, _open=self._tty_open)
+
+    def _restore(self) -> None:
+        if self._original is not None:
+            restored = rename_window(self._runner, self._bin_,
+                                     self.window_id, self._original)
+            for tty in self._ttys:
+                write_tty(tty, OSC6_RESET, _open=self._tty_open)
+            if restored:
+                # Ownership released: a window rename the user makes
+                # afterwards must survive animator exit. A FAILED rename
+                # keeps both the name and the stored value: the store is
+                # the only handle the startup sweep needs to heal the
+                # stranded WAIT later.
+                self._store("blink_name", None)
+                self._original = None
+                if not self._restored_logged:
+                    self._log(f"blink restore window={self.window_id}")
+                    self._restored_logged = True
+        self._blinking = False
+
+    # -- animator surface -------------------------------------------------
+
+    def on_text(self, text: str | None, now: float) -> None:
+        """One animator tick: gate check, phase flip on the interval."""
+        if not self.enabled:
+            return
+        try:
+            gated = blink_gate(text)
+            if gated and not self._blinking:
+                self._start(now)
+                return
+            if not self._blinking:
+                return
+            if not gated:
+                self._restore()
+                return
+            if now - self._last_toggle >= self._interval:
+                self._last_toggle = now
+                self._phase_own = not self._phase_own
+                self._apply(text)
+        except Exception:
+            pass
+
+    def on_exit(self) -> None:
+        """Animator is leaving: restore name and tab color (idempotent)."""
+        if not self.enabled:
+            return
+        try:
+            if self._blinking or self._original is not None:
+                # covers the mid-blink exit AND the retry of a falling-edge
+                # rename that tmux refused; _restore releases ownership on
+                # success, so repeat calls are no-ops
+                self._restore()
+        except Exception:
+            pass

{cc_continuity-0.2.0 → cc_continuity-0.3.0}/cc_continuity/config.py

@@ -224,6 +224,41 @@ def progress_mode(cfg: dict) -> int:
     return v if v in (0, 1, 2) else 0
 
 
+def blink_enabled(cfg: dict) -> bool:
+    """Whether the waiting blink is on (issue #11).
+
+    ``blink``: explicit false disables the tab/window blink entirely and
+    restores today's behavior. A missing key or any non-bool value
+    degrades to True (on whenever the tmux pane animator runs).
+    """
+    v = cfg.get("blink", True)
+    return v if isinstance(v, bool) else True
+
+
+def blink_interval(cfg: dict) -> float:
+    """Seconds per blink phase (issue #11).
+
+    ``blink_interval``: default 0.5 s. Values are clamped to [0.1, 5.0].
+    A missing key or any invalid value (non-numeric, bool) degrades to
+    0.5, so a bad edit can never freeze or hammer the animator.
+    """
+    v = cfg.get("blink_interval", 0.5)
+    if isinstance(v, bool) or not isinstance(v, (int, float)):
+        return 0.5
+    return min(max(float(v), 0.1), 5.0)
+
+
+def blink_no_color(cfg: dict) -> bool:
+    """Whether the blink uses the red fallback (issue #11).
+
+    ``blink_no_color``: true switches the OFF phase from black to red
+    for profiles without a tab color of their own. A missing key or any
+    non-bool value degrades to False (black OFF phase).
+    """
+    v = cfg.get("blink_no_color", False)
+    return v if isinstance(v, bool) else False
+
+
 def session_end_push_suppress(cfg: dict) -> frozenset:
     """Validated Phase 30.1 declared-noise project keys.
 

{cc_continuity-0.2.0 → cc_continuity-0.3.0}/cc_continuity/progress_pane.py

@@ -38,7 +38,7 @@ import shutil
 import subprocess
 import time
 
-from . import atomic, paths
+from . import atomic, blink, config, paths
 from .statusline import _RAINBOW, _SHIMMER
 
 #: Window ids are tmux-generated (``@12``); restrict what we splice into
@@ -430,10 +430,14 @@ def _window_pane_count(window_id: str | None) -> int | None:
 # --------------------------------------------------------------- run_animator
 
 
+_BLINK_MISSING = object()
+
+
 def run_animator(window_id: str | None = None, *, _frames=None,
                  _write=None, _now=None, _size=None, _text=None,
                  _mtime=None, _sleep=None, _live_check=None,
-                 _check_every=40) -> None:
+                 _check_every=40, _blink=None, _tty_open=None,
+                 _runner=None) -> None:
     """Animate the progress line at ~20 fps until any I/O fails.
 
     Each frame is ``\\x1b[H\\x1b[2K`` + a full-width ``_frame``
@@ -472,6 +476,34 @@ def run_animator(window_id: str | None = None, *, _frames=None,
                 else (lambda: _progress_data_mtime(window_id)))
     live_check = (_live_check if _live_check is not None
                   else (lambda: _window_pane_count(window_id)))
+    # Waiting blink (issue #11): one tick-driven state machine beside the
+    # shimmer. It swallows every failure internally; a broken tmux/tty
+    # path must never take the progress animation down with it.
+    blink_mod = _blink if _blink is not None else blink
+    try:
+        cfg = config.load_config()
+    except Exception:
+        cfg = {"blink": False}
+
+    def blink_store(key, value=_BLINK_MISSING):
+        try:
+            rec = _read_pane_record()
+            full = f"blink-{window_id}-{key}"
+            if value is _BLINK_MISSING:
+                return rec.get(full)
+            if value is None:
+                rec.pop(full, None)
+            else:
+                rec[full] = value
+            _write_pane_record(rec)
+        except Exception:
+            return None
+        return None
+
+    blinker = blink_mod.Blinker(
+        window_id or "", cfg, store=blink_store,
+        runner=(_runner if _runner is not None else subprocess.run),
+        tty_open=(_tty_open if _tty_open is not None else open))
     try:
         cur_text = text_fn()
         cur_mtime = mtime_fn()
@@ -504,6 +536,9 @@ def run_animator(window_id: str | None = None, *, _frames=None,
                     cur_text = text_fn()
                 cur_mtime = mt
             t = now()
+            # outside the skipped guard: a skipped paint must not stall
+            # the blink phase clock.
+            blinker.on_text(cur_text, t)
             if not skipped:
                 # \x1b[H homes to row 1 col 1 every frame: \r alone can't
                 # recover a pty cursor that a resize-race wrap dropped to
@@ -532,3 +567,7 @@ def run_animator(window_id: str | None = None, *, _frames=None,
             sleep(max(0.0, 0.05 - (t2 - t)))
     except Exception:
         return
+    finally:
+        # every exit path (frame bound, orphan guard, any I/O failure)
+        # restores the window name and tab color.
+        blinker.on_exit()

{cc_continuity-0.2.0 → cc_continuity-0.3.0}/cc_continuity/statusline.py

@@ -30,7 +30,7 @@ import subprocess
 import time
 from pathlib import Path
 
-from . import atomic, config, ledger, naming, paths
+from . import atomic, blink, config, ledger, naming, paths
 
 #: Hooks treat a metric older than this as unknown (PRD §7, METRIC_STALE).
 STALE_SECONDS = 600
@@ -382,7 +382,7 @@ def render_segment(ratio: float | None, record: dict | None,
                    now: float | None = None,
                    shimmer: bool = False,
                    shimmer_pos: float | None = None,
-                   breathing: bool = False) -> str:
+                   breathing: bool = False, ask: bool = False) -> str:
     """Render our ``◆ …`` segment (PRD §7; Phase 11 styling, P11-D2/D3/D4).
 
     Forms: ``◆ off`` (disabled / session off), ``◆ …`` (no metric),
@@ -394,6 +394,9 @@ def render_segment(ratio: float | None, record: dict | None,
     ``⛔ BLOCKED`` suffix (Phase 9, P9-P5): machine-side truth while a
     needs_human ledger entry is unconsumed — visible on any later attach
     (spec §7 risk note).
+    ``⚠ ASK`` suffix (issue #11): an unsubmitted permission prompt sits in
+    the captured input box (same live gate as the ultrathink word); the
+    blink gate in ``blink.py`` reacts to both suffixes (shared constants).
     Phase 11 (revision 4): with ``ansi`` (default, config
     ``statusline_ansi``) live segments render the ultrathink.sh
     per-character 24-bit rainbow (7 base hues cycled ``i % 7`` —
@@ -407,7 +410,10 @@ def render_segment(ratio: float | None, record: dict | None,
     legacy plain strings byte-for-byte.
     """
     now = time.time() if now is None else now
-    blocked_text = f" ⛔ BLOCKED" if blocked else None
+    # Suffix order BLOCKED then ASK (both must survive substring matching
+    # in blink.blink_gate; the constants are blink's, never copied here).
+    blocked_text = ((f" {blink.MARKER_BLOCKED}" if blocked else "")
+                    + (f" {blink.MARKER_ASK}" if ask else "")) or None
     if not ansi:
         if not enabled or (record is not None and record.get("off")):
             return "◆ off"
@@ -461,6 +467,10 @@ def render_segment(ratio: float | None, record: dict | None,
 #: Word-boundary, case-insensitive — ultrathink.sh's ``/\bultrathink\b/gi``.
 ULTRATHINK_RE = re.compile(r"\bultrathink\b", re.IGNORECASE)
 
+# Permission-prompt wording (issue #11): exact phrase only, so ordinary
+# chat containing "allow"/"yes" can never strand the ASK marker.
+_ASK_RE = re.compile(r"Do you want to allow", re.IGNORECASE)
+
 #: CC's input box bottom border is a line of these (verified live, 014).
 _INPUT_BORDER = "─"
 
@@ -666,6 +676,9 @@ def run(stdin_bytes: bytes, cfg: dict) -> str:
     region = _input_box_lines() if (ansi and live) else None
     word = bool(region) and bool(
         ULTRATHINK_RE.search("\n".join(region)))
+    # issue #11: same live-capture gate as the ultrathink word: a dead
+    # pane must not strand an ASK marker.
+    ask = bool(region) and bool(_ASK_RE.search("\n".join(region)))
     mode = config.progress_mode(cfg)
     if mode == 1:
         # Phase 12 fix (user bug A): in mode 1 the PANE is the ONLY
@@ -704,10 +717,12 @@ def run(stdin_bytes: bytes, cfg: dict) -> str:
             # rewritten by a no-metric render (no downgrade, no re-flash).
             if ratio is not None:
                 progress_pane.write_progress_data(win, render_segment(
-                    ratio, record, enabled, blocked=blocked, ansi=False))
+                    ratio, record, enabled, blocked=blocked, ansi=False,
+                    ask=ask))
             elif enabled and not progress_pane.has_progress_data(win):
                 progress_pane.write_progress_data(win, render_segment(
-                    0.0, record, enabled, blocked=blocked, ansi=False))
+                    0.0, record, enabled, blocked=blocked, ansi=False,
+                    ask=ask))
             segment = ""
         elif (isinstance(result, dict)
               and result.get("reason") in ("no-window", "error")):
@@ -721,14 +736,15 @@ def run(stdin_bytes: bytes, cfg: dict) -> str:
         else:
             segment = render_segment(ratio, record, enabled,
                                      blocked=blocked, ansi=ansi, now=now,
-                                     shimmer=False)
+                                     shimmer=False, ask=ask)
     elif mode == 2:
         # Phase 12: breathing — the whole segment brightens and dims in
         # a 2 s cycle (factor 1.0 == today's rainbow byte-for-byte). No
         # sweep, so no shimmer-state write.
         sweep_pos = None
         segment = render_segment(ratio, record, enabled, blocked=blocked,
-                                 ansi=ansi, now=now, breathing=True)
+                                 ansi=ansi, now=now, breathing=True,
+                                 ask=ask)
     else:
         # mode 0 (default): byte-identical to today. Revision 10:
         # constant-speed sweep — the band advances SHIMMER_CELLS_PER_S
@@ -742,7 +758,7 @@ def run(stdin_bytes: bytes, cfg: dict) -> str:
             _write_shimmer_state(now, sweep_pos)
         segment = render_segment(ratio, record, enabled, blocked=blocked,
                                  ansi=ansi, now=now, shimmer=shimmer,
-                                 shimmer_pos=sweep_pos)
+                                 shimmer_pos=sweep_pos, ask=ask)
     _render_log(enabled, ansi, live, word, now, region, segment,
                 sweep_pos)
     chained = chain(cfg.get("chained_statusline"), stdin_bytes)

{cc_continuity-0.2.0 → cc_continuity-0.3.0}/cc_continuity.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cc-continuity
-Version: 0.2.0
+Version: 0.3.0
 Summary: Zero-touch session rotation for Claude Code (local large-context model)
 Requires-Python: >=3.11
 License-File: LICENSE

{cc_continuity-0.2.0 → cc_continuity-0.3.0}/cc_continuity.egg-info/SOURCES.txt

@@ -4,6 +4,7 @@ pyproject.toml
 cc_continuity/__init__.py
 cc_continuity/__main__.py
 cc_continuity/atomic.py
+cc_continuity/blink.py
 cc_continuity/bootstrap.py
 cc_continuity/checkpoint.py
 cc_continuity/cli.py
@@ -51,6 +52,7 @@ cc_continuity/hooks/task.py
 cc_continuity/hooks/tool_use.py
 cc_continuity/hooks/user_prompt.py
 tests/test_atomic.py
+tests/test_blink.py
 tests/test_bootstrap.py
 tests/test_checkpoint.py
 tests/test_cli.py

{cc_continuity-0.2.0 → cc_continuity-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "cc-continuity"
-version = "0.2.0"
+version = "0.3.0"
 description = "Zero-touch session rotation for Claude Code (local large-context model)"
 requires-python = ">=3.11"
 dependencies = []  # stdlib only at runtime (PRD §0.5)