tycho-cli 0.0.1__py3-none-any.whl

tycho/verify.py

@@ -0,0 +1,202 @@
+"""The engine: reduce check results to a verdict.
+
+M1 is a walking skeleton — `run_stub` returns a hard-coded result set so the CLI
+renders a real block. The `gather -> run_checks` pipeline lands in M2/M3;
+`verdict_of` is already the real reduction (it's pure and cheap to get right now).
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Sequence
+from dataclasses import replace
+import os
+from pathlib import Path, PurePosixPath
+
+from . import checks as checks_mod
+from . import config as config_mod
+from . import events as events_mod
+from . import fsstate, gitstate
+from .config import Config
+from .model import CheckResult, CheckStatus, FileEdit, FileState, GitSnapshot, Session, Verdict
+
+
+def gather(
+    transcript: Path,
+    repo: Path,
+    config: Config | None = None,
+    since: str = "HEAD",
+    parse: Callable[[Path], tuple] | None = None,
+    turn_start: Callable[[Path], float] | None = None,
+    messages: Callable[[Path], tuple] | None = None,
+) -> Session:
+    """Read the transcript + config + file/git state into the immutable Session.
+
+    This is the only I/O boundary on the way in; everything downstream is pure.
+    ``parse`` selects the harness transcript reader (default: Claude Code).
+    ``turn_start`` locates the boundary of the turn under review (TYCHO-17); omit it
+    to scope the whole transcript, which is what a manual ``tycho verify`` audit wants.
+    """
+    events = (parse or events_mod.parse)(transcript)
+    msgs = (messages or events_mod.assistant_messages)(transcript)
+    # Harness transcripts record absolute file paths; git and scope globs speak
+    # repo-relative. Normalize once here so git_state / scope_drift compare like
+    # with like (an edit outside the repo stays absolute — scope_drift flags it).
+    edits = tuple(
+        _with_baseline(replace(fe, path=_relpath(fe.path, repo)), repo, since)
+        for fe in events_mod.file_edits(events)
+    )
+    files = {fe.path: _file_state(repo, fe.path) for fe in edits}
+    return Session(
+        events=events,
+        edits=edits,
+        repo=repo,
+        config=config if config is not None else config_mod.load(repo),
+        files=files,
+        git=_git_snapshot(repo, since),
+        has_tests=_has_tests(repo),
+        turn_start=turn_start(transcript) if turn_start else 0.0,
+        messages=msgs,
+    )
+
+
+_IGNORED_TEST_DIRS = {".git", ".venv", "venv", "node_modules", "vendor", "target", "dist", "build"}
+_TEST_DIRS = {"test", "tests", "spec", "specs", "__tests__"}
+_SUFFIX_TEST_EXTENSIONS = {
+    ".c", ".cc", ".cpp", ".cs", ".dart", ".go", ".java", ".js", ".jsx",
+    ".kt", ".kts", ".m", ".mm", ".php", ".py", ".rb", ".swift", ".ts", ".tsx",
+}
+
+
+def _has_tests(repo: Path) -> bool:
+    """Recognize conventional test files without walking dependencies or build output."""
+    for root, dirs, files in os.walk(repo):
+        dirs[:] = [d for d in dirs if d not in _IGNORED_TEST_DIRS and not d.startswith(".")]
+        try:
+            in_test_dir = any(part.lower() in _TEST_DIRS for part in Path(root).relative_to(repo).parts)
+        except ValueError:
+            in_test_dir = False
+        for name in files:
+            stem, suffix = Path(name).stem, Path(name).suffix
+            if in_test_dir or name == "conftest.py" or stem.startswith("test_"):
+                return True
+            if stem.endswith(("_test", "_spec")) or ".test." in name or ".spec." in name:
+                return True
+            if suffix.lower() in _SUFFIX_TEST_EXTENSIONS and stem.endswith(("Test", "Tests", "Spec")):
+                return True
+            if suffix == ".rs" and name != "build.rs":
+                try:
+                    text = (Path(root) / name).read_text(errors="ignore")
+                    if any(marker in text for marker in ("#[test]", "#[rstest]", "proptest!")):
+                        return True
+                except OSError:
+                    pass
+    return False
+
+
+def _with_baseline(fe: FileEdit, repo: Path, since: str) -> FileEdit:
+    """Recover the pre-edit baseline from git when the harness omitted it.
+
+    Claude Code sends ``originalFile: null`` on a file's *repeat* edits, which would leave
+    the AST tamper checks (`assertion_weakening`/`skip_mock_injection`) with no "before"
+    and silently UNSUPPORTED while still appearing to run (TYCHO-32). ``git show <since>:<path>``
+    is a truthful pre-session baseline for a tracked file, independent of any harness field.
+    Only for in-repo paths; an untracked path returns None and stays a genuine create.
+    """
+    if fe.original is not None or not checks_mod._is_in_repo(fe.path):
+        return fe
+    blob = gitstate.blob_at(repo, since, fe.path)
+    if blob is None:
+        return fe
+    return replace(fe, original=blob, kind="edit")
+
+
+def _relpath(path: str, repo: Path) -> str:
+    """Make an absolute in-repo path repo-relative, always with forward slashes.
+
+    Git (`git diff --name-only`) and the `[scope]` globs both speak POSIX separators, so a
+    Windows backslash here would never reconcile against either — `git_state` would count
+    zero uncommitted and `scope_drift` would miss `src/**` (TYCHO-25). `as_posix()` equals
+    `str()` on *nix, so this is a no-op there.
+    """
+    # `is_absolute()` only knows the *host* flavor: on Windows a POSIX path like
+    # `/repo/old.md` (no drive) reads as relative and never normalizes, while a forward-
+    # slash-normalizing harness or WSL emits exactly that. Try the native flavor first,
+    # then POSIX, so an absolute path is recognized regardless of the OS it's read on.
+    p = Path(path)
+    if p.is_absolute():
+        try:
+            return p.relative_to(repo).as_posix()
+        except ValueError:
+            return path  # edit outside the repo — keep absolute so scope_drift catches it
+    pp = PurePosixPath(path)
+    if pp.is_absolute():
+        try:
+            return pp.relative_to(PurePosixPath(repo.as_posix())).as_posix()
+        except ValueError:
+            return path
+    return path.replace("\\", "/")
+
+
+def _file_state(repo: Path, rel_path: str) -> FileState:
+    abs_path = repo / rel_path
+    text = None
+    if fsstate.exists(abs_path):
+        try:
+            text = abs_path.read_text(encoding="utf-8")
+        except (OSError, UnicodeDecodeError):
+            text = None
+    return FileState(
+        path=rel_path,
+        exists=fsstate.exists(abs_path),
+        mtime=fsstate.mtime(abs_path),
+        current_text=text,
+    )
+
+
+def _git_snapshot(repo: Path, since: str) -> GitSnapshot:
+    if not gitstate.is_repo(repo):
+        return GitSnapshot(is_repo=False, head_sha=None, changed_paths=())
+    return GitSnapshot(
+        is_repo=True,
+        head_sha=gitstate.head_sha(repo),
+        changed_paths=gitstate.diff_names(repo, since),
+    )
+
+
+# file_state/git_state only establish that the edited files exist and are in the
+# repo. That's true of essentially any session that touched a file, and stays true
+# on every later Stop once the work is committed — so on their own they'd turn "I
+# couldn't check anything" into a green VERIFIED. They corroborate a claim; they
+# can't carry one.
+_WEAK_CHECKS = frozenset({"file_state", "git_state"})
+
+
+def verdict_of(results: Sequence[CheckResult]) -> Verdict:
+    """Reduce per-check statuses to one run verdict.
+
+    Any FAIL sinks the run; else any STALE; else one *substantive* PASS is enough
+    to VERIFY (an UNSUPPORTED/INDETERMINATE check does not sink an otherwise-clean
+    run, and a `_WEAK_CHECKS` pass alone is not enough to lift one). With nothing
+    conclusive: all-UNSUPPORTED -> UNSUPPORTED, otherwise INDETERMINATE (including
+    the empty case).
+    """
+    statuses = {r.status for r in results}
+    if CheckStatus.FAIL in statuses:
+        return Verdict.FAILED
+    if CheckStatus.STALE in statuses:
+        return Verdict.STALE
+    if any(r.status is CheckStatus.PASS and r.name not in _WEAK_CHECKS for r in results):
+        return Verdict.VERIFIED
+    if statuses and statuses <= {CheckStatus.UNSUPPORTED}:
+        return Verdict.UNSUPPORTED
+    return Verdict.INDETERMINATE
+
+
+def run_checks(session: Session) -> list[CheckResult]:
+    """Run the enabled checks over the gathered snapshot (pure)."""
+    return checks_mod.run_checks(session)
+
+
+def has_verifiable_activity(session: Session) -> bool:
+    """True when a Stop hook has edits or a recognized test/build command."""
+    return checks_mod.has_verifiable_activity(session)

tycho/version.py

@@ -0,0 +1,99 @@
+"""Is a newer Tycho published? A best-effort, offline-safe update check (TYCHO-53).
+
+**Never runs in the Stop hook and never blocks.** The check is a single stdlib HTTPS GET to
+the package index with a short timeout; anything that goes wrong — offline, slow, blocked,
+unparseable, opted out — returns None and the caller says nothing. The result is cached
+machine-wide so the network is hit at most once a day, and a dismissal counter records how
+often the user waved the notice away.
+
+Surfaced only on the manual/less-frequent paths (`tycho doctor`, `tycho init`, the SessionStart
+agent-bootup hook) — the status bar reads the cache only, never the network.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import time
+import urllib.request
+
+from . import __version__, state
+
+# PyPI distribution name. `tycho` is taken on PyPI by an unrelated project, so we publish and
+# check as `tycho-cli` (TYCHO-73). The import package and CLI command stay `tycho`. (Set to
+# None to make the check inert — it queries no index and never notifies.)
+_DIST_NAME: str | None = "tycho-cli"
+_CHECK_TTL = 86400  # re-hit the index at most once a day
+_TIMEOUT = 2.0  # seconds — a slow index must never make a command drag
+_OPT_OUT_ENV = "TYCHO_NO_UPDATE_CHECK"
+
+
+def _index_url() -> str | None:
+    return f"https://pypi.org/pypi/{_DIST_NAME}/json" if _DIST_NAME else None
+
+
+def _env_opted_out() -> bool:
+    return os.environ.get(_OPT_OUT_ENV, "").strip().lower() in ("1", "true", "yes", "on")
+
+
+def _fetch() -> str | None:
+    """The latest version from PyPI's JSON API, or None on any failure (or no name yet)."""
+    url = _index_url()
+    if not url:
+        return None  # distribution name unset — see _DIST_NAME
+    try:
+        req = urllib.request.Request(
+            url,
+            headers={"Accept": "application/json", "User-Agent": f"tycho/{__version__}"},
+        )
+        with urllib.request.urlopen(req, timeout=_TIMEOUT) as resp:  # noqa: S310 — https literal
+            info = json.loads(resp.read().decode("utf-8")).get("info") or {}
+        version = info.get("version")
+        return version if isinstance(version, str) and version else None
+    except Exception:
+        return None  # offline, slow, blocked, unparseable — say nothing
+
+
+def refresh() -> str | None:
+    """Newest published version, hitting the network only if the cache is stale (≤ once/day)
+    and the user hasn't opted out. Cached machine-wide; never raises."""
+    if _env_opted_out():
+        return None
+    cache = state.read_update_cache()
+    if cache.get("latest") and (time.time() - cache.get("checked_at", 0)) < _CHECK_TTL:
+        return cache["latest"]
+    got = _fetch()
+    if got:
+        state.write_update_cache(latest=got, checked_at=time.time())
+        return got
+    return cache.get("latest")
+
+
+def _tuple(v: str) -> tuple[int, ...]:
+    """Numeric release tuple: "0.1.0" -> (0, 1, 0). Non-numeric suffixes are dropped — fine
+    for the 0.0.x-alpha → 0.1.0 scheme (no pre-release tags in play)."""
+    return tuple(int("".join(c for c in part if c.isdigit()) or 0) for part in v.split("."))
+
+
+def is_newer(candidate: str, than: str) -> bool:
+    return _tuple(candidate) > _tuple(than)
+
+
+def notice(refresh_first: bool = False) -> str | None:
+    """One line if a newer version exists and the user hasn't opted out or dismissed it — else
+    None. `refresh_first=True` permits the network check (doctor/init/bootup); the default reads
+    only the cache, which is what the status bar must use. Never raises."""
+    if _env_opted_out():
+        return None
+    try:
+        newest = refresh() if refresh_first else state.read_update_cache().get("latest")
+        if not isinstance(newest, str) or not is_newer(newest, __version__):
+            return None
+        if state.read_update_cache().get("dismissed_version") == newest:
+            return None  # they waved this exact version off
+        return (
+            f"A newer Tycho is available: {newest} (you have {__version__}). "
+            f"Run `tycho update`; dismiss with `tycho update --skip` or set {_OPT_OUT_ENV}=1."
+        )
+    except Exception:
+        return None

