handcuff 0.2.0__tar.gz

handcuff-0.2.0/.github/workflows/publish.yml

@@ -0,0 +1,52 @@
+name: Publish to PyPI
+
+# Trusted Publishing (OIDC) — no API token stored in GitHub. This
+# workflow's filename ("publish.yml") and the job's environment
+# ("pypi") must match exactly what you register in PyPI's
+# "Add a new pending publisher" form.
+on:
+  release:
+    types: [published]
+  workflow_dispatch: {} # allows a manual run from the Actions tab too
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tooling
+        run: python -m pip install --upgrade build
+
+      - name: Build sdist and wheel
+        run: python -m build
+
+      - name: Upload build artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/handcuff
+    permissions:
+      id-token: write # required for OIDC trusted publishing
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

handcuff-0.2.0/.gitignore

@@ -0,0 +1,28 @@
+build/
+dist/
+.env
+tests/
+.claude/
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+.venv/
+handcuff.spec
+nonexistent.db
+*.db
+*.db-wal
+*.db-shm
+*.egg-info/
+00_README_START_HERE.md
+01_PRD.md
+02_TRD.md
+03_Security_Access.md
+04_Implementation_Plan.md
+05_Tickets.md
+06_App_Flow.md
+07_Terminal_UI.md
+AgentLens_SPEC_Part1.md
+AgentLens_SPEC_Part2.md
+AgentLens_SPEC_Part3.md
+AgentLens_SPEC_Part4.md
+__pycache__/

handcuff-0.2.0/PKG-INFO

