tycho-cli 0.0.1__py3-none-any.whl

tycho/init.py

@@ -0,0 +1,1018 @@
+"""`tycho init` / `tycho uninstall` — manage the completion hook in each harness's config.
+
+Everything written here is **repo-local**: only `<repo>/.claude`, `.cursor`, `.codex`,
+and `.opencode` are ever touched. A harness's home directory under `$HOME` is *read*
+(never written) as a detection signal — it tells us the harness exists on this machine
+and is therefore worth hooking up in this repo.
+
+Idempotent both ways: re-running init never duplicates the entry and never clobbers
+hooks the user already configured; uninstall removes only Tycho-owned entries and is
+a no-op once they're gone. The config shapes differ per harness, so each gets its own
+installer/uninstaller; the load/merge/write skeleton is shared.
+
+Install and uninstall share `_is_tycho_hook` + `_strip_claude_tycho` on purpose — the
+rule for "which entry is ours" must never drift between the two, or uninstall would
+orphan exactly the entries install replaces.
+
+This runs against a real developer's real settings, so every mutation is defensive:
+refuse what we can't parse instead of "recovering" it to `{}` and writing that back,
+back up before touching, write atomically so an interrupted run can't truncate the
+original, and skip the write entirely when the file is already correct.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import shutil
+import sys
+import shlex
+from pathlib import Path
+
+from . import config as config_mod
+from . import harness as harness_mod
+from . import opencode as opencode_mod
+from . import state
+
+
+# The header install stamps into the OpenCode plugin, and the proof uninstall looks
+# for before deleting it. One constant so the two can't drift apart.
+_PLUGIN_MARKER = "// Generated by tycho init."
+
+# Stamped into the `/tycho` slash-command file; the proof uninstall looks for before
+# deleting it, so a hand-written tycho.md is never removed. Kept as an HTML comment so it
+# renders invisibly if the file is ever previewed as Markdown.
+_SLASH_MARKER = "<!-- Generated by tycho init. -->"
+
+# Marker for "we declined to touch this file". Built into the status line from the same
+# constant the CLI matches on, so the exit code can't drift from the message.
+REFUSED = ": refused — "
+
+_BACKUP_SUFFIX = ".tycho.bak"
+_TMP_SUFFIX = ".tycho-tmp"
+
+HARNESSES = ("claude", "cursor", "codex", "opencode")
+
+# Where each harness keeps its per-repo config. A harness creates this on first use in
+# a repo, which makes its presence a detection signal in its own right.
+_LOCAL_DIR = {"claude": ".claude", "cursor": ".cursor", "codex": ".codex", "opencode": ".opencode"}
+
+# statusLine poll cadence, so the badge settles on the verdict shortly after a turn rather
+# than lagging to the next prompt (TYCHO-59). Claude Code's `refreshInterval` is milliseconds
+# (contract in docs/harness-support.md); 1s is responsive and the read it triggers is cheap
+# (one small JSON file, no engine). A user who sets their own value keeps it.
+_STATUS_REFRESH_MS = 1000
+
+
+class ConfigRefused(Exception):
+    """This file must not be written — malformed, unreadable, or read-only.
+
+    The message always carries the fix, not just the complaint: whoever sees it is
+    mid-install and needs to know what to do about it.
+    """
+
+
+def _quote_program(path: str) -> str:
+    """Wrap a program path in double quotes if it contains a space.
+
+    Absolute paths on Windows routinely hold spaces (``C:\\Users\\...\\Swail Labs\\``);
+    an unquoted one splits into two argv tokens under both cmd and /bin/sh, so the
+    harness runs ``...\\Swail`` and fails. Double quotes work in both shells.
+    """
+    return f'"{path}"' if " " in path and not path.startswith('"') else path
+
+
+def hook_command() -> str:
+    """A command the harness's plain `/bin/sh` can actually run.
+
+    The Stop hook fires without an activated venv, so a bare ``tycho`` only works
+    when it's on the global PATH (a pipx/global install). Otherwise resolve an
+    absolute path: the installed console script if we can find one, else the
+    current interpreter with ``-m``. Absolute paths run regardless of PATH.
+    """
+    return _command_for("hook")
+
+
+def status_command() -> str:
+    """Same resolution as `hook_command`, for the status bar (TYCHO-39)."""
+    return _command_for("status")
+
+
+def _command_for(subcommand: str) -> str:
+    # Claude Code runs hook/statusLine commands through Git Bash, which consumes unquoted
+    # backslashes as escapes — so a native Windows path silently fails to resolve and the
+    # hook/status just never fires. Emit forward slashes, per Claude Code's own shipped
+    # guidance. A blunt separator swap (not Path.as_posix, which is host-flavored) so it's
+    # correct for a Windows path on any host — sys.executable / the console script never
+    # carry a literal backslash on POSIX (TYCHO-43).
+    found = shutil.which("tycho")
+    program = _quote_program((found or sys.executable).replace("\\", "/"))
+    return f"{program} {subcommand}" if found else f"{program} -m tycho.cli {subcommand}"
+
+
+def hook_argv(command: str) -> list[str]:
+    """Split a hook command into argv, keeping Windows paths intact.
+
+    ``posix=False`` so a ``C:\\...`` path keeps its backslashes (POSIX mode treats ``\\``
+    as an escape and mangles it), then strip the quotes it leaves on a token. An
+    unbalanced quote yields ``[]`` ("nothing runnable"). Behaves like the old POSIX split
+    on the quote- and backslash-free commands *nix produces.
+    """
+    try:
+        argv = shlex.split(command, posix=False)
+    except ValueError:
+        return []
+    return [a.strip('"') for a in argv]
+
+
+def _is_ours(command: object, subcommand: str) -> bool:
+    """True if an existing entry is one of ours (any resolved form).
+
+    Install and uninstall both route through this, so "which entry is ours" can't drift
+    between them — uninstall must remove exactly what install would replace. Tolerant of
+    the platform executable suffix (on Windows the console script is ``tycho.exe``, so the
+    command ends ``tycho.EXE hook`` not ``tycho hook``), surrounding quotes, and both path
+    separators, so the answer is identical on every OS (matching, not resolution: no
+    filesystem access).
+    """
+    if not isinstance(command, str) or not command.endswith(f" {subcommand}"):
+        return False
+    program = command[: -len(f" {subcommand}")].rstrip()
+    if program.endswith("tycho.cli"):  # `<python> -m tycho.cli <subcommand>`
+        return True
+    base = re.split(r"[\\/]", program.strip('"'))[-1]  # basename, either separator
+    return base.lower() in ("tycho", "tycho.exe")
+
+
+def _is_tycho_hook(command: object) -> bool:
+    return _is_ours(command, "hook")
+
+
+def _is_tycho_status(command: object) -> bool:
+    return _is_ours(command, "status")
+
+
+def _is_tycho_session_start(command: object) -> bool:
+    return _is_ours(command, "session-start")
+
+
+def _is_tycho_prompt_submit(command: object) -> bool:
+    return _is_ours(command, "prompt-submit")
+
+
+def _is_tycho_owned(command: object) -> bool:
+    """Any hook command Tycho installs into a matcher-group — Stop (`hook`), bootup
+    (`session-start`), or run-start (`prompt-submit`). All live in `hooks.*` groups, so one
+    predicate strips any of them."""
+    return (
+        _is_tycho_hook(command)
+        or _is_tycho_session_start(command)
+        or _is_tycho_prompt_submit(command)
+    )
+
+
+def config_path(repo: Path, name: str) -> Path:
+    """Where `name`'s repo-local config lives. One map, so init and doctor can't disagree.
+
+    Resolved from the same root as `.tycho/` (TYCHO-79): a harness config is repo-local in
+    exactly the way our state is, and if the two disagree, `doctor` run from a subdirectory
+    finds the root's install record, looks for the harness config beside *itself*, and cries
+    HOOK BROKEN over a hook that is wired fine.
+    """
+    return state.root_for(repo) / {
+        "claude": ".claude/settings.json",
+        "cursor": ".cursor/hooks.json",
+        "codex": ".codex/hooks.json",
+        "opencode": ".opencode/plugins/tycho.js",
+    }[name]
+
+
+def installed_command(repo: Path, name: str) -> str | None:
+    """The tycho hook command `name` would actually run, read back from its own config.
+
+    The config is the truth — not what we *meant* to install. `doctor` diagnoses what the
+    harness will really execute, which is the only thing that decides whether Tycho fires.
+    Raises ConfigRefused if the config can't be read (same rule as everywhere else).
+    """
+    path = config_path(repo, name)
+    if name == "opencode":
+        text = _current_text(path)
+        if text is None or _PLUGIN_MARKER not in text:
+            return None
+        # The plugin holds its argv as a JSON array: `const command = ["...", "hook"]`.
+        match = re.search(r"^const command = (\[.*\])$", text, re.MULTILINE)
+        if not match:
+            return None
+        try:
+            return shlex.join(json.loads(match.group(1)))
+        except (json.JSONDecodeError, TypeError):
+            return None
+    data = _load(path)
+    hooks = data.get("hooks") if isinstance(data.get("hooks"), dict) else {}
+    if name == "cursor":
+        entries = hooks.get("stop") or []
+    else:
+        entries = [h for g in (hooks.get("Stop") or []) if isinstance(g, dict) for h in (g.get("hooks") or [])]
+    for entry in entries:
+        if isinstance(entry, dict) and _is_tycho_hook(entry.get("command")):
+            return entry["command"]
+    return None
+
+
+# --- detection ---------------------------------------------------------------
+#
+# "Is this harness worth hooking up here?" Two cheap directory probes, either sufficient:
+# the harness has run in this repo (dotdir exists) or is installed for the user (home
+# exists) — never executed. A false negative just means the user passes `--harness`.
+
+
+def detect(repo: Path) -> list[str]:
+    """Supported harnesses that appear to be present, in stable order."""
+    return [name for name in HARNESSES if _is_present(name, repo)]
+
+
+def _is_present(name: str, repo: Path) -> bool:
+    if (repo / _LOCAL_DIR[name]).is_dir():
+        return True
+    if name == "opencode":
+        # OpenCode's data lives in an XDG data dir, not a ~/.<name> dotdir.
+        return opencode_mod.db_path().parent.is_dir()
+    return harness_mod.home(name).is_dir()
+
+
+def _ask(name: str) -> bool:
+    """Prompt before touching one harness. Default yes; anything but n/no is yes."""
+    try:
+        reply = input(f"tycho: install the {name} completion hook in this repo? [Y/n] ")
+    except EOFError:
+        return False
+    return reply.strip().lower() not in ("n", "no")
+
+
+def init(
+    repo: Path,
+    only: str | None = None,
+    assume_yes: bool = False,
+    confirm=None,
+    relay_confirm=None,
+) -> list[str]:
+    """Install the repo-local Stop hook per harness; return status lines.
+
+    Touches only harnesses that are actually present, and asks before each one. With
+    ``only`` set (a harness name), install just that harness and skip detection — the
+    user named it, so its absence is not our call to second-guess. ``assume_yes`` skips
+    the prompts for scripted/CI installs; ``confirm`` overrides the prompt (tests).
+    """
+    installers = {
+        "claude": _install_claude,
+        "cursor": _install_cursor,
+        "codex": _install_codex,
+        "opencode": _install_opencode,
+    }
+    if only:
+        names = [only]
+    else:
+        names = detect(repo)
+        if not names:
+            return ["no supported harness detected here — pass --harness <name> to install anyway"]
+    ask = confirm or _ask
+    if not assume_yes and confirm is None and not sys.stdin.isatty():
+        # Nobody's there to answer, and installing unasked is exactly what this ticket
+        # exists to stop. Say how to proceed rather than silently doing nothing.
+        return [f"tycho init needs a terminal to confirm ({', '.join(names)}) — pass --yes to install non-interactively"]
+
+    lines = []
+    installed = []
+    for name in names:
+        if not assume_yes and not ask(name):
+            lines.append(f"{name}: skipped")
+            continue
+        try:
+            lines.append(installers[name](repo))
+            installed.append(name)
+        except ConfigRefused as exc:
+            lines.append(f"{name}{REFUSED}{exc}")
+    installed_any = bool(installed)
+    # Did the user bring their own .tycho.toml? Capture it *before* `ensure` creates one, so the
+    # relay setup below can tell "user already configured this" from "we just seeded it" (TYCHO-114).
+    config_existed = config_mod.path(repo).is_file()
+    # Seed a .tycho.toml so scope is discoverable and editable (TYCHO-55) — but only once a
+    # harness actually got wired: no install (declined/refused) means don't leave config
+    # behind. Harness-agnostic, empty (behaviour unchanged until a glob is added), never
+    # clobbers an existing one (TYCHO-6). Appended last so a harness line stays lines[0].
+    if installed_any and config_mod.ensure(repo):
+        lines.append(
+            f"created {config_mod.CONFIG_NAME} — no scope set yet, so nothing changes until you "
+            f"run `tycho scope add '<glob>'`"
+        )
+    lines += _offer_relay(repo, "claude" in installed, assume_yes, config_existed, relay_confirm)
+    return lines
+
+
+def _ask_relay() -> bool:
+    """Prompt (default NO) to enable the verdict relay — it feeds Tycho's verdict into the
+    agent and spends extra tokens, so it must be *explicitly* opted into (TYCHO-35). Only
+    'y'/'yes' enables; a bare Enter or EOF leaves it off."""
+    try:
+        reply = input(
+            "tycho: let the agent see its own verdict and keep working until VERIFIED? This feeds "
+            "Tycho's verdict back into the agent (extra tokens; the loop is bounded). [y/N] "
+        )
+    except EOFError:
+        return False
+    return reply.strip().lower() in ("y", "yes")
+
+
+def _offer_relay(
+    repo: Path, claude_installed: bool, assume_yes: bool, config_existed: bool, relay_confirm=None
+) -> list[str]:
+    """Set up the verdict relay at install time (TYCHO-35/114, Claude only). If the user already
+    had a `.tycho.toml`, *respect* its relay choice and just say how to change it; otherwise ask
+    (default NO) and write the initial state. A scripted install (`--yes`, no TTY) never enables
+    it silently. ``relay_confirm`` overrides the prompt for tests. Returns status lines to print."""
+    if not claude_installed:
+        return []
+    if config_existed:
+        # The user brought their own config — don't re-ask or override it. Point at how to change.
+        state_txt = "ON" if state.relay_enabled(repo) else "OFF"
+        return [
+            f"claude: verdict relay is {state_txt} (from your {config_mod.CONFIG_NAME}). Change it "
+            f"with `tycho relay --on|--off`, or /tycho-relay-on / /tycho-relay-off in Claude Code."
+        ]
+    interactive = relay_confirm is not None or (not assume_yes and sys.stdin.isatty())
+    if not interactive:
+        return []  # scripted / no TTY: leave the default (off), already written by config.ensure
+    if (relay_confirm or _ask_relay)():
+        state.set_relay_enabled(repo, True)
+        return [
+            f"claude: verdict relay ON — the agent will see a non-VERIFIED verdict and keep working "
+            f"until VERIFIED, up to {state.relay_max()} automatic re-checks per turn (extra tokens). "
+            f"Turn it off with `tycho relay --off` or /tycho-relay-off."
+        ]
+    return [
+        "claude: verdict relay OFF (the default) — turn it on with `tycho relay --on` or "
+        "/tycho-relay-on to have the agent work until VERIFIED."
+    ]
+
+
+def _wired_here(repo: Path, name: str) -> bool:
+    """Does `name`'s config already carry our hook? A config we can't read counts as wired —
+    we don't offer to overwrite something we can't inspect."""
+    try:
+        return installed_command(repo, name) is not None
+    except ConfigRefused:
+        return True
+
+
+def _ask_setup(harnesses: list[str]) -> bool:
+    reply = input(f"Set up Tycho in this repo ({', '.join(harnesses)})? [Y/n] ").strip().lower()
+    return reply in ("", "y", "yes")
+
+
+def offer_first_run(repo: Path, confirm=None) -> list[str]:
+    """First-run nudge (TYCHO-49): a supported agent is here but Tycho isn't wired.
+
+    Offer to set it up — interactively when there's a terminal (`Set up Tycho here? [Y/n]` →
+    runs init), or by printing the one-liner when there isn't. Fires **once per repo** (a
+    declined offer is never re-nagged) and **never writes config without consent** (TYCHO-6):
+    the "already offered" marker lives outside the repo, and a decline touches nothing.
+    Returns status lines for the caller to print; `[]` when there's nothing to offer.
+    """
+    if state.already_offered(repo):
+        return []
+    detected = detect(repo)
+    if not detected or state.read_install(repo) or any(_wired_here(repo, n) for n in detected):
+        return []  # nothing here, or already set up
+    state.mark_offered(repo)  # offered — regardless of the answer, don't ask again
+    ask = confirm or _ask_setup
+    interactive = confirm is not None or sys.stdin.isatty()  # a real TTY, or a test's confirm
+    if interactive and ask(detected):
+        return ["Tycho: setting up here…", *init(repo, only=None, assume_yes=True)]
+    return [
+        f"Tycho isn't set up in this repo yet — a supported agent ({', '.join(detected)}) is here.",
+        "  Run `tycho init` to wire it up (offered once; it won't ask again).",
+    ]
+
+
+def uninstall(repo: Path, only: str | None = None, purge: bool = False) -> list[str]:
+    """Remove Tycho-owned hook entries; return status lines.
+
+    Only ours come out — unrelated hooks, unrelated keys, and user-owned groups are
+    left as they were. With ``only`` set (a harness name), touch just that harness.
+    With ``purge`` set, also delete the repo-local `.tycho/` state and `.tycho.toml`
+    config — an explicit opt-in, never the default, since it drops the catch trail.
+    """
+    removers = {
+        "claude": _uninstall_claude,
+        "cursor": _uninstall_cursor,
+        "codex": _uninstall_codex,
+        "opencode": _uninstall_opencode,
+    }
+    lines = []
+    for name, fn in removers.items():
+        if only and name != only:
+            continue
+        try:
+            lines.append(fn(repo))
+            # Forget what we recorded, or `doctor` would keep diagnosing a ghost. Only
+            # after the config write succeeded — state must never claim less than truth.
+            state.drop_install(repo, name)
+        except ConfigRefused as exc:
+            # Same rule as install: a config we can't parse is one we can't safely
+            # rewrite. Removing our hook is not worth risking the rest of the file.
+            lines.append(f"{name}{REFUSED}{exc}")
+    if purge:
+        lines += _purge_repo_local(repo)
+    return lines
+
+
+def _purge_repo_local(repo: Path) -> list[str]:
+    """Delete the two repo-local artifacts Tycho owns whole: the `.tycho/` state dir
+    (catch tally + evidence) and the `.tycho.toml` config. Idempotent — a missing target
+    is a no-op line, not an error. Stays repo-local: the machine-wide state under
+    `~/.local/share/tycho` (the all-time tally, shared across repos) is never touched.
+    """
+    lines = []
+    for path in (state.dir_for(repo), config_mod.path(repo)):
+        try:
+            if path.is_dir():
+                shutil.rmtree(path)
+                lines.append(f"removed {path.name}/")
+            elif path.exists():
+                path.unlink()
+                lines.append(f"removed {path.name}")
+            else:
+                lines.append(f"{path.name}: nothing to remove")
+        except OSError as exc:
+            # A delete we couldn't finish is an unfinished uninstall — mark it REFUSED so
+            # the CLI exits non-zero, same contract as a config we couldn't rewrite.
+            lines.append(f"{path.name}{REFUSED}{exc.strerror or exc}")
+    return lines
+
+
+def _current_text(path: Path) -> str | None:
+    """What's on disk, or None if there's no file. Unreadable is refused, not ignored."""
+    try:
+        return path.read_text(encoding="utf-8")
+    except FileNotFoundError:
+        return None
+    except OSError as exc:
+        raise ConfigRefused(f"cannot read {path} ({exc.strerror}) — fix the permissions and re-run") from exc
+
+
+def _load(path: Path) -> dict:
+    """Existing config as a dict. Missing or empty is {}; anything else we can't parse is refused.
+
+    Refusing matters more than it looks: treating malformed JSON as `{}` and writing
+    that back is how a verifier eats a developer's whole config. A hand-edit with a
+    trailing comma is a file to leave alone, not a file to replace.
+    """
+    text = _current_text(path)
+    if text is None or not text.strip():
+        return {}
+    try:
+        data = json.loads(text)
+    except json.JSONDecodeError as exc:
+        raise ConfigRefused(
+            f"{path} is not valid JSON (line {exc.lineno}: {exc.msg}) — fix or move it, then re-run"
+        ) from exc
+    if not isinstance(data, dict):
+        raise ConfigRefused(f"{path} holds {type(data).__name__}, not a JSON object — leaving it alone")
+    return data
+
+
+def _write_text(path: Path, text: str, backup: bool = True) -> bool:
+    """Write `text` to `path` atomically; return False if it was already correct.
+
+    Resolves symlinks first: a settings file symlinked into a dotfiles repo must stay a
+    symlink, so replace what it points at rather than the link itself. Writes to a
+    sibling temp file and renames — rename is atomic, so a run killed mid-write leaves
+    the original whole rather than a truncated husk. ``backup=False`` skips the `.bak` for
+    files that are wholly ours and regenerable (a `/tycho` command), where a backup is
+    just clutter — the settings file, which holds *user* data, always keeps one.
+    """
+    target = Path(os.path.realpath(path))
+    current = _current_text(target)
+    if current == text:
+        return False  # already correct: no write, no backup, no mtime churn
+    if current is not None and not os.access(target, os.W_OK):
+        # A rename lands regardless of the *file's* mode, so without this the user's
+        # deliberate chmod -w would be silently undone. (The dir's mode, and every
+        # other way the filesystem can say no, is caught below.)
+        raise ConfigRefused(f"{target} is read-only — chmod +w (or move it), then re-run")
+    tmp = target.with_name(target.name + _TMP_SUFFIX)
+    try:
+        if current is not None and backup:
+            # .bak holds the state immediately before this change, not a frozen
+            # pristine original: it's the file you'd restore to undo what we just did.
+            # Nothing is lost by overwriting it — we only ever get here for content
+            # we're about to change, we refuse anything unparseable long before this,
+            # and the user's own keys survive into every later copy regardless.
+            shutil.copy2(target, target.with_name(target.name + _BACKUP_SUFFIX))
+        target.parent.mkdir(parents=True, exist_ok=True)
+        tmp.write_text(text, encoding="utf-8")
+        if current is not None:
+            shutil.copymode(target, tmp)  # the user's permissions, not our umask's
+        tmp.replace(target)
+    except OSError as exc:
+        # Anything the filesystem refuses — an unwritable parent dir, a full disk, a
+        # quota — is a refusal like any other, not a traceback. The original is still
+        # whole either way: nothing has replaced it yet.
+        tmp.unlink(missing_ok=True)
+        raise ConfigRefused(f"cannot write {target} ({exc.strerror}) — fix that, then re-run") from exc
+    return True
+
+
+def _write(path: Path, data: dict) -> bool:
+    return _write_text(path, json.dumps(data, indent=2) + "\n")
+
+
+def _status(label: str, what: str, path: Path, command: str, existed: bool, changed: bool) -> str:
+    if not changed:
+        return f"{label}: {what} already current → {path}"
+    verb = "updated" if existed else "installed"
+    return f"{label}: {verb} {what} → {path}  ({command})"
+
+
+def _install_claude(repo: Path) -> str:
+    """Claude gets two things in the same file: the Stop hook, and (if free) the status bar.
+
+    Both land in **one** write, which is not an optimisation. `.bak` must hold the state
+    from before Tycho touched anything, so a second write would back up our own first one
+    and destroy the copy the user would restore.
+    """
+    # .claude/settings.json → hooks.Stop is a list of matcher-groups, each with a `hooks` list.
+    path = config_path(repo, "claude")
+    data = _load(path)
+    command = hook_command()
+    hooks = dict(data.get("hooks") or {}) if isinstance(data.get("hooks"), dict) else {}
+    groups, existed = _strip_claude_tycho(hooks.get("Stop") or [])
+    groups.append({"hooks": [{"type": "command", "command": command}]})
+    hooks["Stop"] = groups
+    # SessionStart: surface a newer-version notice to the user at agent bootup (TYCHO-53).
+    ss_command = _command_for("session-start")
+    ss_groups, ss_existed = _strip_claude_tycho(hooks.get("SessionStart") or [])
+    ss_groups.append({"hooks": [{"type": "command", "command": ss_command}]})
+    hooks["SessionStart"] = ss_groups
+    # UserPromptSubmit: mark a run in flight the moment a prompt is sent, so the badge turns
+    # frost-blue "verifying" for the whole turn rather than only flickering at the Stop that
+    # ends it (TYCHO-94). The Stop hook clears the pending beat to the verdict.
+    ups_command = _command_for("prompt-submit")
+    ups_groups, ups_existed = _strip_claude_tycho(hooks.get("UserPromptSubmit") or [])
+    ups_groups.append({"hooks": [{"type": "command", "command": ups_command}]})
+    hooks["UserPromptSubmit"] = ups_groups
+    merged, statusline = _with_statusline(repo, {**data, "hooks": hooks}, path)
+    changed = _write(path, merged)
+    state.write_install(repo, "claude", command)
+    hook_line = _status("claude", "Stop hook", path, command, existed, changed)
+    ss_line = _status("claude", "SessionStart hook", path, ss_command, ss_existed, changed)
+    ups_line = _status("claude", "UserPromptSubmit hook", path, ups_command, ups_existed, changed)
+    slash = _install_slash_commands(repo)
+    return "\n".join(filter(None, (hook_line, ss_line, ups_line, statusline, slash)))
+
+
+# One flat file per subcommand (`.claude/commands/tycho-status.md` → `/tycho-status`) so
+# each shows up with its own description in Claude Code's `/` autocomplete (TYCHO-48).
+# `hide`/`show` are the discoverable face of the `tycho status --off/--on` toggle (TYCHO-47).
+_SLASH_SUBCOMMANDS = {
+    "status": ("Is Tycho live here, and its last verdict", "status"),
+    "doctor": ("Full diagnostics: is Tycho installed, current, and firing?", "doctor"),
+    "verify": ("Verify the latest session and render a verdict", "verify $ARGUMENTS"),
+    "help": ("What Tycho is, whether it's live here, and every command", "help"),
+    "count": ("How many problems Tycho has caught here, and all-time", "count"),
+    "hide": ("Hide the Tycho status indicator (the hook keeps verifying)", "status --off"),
+    "show": ("Show the Tycho status indicator again", "status --on"),
+    "relay": ("Is the verdict relay on? (agent sees its verdict, works till VERIFIED)", "relay"),
+    "relay-on": ("Turn ON the verdict relay — agent sees non-VERIFIED verdicts, works till VERIFIED (bounded)", "relay --on"),
+    "relay-off": ("Turn OFF the verdict relay — verdicts stay human-only (the default)", "relay --off"),
+}
+
+
+def _commands_dir(repo: Path) -> Path:
+    return repo / ".claude" / "commands"
+
+
+def _q(s: str) -> str:
+    """Quote a YAML frontmatter value. A bare colon-space in a description ("Full
+    diagnostics: ...") reads as a nested mapping and breaks Claude Code's parse, which then
+    falls back to showing the marker — so always quote, escaping `\\` and `"`."""
+    return '"' + s.replace("\\", "\\\\").replace('"', '\\"') + '"'
+
+
+def _slash_body(description: str, cli_args: str, argument_hint: str = "") -> str:
+    """A prompt-style command file backed by the real CLI (TYCHO-48).
+
+    Prompt-style on purpose: relies only on the stable `.claude/commands/*.md` convention
+    and `$ARGUMENTS`, not on `!`-exec / `allowed-tools` glob matching against a quoted
+    interpreter path (the fiddly, version-sensitive part). Runs the exact command the
+    terminal runs, so there's nothing extra to keep in sync.
+    """
+    # The YAML frontmatter MUST be the first thing in the file — Claude Code only parses it
+    # when `---` is line 1, so the marker goes in the body, not above it (a marker on top
+    # left the frontmatter unparsed and showed the comment itself as the description).
+    hint = f"argument-hint: {_q(argument_hint)}\n" if argument_hint else ""
+    return (
+        "---\n"
+        f"description: {_q(description)}\n{hint}"
+        "---\n\n"
+        f"{_SLASH_MARKER}\n\n"
+        "Run this exact command with the Bash tool and show its output verbatim - "
+        "nothing else, no commentary:\n\n"
+        f"`{_command_for(cli_args)}`\n\n"
+        "This is Tycho's own CLI (it also runs standalone in your terminal); it never edits code.\n"
+    )
+
+
+# The four scope commands (TYCHO-55). Each is its own `/tycho-scope-*` so it autocompletes
+# with its own description and argument-hint. set/add/remove take path globs, which MUST be
+# passed single-quoted so the shell doesn't expand them before Tycho stores them — the body
+# says so explicitly. Value: (description, cli action, argument-hint).
+_SCOPE_SLASH = {
+    "scope-list": ("List the files/dirs the agent may edit (the scope_drift allowlist)", "list", ""),
+    "scope-set": ("Replace the scope_drift allowlist with these path globs", "set", "<glob>… e.g. 'src/**' 'tests/**'"),
+    "scope-add": ("Add path globs to the scope_drift allowlist", "add", "<glob>… e.g. 'src/**' 'tests/**'"),
+    "scope-remove": ("Remove path globs from the scope_drift allowlist", "remove", "<glob>… e.g. 'tests/**'"),
+}
+
+
+def _scope_slash_body(description: str, action: str, argument_hint: str) -> str:
+    """A `/tycho-scope-*` command file. `list` takes no args and reuses the generic body;
+    set/add/remove instruct the agent to single-quote each glob so the shell keeps it
+    literal (an un-quoted `src/**` would expand to files before Tycho ever sees it)."""
+    if action == "list":
+        return _slash_body(description, "scope list")
+    cmd = _command_for(f"scope {action}")
+    return (
+        "---\n"
+        f"description: {_q(description)}\n"
+        f"argument-hint: {_q(argument_hint)}\n"
+        "---\n\n"
+        f"{_SLASH_MARKER}\n\n"
+        "Update this repo's Tycho edit-scope, then show the command's output verbatim. Run it with "
+        "the Bash tool, passing **each glob as a separate single-quoted argument** so the shell keeps "
+        "it literal (an unquoted `src/**` expands to files before Tycho stores it):\n\n"
+        f"`{cmd} '<glob>' '<glob>' …`\n\n"
+        "The globs to use: $ARGUMENTS\n\n"
+        "This edits `.tycho.toml` only — it never touches your code.\n"
+    )
+
+
+def _slash_files(repo: Path) -> dict[Path, str]:
+    """Path → body for every `/tycho` command file we install (flat `tycho-<sub>.md`)."""
+    d = _commands_dir(repo)
+    files = {d / "tycho.md": _slash_body(
+        "Run Tycho - verify what the agent claimed", "$ARGUMENTS",
+        argument_hint="<status|doctor|verify|scope|help>",
+    )}
+    for name, (desc, args) in _SLASH_SUBCOMMANDS.items():
+        files[d / f"tycho-{name}.md"] = _slash_body(desc, args)
+    for name, (desc, action, hint) in _SCOPE_SLASH.items():
+        files[d / f"tycho-{name}.md"] = _scope_slash_body(desc, action, hint)
+    return files
+
+
+def _install_slash_commands(repo: Path) -> str | None:
+    """Write the `/tycho` command set; skip any file the user wrote themselves.
+
+    Same non-clobber rule as every other target: a command file without our marker is the
+    user's, and stays put.
+    """
+    target = _slash_files(repo)
+    # Remove any of *our* files from an earlier layout (the old `tycho/` namespace) that
+    # aren't in the current set, plus any `.bak` clutter a previous write left behind — a
+    # command file is wholly ours, so it never needed a backup.
+    for path in [*_tycho_command_files(repo), *_commands_dir(repo).glob("tycho*.tycho.bak")]:
+        if path not in target and (path.suffix == ".bak" or _SLASH_MARKER in (_current_text(path) or "")):
+            path.unlink()
+    try:
+        (_commands_dir(repo) / "tycho").rmdir()  # tidy the old namespace dir if now empty
+    except OSError:
+        pass
+    installed, skipped = [], []
+    for path, body in target.items():
+        existing = _current_text(path)
+        if existing is not None and _SLASH_MARKER not in existing:
+            skipped.append(path.name)
+        elif _write_text(path, body, backup=False):
+            installed.append(path)
+    lines = []
+    if installed:
+        lines.append(f"claude: installed /tycho slash commands ({len(installed)}) → {_commands_dir(repo)}")
+    if skipped:
+        lines.append(f"claude: left your own command file(s) alone: {', '.join(sorted(set(skipped)))}")
+    return "\n".join(lines) or None
+
+
+def _user_statusline_command(repo: Path) -> str | None:
+    """The command in the *user-level* Claude settings' statusLine, if any (read-only).
+
+    We never write user-level config — but reading it tells us whether a repo-level
+    statusLine of ours would *shadow* an existing one (a third-party badge lives here), and
+    the repo slot wins. Knowing that lets Tycho compose with it instead of hiding it. Same
+    read-only posture as harness detection: `$HOME` is a signal, never a write target.
+    """
+    try:
+        data = json.loads((harness_mod.home("claude") / "settings.json").read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return None
+    sl = data.get("statusLine") if isinstance(data, dict) else None
+    cmd = sl.get("command") if isinstance(sl, dict) else None
+    return cmd if isinstance(cmd, str) and not _is_tycho_status(cmd) else None
+
+
+def _with_statusline(repo: Path, data: dict, path: Path) -> tuple[dict, str]:
+    """Claim Claude Code's status bar, *composing* with any existing one (TYCHO-39/47).
+
+    `statusLine` holds exactly one command, and a repo-level line wins over the user-level
+    one — so Tycho could silently hide a working feature (a third-party badge, a shell prompt).
+    It doesn't: instead of replacing, it becomes the slot and *runs the other command too*.
+    - A foreign line in **this repo's** file is recorded (origin "repo") and restored on
+      uninstall — we own the write, so we owe the restore.
+    - A **user-level** line is recorded (origin "user") and left untouched; it resurfaces on
+      its own once ours is removed. `tycho status` runs it and prepends its output.
+
+    Shape verified against Claude Code 2.1.210: {"type": "command", "command": str}, plus
+    optional padding/refreshInterval which are the user's to set — hence the merge.
+    """
+    current = data.get("statusLine")
+    command = status_command()
+    ours = isinstance(current, dict) and _is_tycho_status(current.get("command"))
+    foreign = current.get("command") if (isinstance(current, dict) and not ours) else None
+
+    if isinstance(foreign, str):
+        state.write_statusline_wrap(repo, foreign, origin="repo")
+    elif (user_cmd := _user_statusline_command(repo)) is not None:
+        state.write_statusline_wrap(repo, user_cmd, origin="user")
+    else:
+        state.clear_statusline_wrap(repo)
+
+    base = current if (ours and isinstance(current, dict)) else {}  # keep our own extra keys only
+    merged = {**base, "type": "command", "command": command}
+    # Poll on top of the event-driven render (TYCHO-59). Claude Code renders the badge at the
+    # Stop event, which fires while our hook is still verifying (entry beat = "pending"), so
+    # without polling the badge sits on yellow until the *next* prompt instead of settling on
+    # the verdict. A short interval re-renders it a beat later, once the verdict is written.
+    # Left to the user if they've set their own (see the `base` merge above).
+    merged.setdefault("refreshInterval", _STATUS_REFRESH_MS)
+    if merged == current and state.read_statusline_wrap(repo) is None:
+        return data, ""  # already ours, nothing to compose — the Stop-hook line speaks for it
+    composing = " (composing with your existing status line)" if state.read_statusline_wrap(repo) else ""
+    return {**data, "statusLine": merged}, f"claude: installed statusLine → {path}{composing}"
+
+
+def _strip_claude_tycho(groups: list) -> tuple[list, bool]:
+    """Drop any existing tycho hook entries (and now-empty groups); flag if any removed."""
+    out, existed = [], False
+    for group in groups:
+        entries = (group.get("hooks") or []) if isinstance(group, dict) else []
+        kept = [h for h in entries if not (isinstance(h, dict) and _is_tycho_owned(h.get("command")))]
+        existed = existed or len(kept) != len(entries)
+        if not isinstance(group, dict):
+            out.append(group)
+        elif kept or not entries:
+            out.append({**group, "hooks": kept})
+    return out, existed
+
+
+def _install_cursor(repo: Path) -> str:
+    # .cursor/hooks.json → hooks.stop is a flat list of {command, ...}; needs `version`.
+    path = config_path(repo, "cursor")
+    data = _load(path)
+    hooks = dict(data.get("hooks") or {}) if isinstance(data.get("hooks"), dict) else {}
+    command = hook_command()
+    stop = list(hooks.get("stop") or [])
+    kept = [h for h in stop if not (isinstance(h, dict) and _is_tycho_hook(h.get("command")))]
+    existed = len(kept) != len(stop)
+    kept.append({"command": command})
+    hooks["stop"] = kept
+    changed = _write(path, {**data, "version": data.get("version", 1), "hooks": hooks})
+    state.write_install(repo, "cursor", command)
+    return _status("cursor", "stop hook", path, command, existed, changed)
+
+
+def _install_codex(repo: Path) -> str:
+    """Codex shares Claude's hooks shape: `hooks.<Event>` is a list of matcher-groups. Stop
+    drives the verdict; SessionStart surfaces the bootup update notice via `systemMessage`
+    (Codex's output wire schema clones Claude's — docs/harness-support.md, TYCHO-72). Both go
+    in one write so the .bak doesn't churn (same reason `_install_claude` batches its keys).
+    """
+    path = config_path(repo, "codex")
+    data = _load(path)
+    hooks = dict(data.get("hooks") or {}) if isinstance(data.get("hooks"), dict) else {}
+    command = hook_command()
+    groups, existed = _strip_claude_tycho(hooks.get("Stop") or [])
+    groups.append({"hooks": [{"type": "command", "command": command}]})
+    hooks["Stop"] = groups
+    ss_command = _command_for("session-start")
+    ss_groups, ss_existed = _strip_claude_tycho(hooks.get("SessionStart") or [])
+    ss_groups.append({"hooks": [{"type": "command", "command": ss_command}]})
+    hooks["SessionStart"] = ss_groups
+    changed = _write(path, {**data, "hooks": hooks})
+    state.write_install(repo, "codex", command)
+    hook_line = _status("codex", "Stop hook", path, command, existed, changed)
+    ss_line = _status("codex", "SessionStart hook", path, ss_command, ss_existed, changed)
+    return "\n".join(filter(None, (hook_line, ss_line)))
+
+
+def _install_opencode(repo: Path) -> str:
+    # OpenCode has no Stop hook; a project plugin drives two Tycho entrypoints off the
+    # plugin event bus, each handed the session id on stdin. Both toast their result via
+    # client.tui.showToast — a genuinely user-facing sink (TYCHO-72):
+    #   - session.idle  → `tycho hook`          (the Stop verdict, after every turn)
+    #   - session.created → `tycho session-start` (the bootup update-notice, once per session)
+    # Tycho rebuilds the transcript from opencode.db — no `opencode export` (which truncates
+    # at 128 KB over a pipe).
+    path = config_path(repo, "opencode")
+    command = hook_argv(hook_command())
+    notice = hook_argv(_command_for("session-start"))
+    source = f'''{_PLUGIN_MARKER} OpenCode loads project plugins at startup.
+const command = {json.dumps(command)}
+const noticeCommand = {json.dumps(notice)}
+
+export const TychoPlugin = async ({{ client, directory }}) => {{
+  const run = async (argv, sessionID) => {{
+    const proc = Bun.spawn([...argv], {{
+      cwd: directory, stdin: "pipe", stdout: "pipe", stderr: "ignore",
+    }})
+    proc.stdin.write(JSON.stringify({{ harness: "opencode", sessionID, directory }}))
+    proc.stdin.end()
+    const text = (await new Response(proc.stdout).text()).trim()
+    await proc.exited
+    if (!text) return
+    try {{
+      const message = JSON.parse(text).message
+      if (message) await client.tui.showToast({{
+        body: {{ title: "Tycho", message, variant: "info" }},
+      }})
+    }} catch {{}}
+  }}
+  return {{
+    event: async ({{ event }}) => {{
+      if (event.type === "session.idle") {{
+        const sessionID = event.properties?.sessionID
+        if (sessionID) await run(command, sessionID)
+      }} else if (event.type === "session.created") {{
+        await run(noticeCommand, event.properties?.sessionID)
+      }}
+    }},
+  }}
+}}
+'''
+    # The whole file is ours, but a hand-written tycho.js is not — refuse rather than
+    # overwrite someone else's plugin that happens to share our name.
+    existed = path.exists()
+    if existed and _PLUGIN_MARKER not in (_current_text(path) or ""):
+        raise ConfigRefused(f"{path} wasn't generated by tycho init — move it aside, then re-run")
+    changed = _write_text(path, source)
+    state.write_install(repo, "opencode", shlex.join(command))
+    return _status("opencode", "session.idle + session.created plugin", path, shlex.join(command), existed, changed)
+
+
+# --- uninstall ---------------------------------------------------------------
+#
+# We never delete a harness's config file: it may hold settings we didn't write
+# (a `model`, unrelated hooks). We remove our entries, then drop a container only
+# when it's empty *and* we were the ones who would have created it. The OpenCode
+# plugin is the one exception — that whole file is ours, so it goes.
+
+
+def _prune(data: dict, hooks: dict, key: str, kept: list) -> dict:
+    """Put `kept` back under `key`, dropping containers we emptied."""
+    if kept:
+        hooks[key] = kept
+    else:
+        hooks.pop(key, None)  # init created this list; don't leave an empty one behind
+    merged = {**data, "hooks": hooks}
+    if not hooks:
+        merged.pop("hooks", None)
+    return merged
+
+
+def _uninstall_claude(repo: Path) -> str:
+    """Take back the Stop hook and our statusLine — only ours, and in one write.
+
+    Claude's file holds several Tycho-owned things (Stop, SessionStart, UserPromptSubmit,
+    statusLine); removing them in separate writes would churn the backup for the same reason
+    install batches them. Codex now batches its two keys the same way (`_uninstall_codex`).
+    """
+    path = config_path(repo, "claude")
+    if not path.exists():
+        return "claude: nothing to remove (no config)"
+    data = _load(path)
+    hooks = dict(data.get("hooks") or {}) if isinstance(data.get("hooks"), dict) else {}
+    groups, had_hook = _strip_claude_tycho(hooks.get("Stop") or [])
+    ss_groups, had_ss = _strip_claude_tycho(hooks.get("SessionStart") or [])
+    ups_groups, had_ups = _strip_claude_tycho(hooks.get("UserPromptSubmit") or [])
+    current = data.get("statusLine")
+    had_statusline = isinstance(current, dict) and _is_tycho_status(current.get("command"))
+    slash = _uninstall_slash_commands(repo)
+    wrap = state.read_statusline_wrap(repo)
+    state.clear_statusline_wrap(repo)  # forget the compose target either way
+    if not had_hook and not had_ss and not had_ups and not had_statusline:
+        return slash or "claude: nothing to remove"
+    _prune(data, hooks, "Stop", groups)  # mutates `hooks` in place…
+    _prune(data, hooks, "SessionStart", ss_groups)  # …then the second key…
+    merged = _prune(data, hooks, "UserPromptSubmit", ups_groups)  # …then the third
+    restored = False
+    if had_statusline:
+        merged = {k: v for k, v in merged.items() if k != "statusLine"}
+        # A foreign repo-level line we replaced is ours to put back; a user-level one
+        # (origin "user", or no record) resurfaces on its own once ours is gone.
+        if isinstance(wrap, dict) and wrap.get("origin") == "repo" and isinstance(wrap.get("command"), str):
+            merged = {**merged, "statusLine": {"type": "command", "command": wrap["command"]}}
+            restored = True
+    _write(path, merged)
+    lines = []
+    if had_hook:
+        lines.append(f"claude: removed Stop hook → {path}")
+    if had_ss:
+        lines.append(f"claude: removed SessionStart hook → {path}")
+    if had_ups:
+        lines.append(f"claude: removed UserPromptSubmit hook → {path}")
+    if had_statusline:
+        lines.append(f"claude: restored your statusLine → {path}" if restored
+                     else f"claude: removed statusLine → {path}")
+    if slash:
+        lines.append(slash)
+    return "\n".join(lines)
+
+
+def _tycho_command_files(repo: Path) -> list[Path]:
+    """Every command file that could be ours — the flat `tycho.md`/`tycho-*.md`, plus the
+    old namespaced `tycho/*.md` from before the rename, so uninstall cleans both layouts."""
+    d = _commands_dir(repo)
+    return [*d.glob("tycho.md"), *d.glob("tycho-*.md"), *(d / "tycho").glob("*.md")]
+
+
+def _uninstall_slash_commands(repo: Path) -> str | None:
+    """Remove every `/tycho` command we generated; leave hand-written files alone."""
+    removed = False
+    for path in _tycho_command_files(repo):
+        text = _current_text(path)
+        if text is not None and _SLASH_MARKER in text:
+            path.unlink()
+            removed = True
+    for tidy in (_commands_dir(repo) / "tycho", _commands_dir(repo)):
+        try:
+            tidy.rmdir()  # only if now empty — never take a dir holding someone's file
+        except OSError:
+            pass
+    return f"claude: removed /tycho slash commands → {_commands_dir(repo)}" if removed else None
+
+
+def _uninstall_codex(repo: Path) -> str:
+    """Remove the Stop and SessionStart hooks (TYCHO-72) — only ours, in one write."""
+    path = repo / ".codex" / "hooks.json"
+    if not path.exists():
+        return "codex: nothing to remove (no config)"
+    data = _load(path)
+    hooks = dict(data.get("hooks") or {}) if isinstance(data.get("hooks"), dict) else {}
+    groups, had_hook = _strip_claude_tycho(hooks.get("Stop") or [])
+    ss_groups, had_ss = _strip_claude_tycho(hooks.get("SessionStart") or [])
+    if not had_hook and not had_ss:
+        return "codex: nothing to remove"
+    _prune(data, hooks, "Stop", groups)  # mutates `hooks` in place…
+    merged = _prune(data, hooks, "SessionStart", ss_groups)  # …then the second key
+    _write(path, merged)
+    lines = []
+    if had_hook:
+        lines.append(f"codex: removed Stop hook → {path}")
+    if had_ss:
+        lines.append(f"codex: removed SessionStart hook → {path}")
+    return "\n".join(lines)
+
+
+def _uninstall_cursor(repo: Path) -> str:
+    # .cursor/hooks.json → hooks.stop is a flat list of {command, ...}.
+    path = repo / ".cursor" / "hooks.json"
+    if not path.exists():
+        return "cursor: nothing to remove (no config)"
+    data = _load(path)
+    hooks = dict(data.get("hooks") or {}) if isinstance(data.get("hooks"), dict) else {}
+    stop = list(hooks.get("stop") or [])
+    kept = [h for h in stop if not (isinstance(h, dict) and _is_tycho_hook(h.get("command")))]
+    if len(kept) == len(stop):
+        return "cursor: nothing to remove"
+    _write(path, _prune(data, hooks, "stop", kept))
+    return f"cursor: removed stop hook → {path}"
+
+
+def _uninstall_opencode(repo: Path) -> str:
+    # The whole plugin file is ours — but only if we generated it. A hand-written
+    # tycho.js belongs to the user and is left alone.
+    path = repo / ".opencode" / "plugins" / "tycho.js"
+    if not path.exists():
+        return "opencode: nothing to remove"
+    try:
+        generated = _PLUGIN_MARKER in path.read_text(encoding="utf-8")
+    except OSError:
+        generated = False
+    if not generated:
+        return f"opencode: left {path} alone (not generated by tycho init)"
+    path.unlink()
+    try:
+        path.parent.rmdir()  # tidy the plugins/ dir we made — only if now empty
+    except OSError:
+        pass  # user has other plugins, or the dir predates us: leave it
+    return f"opencode: removed plugin → {path}"