tycho_cli-0.0.1.dist-info/METADATA

@@ -0,0 +1,379 @@
+Metadata-Version: 2.4
+Name: tycho-cli
+Version: 0.0.1
+Summary: Tycho — a free, offline, open-source local verifier that proves an AI agent actually did what it claims, from git, the filesystem, process exit codes, and the harness event stream. No account, no LLM in the trust path.
+Project-URL: Homepage, https://swail.dev/tycho
+Project-URL: Repository, https://github.com/swail-labs/tycho
+Project-URL: Issues, https://github.com/swail-labs/tycho/issues
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: agents,ai,claude-code,codex,cursor,opencode,verification
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.11
+Provides-Extra: dev
+Requires-Dist: build>=1; extra == 'dev'
+Requires-Dist: pytest-cov>=5; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Tycho
+
+A free, offline, open-source **local verifier** that proves an AI coding agent actually did what it
+claims — from git, the filesystem, process exit codes, and the harness event stream. When an agent
+says "done," Tycho turns some ✅s into `FAILED` / `STALE` / `INDETERMINATE` with per-check evidence,
+*before* that ✅ reaches you.
+
+- **No account, no network, no LLM in the trust path.** Only code renders a verdict.
+- **Stdlib only**, Python ≥ 3.11. Nothing to audit, trivial install.
+- **Claude Code, Cursor, Codex, and OpenCode** supported (auto-detected).
+- **Linux, macOS, and Windows** — see [Platforms](#platforms).
+
+## Platforms
+
+| OS | Status | Verified by |
+|----|--------|-------------|
+| Linux | Supported | CI: `ubuntu-latest`, Python 3.11 / 3.12 / 3.13 — full suite, `ruff`, and a wheel + sdist install into a clean venv |
+| Windows | Supported | CI: `windows-latest`, Python 3.12 — same suite, plus the `.exe` console-script hook under cp1252/backslash |
+| macOS | Supported | Development baseline; not gated in CI |
+
+**WSL2 is Linux** (a real Linux kernel), so it's covered by the Linux row. Install and run Tycho
+*inside* the distro — launch your agent from the WSL shell — rather than driving `wsl.exe` from a
+Windows-hosted agent, so Tycho's Stop hook and the commands it verifies share one environment.
+
+## Install
+
+Tycho is one stdlib-only CLI. The PyPI package is **`tycho-cli`** (the name `tycho` is taken by
+an unrelated project); it installs the **`tycho`** command. Install it however you manage tools:
+
+```sh
+uv tool install tycho-cli     # uv (recommended)
+pipx install tycho-cli        # or pipx
+```
+
+Both drop the `tycho` command on your PATH in its own isolated environment. Other paths:
+
+```sh
+uvx --from tycho-cli tycho <command>   # run once, no install (uv)
+uv add tycho-cli                       # add to a project's dependencies
+pip install --user tycho-cli           # plain pip
+```
+
+Prefer an isolated *tool* install (`uv tool install` / `pipx`) over a bare `pip install`, which
+drops the CLI into whatever environment you happen to be in.
+
+> **Not on PyPI yet.** The first release is still landing, so the commands above 404 for now.
+> Until then, install from a source checkout — same isolated `tycho` command, no index needed:
+>
+> ```sh
+> uv tool install .            # from a clone of this repo
+> uvx --from . tycho <command> # or run once, no install
+> ```
+
+Then wire it into your repo (or let Tycho offer to on first run):
+
+```sh
+tycho init
+```
+
+## Quickstart
+
+```sh
+tycho init              # install the completion hook into the harnesses you actually have
+                        # (asks per harness; idempotent, self-healing, repo-local only)
+tycho init --yes        # skip the prompts (scripts and CI)
+```
+
+Tycho only touches harnesses it finds — Claude Code, Cursor, Codex, or OpenCode — and only inside this
+repo. It merges with hooks you already have, backs up anything it changes, and refuses to touch a config
+it can't parse rather than risk it.
+
+On Claude Code it also adds a status-bar badge and a set of `/tycho` slash commands, so you can see it's
+on and drive it without leaving the session — see [In Claude Code](#in-claude-code) below. On the other
+three harnesses, `tycho status` prints that same badge for a shell prompt or tmux status line — see
+[The badge in any shell](#the-badge-in-any-shell).
+
+That's it. The next time an agent finishes a turn, Tycho verifies it automatically and prints the
+verdict. To run it by hand:
+
+```sh
+tycho verify                     # auto-discovers the most-recently-used session and verifies it
+tycho verify --harness cursor    # force a harness (default: whichever ran most recently)
+tycho verify --session <path>    # verify a specific transcript
+tycho verify --claim "added rate limiting, tests pass"   # echo the claim above the verdict
+tycho help                       # what Tycho is, whether it's live here, and every command
+tycho status                     # the one-line status-bar indicator (what Claude Code renders)
+tycho count                      # how many problems Tycho has caught — in this repo, and all-time
+tycho run -- pytest -q           # run a command so its true exit code is seen (see "tycho run" below)
+tycho scope list                 # show/edit which files the agent may edit (see "Scope" below)
+tycho relay                      # let the agent see its verdict & work till VERIFIED (opt-in; see below)
+tycho --version                  # print the version
+tycho --help                     # full usage (also `tycho verify --help`)
+```
+
+```
+🔍 Tycho: FAILED
+  ✗ test_freshness — auth_test.py passed 14:22:01, auth.py edited 14:22:47 (46s later)
+  ✗ assertion_weakening — 2 assertions removed from test_login_expiry
+  ✓ command_execution — pytest ran, exit 0
+  • scope_drift — no [scope] set — run `tycho scope add '<glob>'` to bound edits (zero-config)
+```
+
+`tycho verify` exits non-zero on an adverse finding so you can gate in `pre-push`/CI. The completion
+hook never blocks — it annotates; you decide.
+
+| Exit | Meaning |
+|---|---|
+| `0` | `VERIFIED` / `UNSUPPORTED` / `INDETERMINATE` — nothing adverse found |
+| `1` | `FAILED` — a check proved the claim wrong |
+| `2` | usage error |
+| `3` | `STALE` — edits landed after the last passing test run |
+| `4` | Tycho could not complete (unreadable transcript/config) |
+
+`FAILED` and `STALE` are separate codes so you can pick which one blocks: gate on `1` alone, or on
+both.
+
+## `tycho run` — when a test run is hidden from Tycho
+
+Tycho recognises a test/build run from the command in the transcript. It reads *through* the common
+ways a runner is wrapped — a pipe (`pytest | tail`), a variable interpreter (`"$PY" -m pytest`), and
+nested shells (`wsl.exe -d Ubuntu -- bash -c 'pytest'`, `ssh host 'pytest'`) — automatically, with
+nothing to remember. **WSL runs verify on their own; you don't need `tycho run` for them.**
+
+The one case it can't see is when the runner's name isn't in the command at all — a Makefile target
+(`make test`), a shell alias, or a `./run-tests.sh` that calls pytest inside. For those, prefix it:
+
+```sh
+tycho run -- make test
+```
+
+`tycho run` execs the command, forwards its output and exit code **unchanged**, and lets Tycho read
+the runner's true status. It's a thin, safe wrapper — never use it as a habit for WSL or piped runs,
+only where the runner is genuinely hidden behind indirection.
+
+## Scope — bounding what the agent may edit
+
+Tycho is **zero-config**: with no `.tycho.toml`, `scope_drift` reports `UNSUPPORTED` and every other
+check runs exactly as normal. Nothing assumes the file exists.
+
+Opt in when you want to bound *where* the agent edits. `tycho init` drops a starter `.tycho.toml`
+(empty, so behaviour is unchanged until you add a glob), and you manage the allowlist with:
+
+```
+tycho scope add 'src/**' 'tests/**'   # allow these; an edit elsewhere FAILs scope_drift
+tycho scope remove 'tests/**'         # drop one or more
+tycho scope set 'src/**'              # replace the whole list
+tycho scope list                      # show the current bounds
+
+tycho scope set '**'                  # allow the whole tree…
+tycho scope add --exclude 'LICENSE'   # …but carve this back out (exclude wins)
+```
+
+`set`, `add`, and `remove` each take **one or more** globs — quote them so your shell keeps them
+literal. The bound is an **explicit, deterministic** declaration: Tycho stores exactly what you wrote
+and never infers scope from the prompt. Set it once as a standing bound, or change it whenever the task
+changes. In Claude Code the same four are `/tycho-scope-list`, `/tycho-scope-set`, `/tycho-scope-add`,
+and `/tycho-scope-remove`.
+
+**Excluding paths.** Add `--exclude` to `set`/`add`/`remove` to edit a **denylist** instead of the
+allowlist: a path that matches `exclude` FAILs `scope_drift` even if it also matches `include` — exclude
+wins. This lets you allow a broad area and carve specific files back out (e.g. `include = ["**"]`,
+`exclude = ["LICENSE"]` allows the whole repo but that one file). An empty exclude is a pure allowlist,
+exactly as before; exclude has no effect while `include` is empty (scope stays zero-config `UNSUPPORTED`).
+
+## In Claude Code
+
+`tycho init` wires Claude Code up with a status badge and slash commands, so you can drive Tycho without
+leaving the session. Everything here also runs as a plain `tycho <command>` in your terminal — the slash
+commands are just the in-editor shortcut.
+
+**Slash commands.** Type `/` and each shows with its own description:
+
+| Command | Does |
+|---|---|
+| `/tycho <args>` | run any Tycho subcommand, e.g. `/tycho verify --claim "added rate limiting"` |
+| `/tycho-verify` | verify the latest session and render a verdict |
+| `/tycho-status` | the one-line badge (what the status bar renders) |
+| `/tycho-doctor` | full diagnostics: is Tycho installed, current, and firing? |
+| `/tycho-help` | what Tycho is, whether it's live here, and every command |
+| `/tycho-hide` · `/tycho-show` | hide / show the status badge |
+| `/tycho-relay` · `-on` · `-off` | show / turn on / turn off the verdict relay (see [below](#let-the-agent-see-its-own-verdict--the-relay)) |
+| `/tycho-scope-list` · `-set` · `-add` · `-remove` | show or edit the files the agent may edit (each `set`/`add`/`remove` takes one or more globs) |
+
+**Status badge.** A `[TYCHO]` indicator in the status bar, coloured by the last run:
+
+| Color | Meaning |
+|---|---|
+| 🟢 green | last run `VERIFIED` |
+| 🔴 red | last run `FAILED` or `STALE` — something to look at |
+| 🔵 blue | verifying right now — a run is in flight this turn |
+| 🟡 yellow | an `INDETERMINATE` run (ran, couldn't conclude) |
+| ⚪ grey | nothing to say yet — never fired here, `UNSUPPORTED`, or a turn with nothing to verify |
+
+It settles on green or red once a real verdict exists; blue is only the in-flight moment,
+yellow is the inconclusive-but-noteworthy run, and grey is the honest "no signal" — including a
+fresh install that hasn't fired yet. The colors are muted on purpose, to stay readable on a dark
+terminal.
+
+`tycho verify` updates the badge too, so a manual verify that comes back `VERIFIED` turns it green. If you
+already run a status line — a third-party badge, a shell prompt — Tycho **composes** with it instead of
+replacing it: it takes Claude Code's single `statusLine` slot, runs your existing command too, and renders
+both (`[OTHER] [TYCHO]`). Nothing you had is lost, and `tycho uninstall` restores it.
+
+**Toggle the badge.** `/tycho-hide` (or `tycho status --off`) hides only Tycho's segment — the hook keeps
+verifying every turn; `/tycho-show` (or `tycho status --on`) brings it back. `TYCHO_STATUS=off` hides it
+everywhere for a session.
+
+## Let the agent see its own verdict — the relay
+
+By default Tycho's verdict on Claude Code is **human-only**: it renders to your terminal and never enters
+the model's context, so the agent can't see when its own turn came back `FAILED` or `STALE`. That's the
+safe default — **Tycho free never spends your context or tokens unless you ask it to.**
+
+Turn on the **verdict relay** and Tycho feeds a non-`VERIFIED` verdict back to the agent as it finishes a
+turn, so the agent keeps working **until the verdict is `VERIFIED`** — catching a false "done" the moment
+it happens instead of waiting for you to paste the verdict back in. `tycho init` asks once (default **no**)
+when a repo has no `.tycho.toml` yet; if you already have one, it leaves your setting alone and just points
+you at the toggle. Flip it any time:
+
+```sh
+tycho relay            # show the current setting
+tycho relay --on       # feed non-VERIFIED verdicts back to the agent (works until VERIFIED)
+tycho relay --off      # back to human-only (the default)
+```
+
+In Claude Code the same three are `/tycho-relay`, `/tycho-relay-on`, and `/tycho-relay-off`; bare
+`/tycho-relay` shows the current status and how to toggle. The setting is a hand-editable, per-repo key in
+`.tycho.toml` (`[relay] enabled`), Claude-only, and never blocks — the Stop hook still exits 0.
+
+**It is bounded — no infinite loops.** Each user turn can be auto-continued at most **3 times** before
+Tycho goes quiet and hands control back to you, so a verdict the agent can't satisfy converges on a hard
+stop, not an endless cycle. A fresh prompt from you resets the leash. Change the ceiling with
+`TYCHO_RELAY_MAX` (e.g. `TYCHO_RELAY_MAX=5`; `0` disables the auto-continue entirely, leaving the verdict as
+a one-shot note the agent sees but isn't pushed to act on).
+
+**Estimated extra token usage.** With the relay **off** (default), **zero** — nothing reaches the model.
+With it **on**, each turn that ends non-`VERIFIED` costs:
+
+- the injected verdict itself — small and fixed, roughly **120–200 tokens** per re-check (the verdict lines
+  plus a one-paragraph guard), and
+- **up to `TYCHO_RELAY_MAX` extra agent turns** (default 3) — the real cost, since each is a full generation
+  in which the agent reads context and works. Budget on the order of *your agent's normal per-turn token
+  use × up to 3* for a turn Tycho keeps re-checking; a turn that's already `VERIFIED` adds **nothing**.
+
+So the relay trades tokens for the agent catching its own mistakes without you in the loop. Leave it off for
+the cheapest, quietest default; turn it on when you'd rather the agent fix a bad turn before it reaches you.
+
+## The badge in any shell
+
+Only the *wiring* is Claude-only. `statusLine` is the one harness setting that means "run this command and
+render its stdout", so `tycho init` has nowhere to hang the badge on Cursor, Codex, or OpenCode. The badge
+itself doesn't care: `tycho status` reads `.tycho/` off disk and prints one line, whichever agent wrote the
+state. Call it from anything that renders a command:
+
+```sh
+PS1='$(tycho status) '$PS1                                        # bash / zsh prompt
+set -g status-right '#(cd #{pane_current_path} && tycho status)'  # tmux (in tmux.conf)
+```
+
+```toml
+[custom.tycho]                                # starship (in starship.toml)
+command = "tycho status"
+when = true
+```
+
+No stdin needed — with no JSON on stdin it resolves the repo from the current directory, walking up to
+find `.tycho/`, so the badge stays put as you `cd` around the tree. It prints nothing in repos where
+Tycho isn't installed, so it stays out of every other prompt you have. `tycho status --off` / `--on` and
+`TYCHO_STATUS=off` work here exactly as they do in Claude Code.
+
+## Is the hook still firing?
+
+A silently dead hook is the worst failure a verifier has — silence looks exactly like "everything
+passed." `tycho doctor` checks, without editing anything, that Tycho's entry is still in each harness's
+config, that the command it would run resolves to a real executable, and when the hook last fired:
+
+```sh
+tycho doctor    # exits 0 when healthy, 5 when installed-but-not-working
+```
+
+Repair is always the same self-healing `tycho init`. `tycho verify` runs the config half of this check
+too, warning on stderr if the hook is broken. See [`docs/hooks.md`](docs/hooks.md#is-it-still-working-tycho-doctor).
+
+## Uninstall
+
+```sh
+tycho uninstall                  # remove Tycho's hooks from every harness
+tycho uninstall --harness codex  # just one
+tycho uninstall --purge          # hooks, plus this repo's .tycho/ state and .tycho.toml config
+```
+
+Only Tycho's own entries come out — your other hooks, and any unrelated settings in the same file,
+are left exactly as they were. It's idempotent, so running it twice is safe.
+
+By default uninstall leaves two repo-local files behind: `.tycho/` (the catch tally and evidence trail)
+and `.tycho.toml` (your scope/checks config). Add **`--purge`** to delete those too — an explicit opt-in,
+never the default, since it drops your catch history. It stays repo-local; the machine-wide all-time tally
+under `~/.local/share/tycho` is never touched.
+
+Removing the hooks and removing the package are two separate steps: uninstall first (otherwise the
+harness is left calling a command that no longer exists), then remove the package the same way you
+installed it — `pipx uninstall tycho`, `pip uninstall tycho`, or deleting the standalone binary.
+
+## The checks
+
+`command_execution` · `test_freshness` · `test_provenance` · `assertion_weakening` ·
+`skip_mock_injection` · `file_state` · `git_state` · `scope_drift` · `tool_call_provenance`. A check
+that can't run returns `UNSUPPORTED`/`INDETERMINATE` with a reason — Tycho degrades honestly rather
+than guess.
+
+`tool_call_provenance` catches an agent that *claims* a tool action it never took. It currently
+recognizes two families of claim — web search/fetch and issue-tracker actions (Jira/Linear). Broader
+tool-call coverage — calendar, email, file/drive, code execution, and other connectors — is **not yet
+supported and is in development**; until then a claim it can't classify is left `UNSUPPORTED`, never
+guessed.
+
+This is a **scope limitation, not a finished feature** — treat its result as advisory for now. Two
+consequences follow from how narrowly it's currently drawn, both of which we'll address as the family
+table is widened:
+
+- **Missed claims ("no tool-action claims recognized").** The claim-recognition patterns are narrower
+  than real phrasing, so a turn that genuinely performed a supported action can still read as *no claim
+  recognized* — e.g. issue-tracker verbs like "parented", "linked", "added N links", or "created ticket
+  X" that fall outside the pattern set. That's a recall gap, not a statement that no tools ran.
+- **Coarse (potentially false-positive) matches.** Within a supported family the match is **broad —
+  family-presence only, with no content-correlation.** A claim is considered backed if *some* tool call
+  of that family occurred; it does not yet verify that the specific claimed action (that ticket, that
+  URL) is the one the tool actually touched. So a claim could be marked backed by an unrelated call in
+  the same family.
+
+Both are deliberate: the check is tuned to **never emit a false FAIL** today, at the cost of these gaps.
+Tightening the phrasing coverage and adding safe content-correlation is planned, not shipped — so for
+now, read `tool_call_provenance` as a hint, and confirm from the transcript when it matters.
+
+## How it works
+
+The engine is pure and harness-agnostic: `gather → check → verdict` over an immutable snapshot, all I/O
+at the edges. The four harnesses differ only in transcript format, repo field, and output channel —
+isolated in one adapter. See [`docs/hooks.md`](docs/hooks.md) for the multi-harness design.
+
+Tycho looks for each agent's sessions under the usual `~/.claude`, `~/.cursor`, `~/.codex`, and
+`~/.local/share/opencode`. If yours live elsewhere, set `TYCHO_CLAUDE_HOME`, `TYCHO_CURSOR_HOME`,
+`TYCHO_CODEX_HOME`, or `TYCHO_OPENCODE_HOME` to the directory that holds them — each agent's own
+variable (`CLAUDE_CONFIG_DIR`, `CODEX_HOME`, `XDG_DATA_HOME`) is honored too. See
+[`docs/hooks.md`](docs/hooks.md#overriding-where-an-agents-data-lives).
+
+Tycho's own machine-level state — just the all-time tally behind `tycho count` — lives under
+`~/.local/share/tycho`; set `TYCHO_HOME` (or `XDG_DATA_HOME`) to move it. Everything else Tycho
+knows is per-repo, in `<repo>/.tycho/`.
+
+## License
+
+Apache-2.0.