@@ -0,0 +1,149 @@
+Metadata-Version: 2.4
+Name: handcuff
+Version: 0.2.0
+Summary: A dashcam for your AI agents: local, tamper-evident recorder for process/file/network activity, with a LangChain/LangGraph drop-in prompt-injection circuit breaker.
+Project-URL: Homepage, https://github.com/Mister2005/Handcuff
+Project-URL: Repository, https://github.com/Mister2005/Handcuff
+Project-URL: Issues, https://github.com/Mister2005/Handcuff/issues
+Author: Varun Gupta
+License: MIT
+Keywords: agents,langchain,langgraph,observability,prompt-injection,security
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.11
+Requires-Dist: cryptography>=42.0
+Requires-Dist: httpx>=0.27
+Requires-Dist: pillow>=10.0
+Requires-Dist: psutil>=5.9
+Requires-Dist: pyfiglet>=1.0
+Requires-Dist: python-ulid>=2.2
+Requires-Dist: rich-pixels>=3.0
+Requires-Dist: ruamel-yaml>=0.18
+Requires-Dist: textual>=0.58
+Requires-Dist: typer>=0.12
+Requires-Dist: watchdog>=4.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pip-audit>=2.7; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.2; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Provides-Extra: langchain
+Requires-Dist: langchain-core>=0.2; extra == 'langchain'
+Description-Content-Type: text/markdown
+
+# Handcuff
+
+**A dashcam for your AI agents.** Handcuff records the OS-level side effects of an AI agent — processes spawned, files written, network connections opened — into a local, tamper-evident, hash-chained SQLite timeline you can replay, search, export, and verify. Real-time policy alerts flag risky behavior (sudo, mass deletes, writes outside the workspace, unknown domains, force pushes) while the agent runs.
+
+**Local-only by design:** nothing ever leaves your machine except an optional, user-configured, content-light webhook (HTTPS required). This is enforced by a `test_no_egress` release-gate test.
+
+> **Platform note:** the current implementation targets **Windows** (psutil + watchdog capture, Windows ACL/Firewall enforcement, PyInstaller binary). The original planning docs describe a Linux-first design; that pivot is deliberate. Most capture code is psutil-generic, so Linux/macOS support is feasible but currently untested.
+
+## Install
+
+```powershell
+# From PyPI (Python 3.11+) — note the distribution name; the import
+# name and CLI command are still `handcuff` either way.
+pip install handcuff
+# with the LangChain/LangGraph integration:
+pip install "handcuff[langchain]"
+
+# From source, for development
+pip install .
+
+# Or use the prebuilt binary
+dist\handcuff.exe --help
+```
+
+## Quickstart
+
+```powershell
+# Record an agent (or any command) and everything it does
+handcuff watch -- python my_agent.py
+
+# List recorded sessions, then open the live dashboard
+handcuff sessions
+handcuff tui
+
+# Replay a past session, jumping between alerts
+handcuff replay <SESSION_ID>
+
+# Export a report (json | md | html) and verify its hash chain
+handcuff export <SESSION_ID> --format html
+handcuff verify <SESSION_ID>
+
+# Attach to something already running
+handcuff attach <PID>
+
+# Environment diagnostics
+handcuff doctor
+```
+
+## Key features
+
+- **Tamper-evident timeline** — every event is SHA-256 hash-chained; session heads are Ed25519-signed. `handcuff verify` re-validates the chain from the DB or from a JSON export.
+- **Capture** — process spawn/exit (psutil), file write/delete/rename (watchdog), network connects (psutil). Optional `--hash-content` records a SHA-256 of written files (≤1 MiB; hash only, never content).
+- **Rules & alerts** — safe expression DSL (AST-evaluated, no `eval`), windowed rules, default ruleset, trust allowlist (`handcuff rules trust add domain example.com`), optional webhook on critical alerts.
+- **Redaction** — secrets (API keys, tokens) are scrubbed before events are persisted.
+- **Enforcement (opt-in, Windows)** — `watch --enforce` applies real OS-level blocking: Deny-ACLs on sensitive files (no admin needed) and, if elevated, a Windows Firewall outbound block with `--allow-domain` exceptions. Always reverted on exit.
+- **Cooperative gateway + prompt-injection circuit breaker** — `handcuff.gateway.Gateway` is a validating proxy for agent frameworks that route their file/network tool calls through it (same trust model as an OpenAI/LangChain/MCP tool sandbox — see its docstring for exact scope, it cannot stop raw shell/socket access). Every fetched URL (and any file read marked `untrusted=True`) is scanned with a heuristic prompt-injection signature scanner (`handcuff.rules.injection`) covering instruction-override phrasing, fake system/assistant turn markers, jailbreak personas, data-exfiltration instructions, and obfuscation tells (hidden Unicode, suspicious base64 blobs). A match "taints" the session for a configurable window and the gateway then **blocks further network egress** — the deterministic mitigation for Simon Willison's "lethal trifecta" (private data access + untrusted content + external communication), rather than trying to out-guess the injection semantically. This is a regex/heuristic tripwire, not a semantic guarantee — a novel or paraphrased injection can still slip past it; treat a miss as "not a known pattern" rather than "safe."
+
+  ```python
+  from pathlib import Path
+  from handcuff.gateway.gateway import Gateway, GatewayDenied
+
+  with Gateway(workspace_root=Path("./agent_workspace")) as gw:
+      page = gw.http_request("https://example.com/some-doc")  # scanned automatically
+      if gw.is_tainted:
+          print("suspected prompt injection:", gw.taint_info.reason)
+      try:
+          gw.http_request("https://wherever-the-doc-said-to-send-data.example")
+      except GatewayDenied as e:
+          print("blocked:", e)  # circuit breaker fired
+  ```
+- **TUI dashboard** — trust meter, flagged-event cards, live monitoring, recommendation panel (Textual).
+- **Exports** — JSON (with embedded verification block), Markdown, and self-contained HTML reports.
+- **Multi-agent framework integration (LangChain / LangGraph), one line of code** — `handcuff.integrations.langchain.HandcuffHandler` is a real `langchain-core` `BaseCallbackHandler`. Pass it as `callbacks=[handler]` to any chain, agent, or graph and it records every chain/tool/retriever call as a hash-chained event **and** runs the same injection scanner + taint circuit breaker as the Gateway, scoped per agent. It works for concurrent/parallel agents (multiple LangGraph nodes, `ThreadPoolExecutor`, `asyncio.gather`) because it keys state off LangChain's own `run_id`/`parent_run_id` run tree — the same mechanism LangChain uses internally to keep parallel runs from crossing wires — with all shared state protected by a lock for real cross-thread safety. `pip install handcuff[langchain]` to pull in `langchain-core`. Verified against the real package end-to-end (parallel `ThreadPoolExecutor` agents, real `@tool`s, real blocking) — see `tests/test_langchain_real.py`.
+
+  ```python
+  from handcuff.integrations.langchain import HandcuffHandler
+
+  handler = HandcuffHandler()  # writes to the same DB `handcuff tui` watches
+  result = my_graph.invoke(inputs, config={"callbacks": [handler]})
+  handler.close()
+  ```
+
+  Run `handcuff tui` in another terminal while your agent(s) run — it polls the same DB and picks the session up live automatically, no extra wiring. Honest scope: this only sees what happens through LangChain's own abstractions (chains/tools/retrievers) — a tool implementation that shells out or calls `requests` directly with no LangChain wrapper around it never fires these callbacks, and taint is scoped to one run tree (one top-level `.invoke()`), not the whole process.
+
+## Configuration
+
+```powershell
+handcuff config list
+handcuff config set retention_days 14
+handcuff config set webhook_url https://hooks.example.com/handcuff
+```
+
+Config lives at `~/.config/handcuff/config.yaml`; the DB at `~/.local/share/handcuff/handcuff.db`; the signing key at `~/.config/handcuff/ed25519.key`.
+
+## Development
+
+```powershell
+python -m venv .venv && .venv\Scripts\pip install -e .[dev,langchain]
+.venv\Scripts\python -m pytest tests -q     # ~180 tests
+.venv\Scripts\ruff check handcuff tests
+scripts\build_windows.ps1                    # PyInstaller binary
+```
+
+Security release gates (must always pass): no-egress, chain-tamper detection, redaction, DSL safety, watchdog reconcile.
+
+## Documentation
+
+Planning and design docs live in the repo root: [PRD](01_PRD.md), [TRD](02_TRD.md), [Security](03_Security_Access.md), [Implementation Plan](04_Implementation_Plan.md), [Tickets](05_Tickets.md), and the TUI spec (`Handcuff_SPEC_Part1-4.md`).

handcuff-0.2.0/README.md

@@ -0,0 +1,108 @@
+# Handcuff
+
+**A dashcam for your AI agents.** Handcuff records the OS-level side effects of an AI agent — processes spawned, files written, network connections opened — into a local, tamper-evident, hash-chained SQLite timeline you can replay, search, export, and verify. Real-time policy alerts flag risky behavior (sudo, mass deletes, writes outside the workspace, unknown domains, force pushes) while the agent runs.
+
+**Local-only by design:** nothing ever leaves your machine except an optional, user-configured, content-light webhook (HTTPS required). This is enforced by a `test_no_egress` release-gate test.
+
+> **Platform note:** the current implementation targets **Windows** (psutil + watchdog capture, Windows ACL/Firewall enforcement, PyInstaller binary). The original planning docs describe a Linux-first design; that pivot is deliberate. Most capture code is psutil-generic, so Linux/macOS support is feasible but currently untested.
+
+## Install
+
+```powershell
+# From PyPI (Python 3.11+) — note the distribution name; the import
+# name and CLI command are still `handcuff` either way.
+pip install handcuff
+# with the LangChain/LangGraph integration:
+pip install "handcuff[langchain]"
+
+# From source, for development
+pip install .
+
+# Or use the prebuilt binary
+dist\handcuff.exe --help
+```
+
+## Quickstart
+
+```powershell
+# Record an agent (or any command) and everything it does
+handcuff watch -- python my_agent.py
+
+# List recorded sessions, then open the live dashboard
+handcuff sessions
+handcuff tui
+
+# Replay a past session, jumping between alerts
+handcuff replay <SESSION_ID>
+
+# Export a report (json | md | html) and verify its hash chain
+handcuff export <SESSION_ID> --format html
+handcuff verify <SESSION_ID>
+
+# Attach to something already running
+handcuff attach <PID>
+
+# Environment diagnostics
+handcuff doctor
+```
+
+## Key features
+
+- **Tamper-evident timeline** — every event is SHA-256 hash-chained; session heads are Ed25519-signed. `handcuff verify` re-validates the chain from the DB or from a JSON export.
+- **Capture** — process spawn/exit (psutil), file write/delete/rename (watchdog), network connects (psutil). Optional `--hash-content` records a SHA-256 of written files (≤1 MiB; hash only, never content).
+- **Rules & alerts** — safe expression DSL (AST-evaluated, no `eval`), windowed rules, default ruleset, trust allowlist (`handcuff rules trust add domain example.com`), optional webhook on critical alerts.
+- **Redaction** — secrets (API keys, tokens) are scrubbed before events are persisted.
+- **Enforcement (opt-in, Windows)** — `watch --enforce` applies real OS-level blocking: Deny-ACLs on sensitive files (no admin needed) and, if elevated, a Windows Firewall outbound block with `--allow-domain` exceptions. Always reverted on exit.
+- **Cooperative gateway + prompt-injection circuit breaker** — `handcuff.gateway.Gateway` is a validating proxy for agent frameworks that route their file/network tool calls through it (same trust model as an OpenAI/LangChain/MCP tool sandbox — see its docstring for exact scope, it cannot stop raw shell/socket access). Every fetched URL (and any file read marked `untrusted=True`) is scanned with a heuristic prompt-injection signature scanner (`handcuff.rules.injection`) covering instruction-override phrasing, fake system/assistant turn markers, jailbreak personas, data-exfiltration instructions, and obfuscation tells (hidden Unicode, suspicious base64 blobs). A match "taints" the session for a configurable window and the gateway then **blocks further network egress** — the deterministic mitigation for Simon Willison's "lethal trifecta" (private data access + untrusted content + external communication), rather than trying to out-guess the injection semantically. This is a regex/heuristic tripwire, not a semantic guarantee — a novel or paraphrased injection can still slip past it; treat a miss as "not a known pattern" rather than "safe."
+
+  ```python
+  from pathlib import Path
+  from handcuff.gateway.gateway import Gateway, GatewayDenied
+
+  with Gateway(workspace_root=Path("./agent_workspace")) as gw:
+      page = gw.http_request("https://example.com/some-doc")  # scanned automatically
+      if gw.is_tainted:
+          print("suspected prompt injection:", gw.taint_info.reason)
+      try:
+          gw.http_request("https://wherever-the-doc-said-to-send-data.example")
+      except GatewayDenied as e:
+          print("blocked:", e)  # circuit breaker fired
+  ```
+- **TUI dashboard** — trust meter, flagged-event cards, live monitoring, recommendation panel (Textual).
+- **Exports** — JSON (with embedded verification block), Markdown, and self-contained HTML reports.
+- **Multi-agent framework integration (LangChain / LangGraph), one line of code** — `handcuff.integrations.langchain.HandcuffHandler` is a real `langchain-core` `BaseCallbackHandler`. Pass it as `callbacks=[handler]` to any chain, agent, or graph and it records every chain/tool/retriever call as a hash-chained event **and** runs the same injection scanner + taint circuit breaker as the Gateway, scoped per agent. It works for concurrent/parallel agents (multiple LangGraph nodes, `ThreadPoolExecutor`, `asyncio.gather`) because it keys state off LangChain's own `run_id`/`parent_run_id` run tree — the same mechanism LangChain uses internally to keep parallel runs from crossing wires — with all shared state protected by a lock for real cross-thread safety. `pip install handcuff[langchain]` to pull in `langchain-core`. Verified against the real package end-to-end (parallel `ThreadPoolExecutor` agents, real `@tool`s, real blocking) — see `tests/test_langchain_real.py`.
+
+  ```python
+  from handcuff.integrations.langchain import HandcuffHandler
+
+  handler = HandcuffHandler()  # writes to the same DB `handcuff tui` watches
+  result = my_graph.invoke(inputs, config={"callbacks": [handler]})
+  handler.close()
+  ```
+
+  Run `handcuff tui` in another terminal while your agent(s) run — it polls the same DB and picks the session up live automatically, no extra wiring. Honest scope: this only sees what happens through LangChain's own abstractions (chains/tools/retrievers) — a tool implementation that shells out or calls `requests` directly with no LangChain wrapper around it never fires these callbacks, and taint is scoped to one run tree (one top-level `.invoke()`), not the whole process.
+
+## Configuration
+
+```powershell
+handcuff config list
+handcuff config set retention_days 14
+handcuff config set webhook_url https://hooks.example.com/handcuff
+```
+
+Config lives at `~/.config/handcuff/config.yaml`; the DB at `~/.local/share/handcuff/handcuff.db`; the signing key at `~/.config/handcuff/ed25519.key`.
+
+## Development
+
+```powershell
+python -m venv .venv && .venv\Scripts\pip install -e .[dev,langchain]
+.venv\Scripts\python -m pytest tests -q     # ~180 tests
+.venv\Scripts\ruff check handcuff tests
+scripts\build_windows.ps1                    # PyInstaller binary
+```
+
+Security release gates (must always pass): no-egress, chain-tamper detection, redaction, DSL safety, watchdog reconcile.
+
+## Documentation
+
+Planning and design docs live in the repo root: [PRD](01_PRD.md), [TRD](02_TRD.md), [Security](03_Security_Access.md), [Implementation Plan](04_Implementation_Plan.md), [Tickets](05_Tickets.md), and the TUI spec (`Handcuff_SPEC_Part1-4.md`).

handcuff-0.2.0/handcuff/alerts/webhooks.py

@@ -0,0 +1,56 @@
+"""Webhook alerts (AL-042).
+
+Posts a minimal JSON payload to a configured URL when a `critical`
+severity alert fires. Deliberately content-light: only rule_id,
+severity, message, and timestamp — never argv, file paths, domains, or
+any other captured content (NFR-1: nothing leaves the machine except to
+a user-configured webhook, and even then, as little as possible).
+
+HTTPS is required for remote hosts; plain HTTP is only allowed to
+localhost (useful for local test receivers / local automation), so a
+misconfigured webhook URL can't silently leak alert text in the clear
+over the network.
+"""
+
+from __future__ import annotations
+
+from urllib.parse import urlparse
+
+import httpx
+
+from handcuff.rules.engine import Alert
+
+_LOCALHOST_HOSTS = {"localhost", "127.0.0.1", "::1"}
+
+
+def is_allowed_url(url: str) -> bool:
+    parsed = urlparse(url)
+    if parsed.scheme == "https":
+        return True
+    if parsed.scheme == "http" and parsed.hostname in _LOCALHOST_HOSTS:
+        return True
+    return False
+
+
+def alert_payload(alert: Alert) -> dict:
+    """Content-light payload: no argv/path/domain/file content, ever."""
+    return {
+        "rule_id": alert.rule_id,
+        "severity": alert.severity,
+        "message": alert.message,
+        "ts": alert.ts,
+    }
+
+
+async def post_alert(url: str, alert: Alert, timeout: float = 5.0) -> bool:
+    """Post a critical alert to the configured webhook. Returns False
+    (never raises) on any failure — a broken webhook must not crash or
+    stall the recording session."""
+    if not is_allowed_url(url):
+        return False
+    try:
+        async with httpx.AsyncClient(timeout=timeout) as client:
+            resp = await client.post(url, json=alert_payload(alert))
+            return resp.status_code < 400
+    except httpx.HTTPError:
+        return False

handcuff-0.2.0/handcuff/banner.py

@@ -0,0 +1,128 @@
+"""Startup banner (Handcuff's "logo"), printed like Claude Code/Gemini
+CLI show a welcome screen on launch.
+
+Two-column layout matching Claude Code's actual screen: a bordered
+panel (icon + welcome + identity) on the left, "Quick start"/"What's
+new" on the right — not a single lonely box in empty space.
+
+Uses Rich's own box-drawing (rounded corners, the magnifying-glass
+icon) which Rich encodes correctly for the detected terminal — verified
+directly against Windows Terminal. Only hand-typed *content* avoids
+non-ASCII (verified while building this that this environment's
+console can mangle hand-typed non-ASCII depending on code page); Rich's
+box-drawing glyphs are a separate, correctly-handled concern.
+"""
+
+from __future__ import annotations
+
+import getpass
+import os
+import platform
+import sys
+from importlib.metadata import PackageNotFoundError, version
+from pathlib import Path
+
+from rich import box
+from rich.align import Align
+from rich.console import Console, Group
+from rich.panel import Panel
+from rich.table import Table
+from rich.text import Text
+from rich_pixels import Pixels
+
+from handcuff.tui.widgets.hero import render_hero_pixels
+
+# Explicit hex, not a named Rich color ("bright_cyan" etc.): verified
+# directly from a user screenshot that named ANSI colors get remapped
+# by the terminal's own color theme (rendered as purple instead of
+# cyan there), while hex triggers Rich's 24-bit true-color escape codes
+# and bypasses that remapping — same reason the Hero widget's lens ring
+# (already hex-based) rendered correctly cyan in that same screenshot.
+ACCENT = "#00D9FF"  # matches the TUI theme's primary color
+
+
+def _version() -> str:
+    try:
+        return version("handcuff")
+    except PackageNotFoundError:
+        return "0.1.0"
+
+
+def _short_cwd(max_len: int = 42) -> str:
+    cwd = str(Path.cwd())
+    home = str(Path.home())
+    if cwd.startswith(home):
+        cwd = "~" + cwd[len(home) :]
+    if len(cwd) <= max_len:
+        return cwd
+    head, tail = cwd[: max_len // 2 - 2], cwd[-(max_len // 2 - 1) :]
+    return f"{head}...{tail}"
+
+
+def _icon() -> Pixels:
+    """Reuses the exact same robot-inside-a-lens image the TUI's Hero
+    widget draws (frozen, non-animated) — the startup banner and the
+    live dashboard used to show two unrelated icons; this keeps the
+    mascot consistent everywhere Handcuff shows its face."""
+    return render_hero_pixels(lens_color=ACCENT)
+
+
+def _left_panel() -> Panel:
+    welcome = Text(f"Welcome back, {getpass.getuser()}!", style="bold white", justify="center")
+    info = Text(
+        f"v{_version()}  -  {getpass.getuser()}  -  {platform.system()} {platform.release()}",
+        style="dim",
+        justify="center",
+    )
+    cwd = Text(_short_cwd(), style="dim", justify="center")
+
+    body = Group(
+        Text(""),
+        Align.center(_icon()),
+        Text(""),
+        Align.center(welcome),
+        Align.center(info),
+        Align.center(cwd),
+        Text(""),
+    )
+    return Panel(body, box=box.ROUNDED, border_style=ACCENT, width=50)
+
+
+def _right_column() -> Text:
+    right = Text()
+    right.append("Quick start\n\n", style=f"bold {ACCENT}")
+    right.append("handcuff watch -- <cmd>\n", style="bold white")
+    right.append("  record a process as it runs\n\n", style="dim")
+    right.append("handcuff tui\n", style="bold white")
+    right.append("  open this live dashboard\n\n", style="dim")
+    right.append("handcuff doctor\n", style="bold white")
+    right.append("  check capture capabilities\n\n", style="dim")
+    right.append("What's new\n", style=f"bold {ACCENT}")
+    right.append("Real OS-level file & network blocking (--enforce)\n", style="dim")
+    right.append("Session replay, export, and trust lists\n", style="dim")
+    return right
+
+
+def banner_grid() -> Table:
+    grid = Table.grid(expand=False, padding=(0, 3))
+    grid.add_column()
+    grid.add_column()
+    grid.add_row(_left_panel(), _right_column())
+    return grid
+
+
+def should_show_banner() -> bool:
+    """Skip the banner when output isn't an interactive terminal (piped/
+    redirected output, CI logs) or when explicitly suppressed — mirrors
+    how `--quiet` already suppresses noise elsewhere in this CLI."""
+    if os.environ.get("HANDCUFF_NO_BANNER"):
+        return False
+    return sys.stdout.isatty()
+
+
+def print_banner(console: Console | None = None, force: bool = False) -> None:
+    if not force and not should_show_banner():
+        return
+    console = console or Console()
+    console.print(banner_grid())
+    console.print()

handcuff-0.2.0/handcuff/capture/base.py

@@ -0,0 +1,28 @@
+"""CaptureBackend protocol (TRD §4).
+
+All platform-specific capture implementations conform to this Protocol
+so the rest of the system (bus, writer, `doctor`) is backend-agnostic.
+"""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator
+from pathlib import Path
+from typing import Protocol, runtime_checkable
+
+from handcuff.core.events import RawEvent
+
+
+@runtime_checkable
+class CaptureBackend(Protocol):
+    name: str
+    capabilities: set[str]  # subset of {"process", "file", "network", "argv", "content"}
+
+    async def start(self, root_pid: int, watch_paths: list[Path]) -> None: ...
+
+    def events(self) -> AsyncIterator[RawEvent]: ...
+
+    async def stop(self) -> None: ...
+
+    @staticmethod
+    def available() -> bool: ...