tycho-cli 0.0.1__py3-none-any.whl

tycho/state.py

@@ -0,0 +1,469 @@
+"""Tycho's own repo-local state: what `init` wired up, and proof the hook still fires.
+
+Two files under ``<repo>/.tycho/``, both entirely ours (no user content, ever):
+
+- ``install.json``  — written by `tycho init`: schema version + what we wired, per harness.
+- ``last-run.json`` — rewritten by the Stop hook on *every* invocation: the heartbeat.
+
+Separate files on purpose: init and the hook write on different schedules from
+different processes, so one shared file would mean read-modify-write races and a lost
+update — exactly the kind of silent corruption TYCHO-6 just finished stamping out.
+
+**Nothing here may raise into a caller.** The hook must never break the agent's Stop
+(see hook.py), so a heartbeat we can't write is simply not written: a missing beat makes
+`tycho doctor` say "unknown", which is honest, whereas an exception here would break the
+one thing Tycho promises never to touch.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import time
+from pathlib import Path
+
+# Bump when the shape of what init installs changes such that an already-installed
+# entry no longer satisfies it. `tycho doctor` compares this against the stamp in
+# install.json and reports HOOK OUTDATED when they diverge; `tycho init` re-stamps.
+SCHEMA = 1
+
+_DIR = ".tycho"
+_INSTALL = "install.json"
+_LAST_RUN = "last-run.json"
+
+# `.tycho.toml` is config.py's file, but it marks the same root as `.tycho/` and can exist
+# without it (configured, never inited), so root_for() looks for either. Spelled out here
+# rather than imported to keep state.py free of a config import it otherwise has no use for.
+_CONFIG_MARKER = ".tycho.toml"
+_GIT = ".git"
+
+
+def root_for(repo: Path) -> Path:
+    """Where this repo's Tycho state lives: `repo` itself, or the nearest ancestor holding it.
+
+    Every entry point hands us a cwd, and a cwd follows the user into subdirectories. Without
+    the walk, `<cwd>/.tycho` misses from anywhere but the repo root, and every reader here
+    reports that as "not installed" — the badge goes blank and `doctor` says unknown, both of
+    which read as "Tycho isn't here" rather than "you're one directory down" (TYCHO-79).
+
+    Stops at the git root: our state belongs to *this* repo, and an unrelated parent's `.tycho/`
+    is not ours to adopt. No marker anywhere means `repo` — so `init` still creates state where
+    it was run, and a first write lands exactly where it does today.
+    """
+    for d in (repo, *repo.parents):
+        if (d / _DIR).is_dir() or (d / _CONFIG_MARKER).is_file():
+            return d
+        if (d / _GIT).exists():  # repo root reached (a dir, or a worktree/submodule's file)
+            break
+    return repo
+
+
+def dir_for(repo: Path) -> Path:
+    return root_for(repo) / _DIR
+
+
+def _read_json(path: Path) -> dict | None:
+    """Our own state, so unreadable or corrupt means "unknown" — never an error."""
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return None
+    return data if isinstance(data, dict) else None
+
+
+def _write_json(path: Path, data: dict) -> None:
+    """Atomic, like every other write in this package: temp sibling, then rename."""
+    path.parent.mkdir(parents=True, exist_ok=True)
+    tmp = path.with_name(path.name + ".tmp")
+    tmp.write_text(json.dumps(data, indent=2) + "\n", encoding="utf-8")
+    tmp.replace(path)
+
+
+def write_install(repo: Path, harness: str, command: str) -> None:
+    """Record that we wired `harness` to `command`. Merges — other harnesses survive."""
+    installed = dict(read_install(repo))
+    installed[harness] = {"command": command, "at": time.time()}
+    _write_json(dir_for(repo) / _INSTALL, {"schema": SCHEMA, "installed": installed})
+
+
+def drop_install(repo: Path, harness: str) -> None:
+    """Forget one harness; drop the file (and dir) once there's nothing left to remember."""
+    path = dir_for(repo) / _INSTALL
+    installed = {k: v for k, v in read_install(repo).items() if k != harness}
+    if installed:
+        _write_json(path, {"schema": SCHEMA, "installed": installed})
+        return
+    path.unlink(missing_ok=True)
+    (dir_for(repo) / _LAST_RUN).unlink(missing_ok=True)  # a heartbeat for nothing
+    try:
+        dir_for(repo).rmdir()  # only if empty — never take a dir holding someone's file
+    except OSError:
+        pass
+
+
+def read_install(repo: Path) -> dict:
+    """{harness: {"command": str, "at": float}} for what we believe we installed."""
+    data = _read_json(dir_for(repo) / _INSTALL) or {}
+    installed = data.get("installed")
+    return installed if isinstance(installed, dict) else {}
+
+
+def installed_schema(repo: Path) -> int | None:
+    """The schema stamp on disk, or None if we've never installed here."""
+    data = _read_json(dir_for(repo) / _INSTALL)
+    return data.get("schema") if data else None
+
+
+def record_run(repo: Path, harness: str, verdict: str | None = None, pending: bool = False) -> None:
+    """The heartbeat. Called on every hook invocation — a dead hook can't call this.
+
+    Recorded even when the hook finds nothing to verify: the question this answers is
+    "did the wiring fire?", not "was there a verdict?". Swallows everything, per the
+    module docstring.
+
+    The hook calls this at least twice: once on entry with ``pending=True`` (the beat must
+    land even if everything downstream fails — and the badge shows "verifying"), then again
+    at every terminal path — with a `verdict` when there is one, or plain (no verdict, no
+    pending) when there was nothing to verify. So the three shapes are distinct and drive
+    the badge colour (TYCHO-39/59): `pending` = mid-run (yellow), `verdict` = the result
+    (green/red), neither = fired-but-nothing-to-report (grey). Re-recording is what stops a
+    stale verdict — or a stuck "verifying" — outliving the run that produced it.
+    """
+    beat: dict = {"at": time.time(), "harness": harness}
+    if verdict is not None:
+        beat["verdict"] = verdict
+    elif pending:
+        beat["pending"] = True
+    try:
+        _write_json(dir_for(repo) / _LAST_RUN, beat)
+    except OSError:
+        pass
+
+
+# --- the catch record (TYCHO-62, replaces TYCHO-50's bare tally) -------------
+#
+# What Tycho caught — with the evidence, not just a number. Two files, same fail-open rule
+# as everything here (a record we can't write is simply not written):
+#   repo   <repo>/.tycho/catches.json : {tally, catches: [entry, … newest first]}
+#   machine <user_dir>/catches.json   : {tally}   — running total across every repo
+# An entry is one adverse (FAILED/STALE) or intermediate (INDETERMINATE) run plus the
+# checks that failed or couldn't pass. The last *verdict* is not stored here — that lives
+# in last-run.json — so there is no transition dedup: every adverse/intermediate run is
+# recorded (a standing failure re-reported each turn counts each turn).
+
+_CATCHES = "catches.json"
+_LEGACY_COUNTS = "counts.json"  # pre-TYCHO-62 tally; migrated on first read/write, then dropped
+_TALLIED = ("FAILED", "STALE", "INDETERMINATE")  # verdicts that count as catches (with evidence)
+_BLIND = ("INDETERMINATE", "UNSUPPORTED")  # verdicts where Tycho had nothing to say (TYCHO-58)
+_CATCH_LIST_CAP = 100  # the repo evidence trail keeps the most recent N; the tally stays exact
+
+
+def user_dir() -> Path:
+    """Root of Tycho's *machine-level* state — outside every repo, by definition.
+
+    ``TYCHO_HOME`` wins, then ``XDG_DATA_HOME``, then the ``~/.local/share`` default:
+    the same override chain the harness roots use (``harness.home``, TYCHO-14), spelled
+    out here because this root is an XDG data dir rather than a ``~/.<name>`` dotdir.
+    """
+    override = os.environ.get("TYCHO_HOME")
+    if override:
+        return Path(override).expanduser()
+    data_home = os.environ.get("XDG_DATA_HOME") or str(Path.home() / ".local" / "share")
+    return Path(data_home) / "tycho"
+
+
+def _count_of(data: dict, key: str) -> int:
+    """A counter off disk, coerced. Anything else on that key means "no count yet"."""
+    value = data.get(key)
+    return value if isinstance(value, int) and not isinstance(value, bool) and value >= 0 else 0
+
+
+def _read_catches(path: Path) -> dict:
+    """catches.json as {tally, catches}. Falls back to a legacy counts.json tally so the
+    numbers carry across the rename, until the next write re-homes them (TYCHO-62)."""
+    data = _read_json(path)
+    if data is not None:
+        return data
+    legacy = _read_json(path.with_name(_LEGACY_COUNTS))
+    if legacy:
+        return {"tally": {v: _count_of(legacy, v) for v in _TALLIED if _count_of(legacy, v)}}
+    return {}
+
+
+def _tally_of(data: dict) -> dict:
+    tally = data.get("tally")
+    return tally if isinstance(tally, dict) else {}
+
+
+def record_catch(repo: Path, harness: str, verdict: str, results) -> None:
+    """Record one verdict: bump the running tally (repo + machine) and, when the verdict is
+    adverse/intermediate, append it to the repo's evidence trail. *Every* verdict counts
+    toward the `runs` denominator (TYCHO-58) — VERIFIED/UNSUPPORTED are runs, not catches, so
+    they add no evidence entry. Never raises: this runs inside the Stop hook, so a record we
+    can't write is simply not written.
+    """
+    entry = None
+    if verdict in _TALLIED:
+        # The evidence trail: what failed or couldn't pass. Every non-PASS check, with its
+        # status and the same evidence string the report shows.
+        trail = [
+            {"check": r.name, "status": r.status.name, "evidence": r.evidence}
+            for r in results if r.status.name != "PASS"
+        ]
+        entry = {"at": time.time(), "harness": harness, "verdict": verdict, "checks": trail}
+    _bump(dir_for(repo) / _CATCHES, verdict, entry)  # repo: tally (+ evidence if adverse)
+    _bump(user_dir() / _CATCHES, verdict, None)      # machine: running tally only
+
+
+def _bump(path: Path, verdict: str, entry: dict | None) -> None:
+    # read-modify-write with no lock — two repos catching something in the same
+    # instant can lose one machine-tally increment. It's a tally, not a ledger; add locking
+    # only if a slightly-low all-time number ever actually matters to someone.
+    try:
+        data = _read_catches(path)
+        tally = _tally_of(data)
+        tally["runs"] = _count_of(tally, "runs") + 1     # the denominator: every verdict (TYCHO-58)
+        tally[verdict] = _count_of(tally, verdict) + 1   # per-verdict, incl VERIFIED/UNSUPPORTED
+        out: dict = {"tally": tally}
+        if entry is not None:
+            prior = data.get("catches") if isinstance(data.get("catches"), list) else []
+            out["catches"] = [entry, *prior][:_CATCH_LIST_CAP]  # newest first, bounded
+        _write_json(path, out)
+        path.with_name(_LEGACY_COUNTS).unlink(missing_ok=True)  # migrated — drop the old file
+    except OSError:
+        pass
+
+
+def counts(repo: Path) -> dict:
+    """{"FAILED": n, "STALE": n, "INDETERMINATE": n} — the running tally for `repo`."""
+    tally = _tally_of(_read_catches(dir_for(repo) / _CATCHES))
+    return {v: _count_of(tally, v) for v in _TALLIED}
+
+
+def all_time_counts() -> dict:
+    """The same running tally across every repo on this machine."""
+    tally = _tally_of(_read_catches(user_dir() / _CATCHES))
+    return {v: _count_of(tally, v) for v in _TALLIED}
+
+
+def totals(repo: Path) -> dict:
+    """{"runs": n, "blind": n} for `repo` (TYCHO-58): every verdict recorded — the denominator
+    the catch counts are read against — and how many of those were blind (INDETERMINATE or
+    UNSUPPORTED, i.e. Tycho had nothing to say). `runs` is 0 for a legacy tally migrated from
+    the pre-TYCHO-58 `counts.json`, which had no denominator; it fills in as new runs land."""
+    return _totals(_read_catches(dir_for(repo) / _CATCHES))
+
+
+def all_time_totals() -> dict:
+    """The same runs/blind totals across every repo on this machine."""
+    return _totals(_read_catches(user_dir() / _CATCHES))
+
+
+def _totals(data: dict) -> dict:
+    tally = _tally_of(data)
+    return {"runs": _count_of(tally, "runs"), "blind": sum(_count_of(tally, v) for v in _BLIND)}
+
+
+def catches(repo: Path) -> list:
+    """The evidence trail for `repo` — recent adverse/intermediate runs, newest first."""
+    trail = _read_catches(dir_for(repo) / _CATCHES).get("catches")
+    return trail if isinstance(trail, list) else []
+
+
+def last_run(repo: Path) -> dict | None:
+    """The last recorded heartbeat, or None if the hook has never fired here."""
+    return _read_json(dir_for(repo) / _LAST_RUN)
+
+
+# --- update check cache (TYCHO-53) ------------------------------------------
+#
+# Machine-wide (one check serves every repo): the newest version we saw, when we last
+# looked, which version the user waved off, and how many times they've dismissed a notice.
+# Fail-open like the rest — an unreadable/​unwritable cache just means "check again".
+
+_UPDATE = "update-check.json"
+
+
+def read_update_cache() -> dict:
+    return _read_json(user_dir() / _UPDATE) or {}
+
+
+def write_update_cache(**fields) -> None:
+    """Merge `fields` into the update cache. Never raises."""
+    try:
+        data = read_update_cache()
+        data.update(fields)
+        _write_json(user_dir() / _UPDATE, data)
+    except OSError:
+        pass
+
+
+def dismiss_update(version: str) -> None:
+    """Record that the user waved off the notice for `version`, counting the dismissal."""
+    write_update_cache(dismissed_version=version, dismissed=_count_of(read_update_cache(), "dismissed") + 1)
+
+
+def update_dismissed_count() -> int:
+    """How many update notices the user has dismissed (record-keeping, TYCHO-53)."""
+    return _count_of(read_update_cache(), "dismissed")
+
+
+# --- first-run offer bookkeeping (TYCHO-49) ---------------------------------
+#
+# Machine-level, keyed by repo path: which repos we've already made the "set up Tycho here?"
+# offer in, so a declined offer is never re-nagged — and nothing is written into a repo the
+# user said no to (the marker lives outside it).
+
+_OFFERED = "offered.json"
+
+
+def already_offered(repo: Path) -> bool:
+    data = _read_json(user_dir() / _OFFERED) or {}
+    return _key(repo) in (data.get("repos") if isinstance(data.get("repos"), list) else [])
+
+
+def mark_offered(repo: Path) -> None:
+    try:
+        data = _read_json(user_dir() / _OFFERED) or {}
+        repos = data.get("repos") if isinstance(data.get("repos"), list) else []
+        key = _key(repo)
+        if key not in repos:
+            repos.append(key)
+        _write_json(user_dir() / _OFFERED, {"repos": repos})
+    except OSError:
+        pass
+
+
+def _key(repo: Path) -> str:
+    try:
+        return str(repo.resolve())
+    except OSError:
+        return str(repo)
+
+
+_STATUS_OFF = "status-off"
+
+
+def status_enabled(repo: Path) -> bool:
+    """Whether the status-bar indicator should render here. Default on; a sentinel hides it.
+
+    Hiding the badge is not uninstalling: the Stop hook keeps verifying every turn, the
+    heartbeat keeps landing — only the passive indicator goes quiet (TYCHO-47).
+    """
+    return not (dir_for(repo) / _STATUS_OFF).exists()
+
+
+def set_status_enabled(repo: Path, enabled: bool) -> None:
+    """Toggle the indicator on/off for `repo`. Never raises (same fail-open rule as above)."""
+    path = dir_for(repo) / _STATUS_OFF
+    try:
+        if enabled:
+            path.unlink(missing_ok=True)
+        else:
+            path.parent.mkdir(parents=True, exist_ok=True)
+            path.write_text("", encoding="utf-8")
+    except OSError:
+        pass
+
+
+# --- verdict relay to the agent (TYCHO-35, opt-in, default OFF) --------------
+#
+# Off by default: Tycho never feeds the agent its own context — and never spends the extra
+# generations doing so — unless the user opts in. When ON, the Stop hook hands a non-VERIFIED
+# verdict back to the Claude agent as additionalContext, which makes Claude Code continue the
+# turn so the agent can address what Tycho caught, "until VERIFIED".
+#
+# The on/off flag lives in `.tycho.toml` (`[relay] enabled`, TYCHO-114) so it's hand-editable
+# and versionable; these functions just delegate to `config`. Only the transient per-turn leash
+# (`relay-streak`) stays a runtime file here — it's ephemeral state, not user configuration.
+#
+# That auto-continuation is *bounded* by the streak counter: one user turn can only be re-entered
+# a fixed number of times (relay_max) before Tycho goes quiet and hands control back — so a
+# verdict Tycho can never satisfy cannot cycle forever (the operator's explicit requirement).
+# The streak resets on every real user prompt (UserPromptSubmit) and on a VERIFIED verdict.
+
+_RELAY_STREAK = "relay-streak"
+_RELAY_MAX_DEFAULT = 3
+
+
+def relay_max() -> int:
+    """How many times the relay may auto-continue one user turn before going quiet.
+
+    Default 3; ``TYCHO_RELAY_MAX`` overrides it for a longer or shorter leash. Floored at 0
+    (0 = never force a continuation — the relay becomes a pure, single-shot notice). A junk
+    value falls back to the default rather than raising: this is read inside the Stop hook.
+    """
+    try:
+        return max(0, int(os.environ.get("TYCHO_RELAY_MAX", _RELAY_MAX_DEFAULT)))
+    except (TypeError, ValueError):
+        return _RELAY_MAX_DEFAULT
+
+
+def relay_enabled(repo: Path) -> bool:
+    """Whether the Stop hook should feed the verdict back to the agent here. Reads
+    `.tycho.toml` ([relay] enabled), default off. Lazy import of `config` avoids an import
+    cycle (config imports state for its path resolution)."""
+    from . import config
+    return config.load(repo).relay_enabled
+
+
+def set_relay_enabled(repo: Path, enabled: bool) -> None:
+    """Toggle the verdict relay for `repo` in `.tycho.toml`. Resets the streak either way (a
+    toggle starts a fresh leash). Never raises — same fail-open rule as every write here."""
+    from . import config
+    try:
+        config.set_relay(repo, enabled)
+    except OSError:
+        pass
+    reset_relay_streak(repo)
+
+
+def relay_streak(repo: Path) -> int:
+    """How many times the current user turn has already been auto-continued by the relay.
+    Absent/unreadable/garbage counts as 0 — the honest floor for "nothing recorded yet"."""
+    try:
+        return max(0, int((dir_for(repo) / _RELAY_STREAK).read_text(encoding="utf-8").strip()))
+    except (OSError, ValueError):
+        return 0
+
+
+def bump_relay_streak(repo: Path) -> int:
+    """Record one more relay auto-continuation; return the new count. Never raises."""
+    n = relay_streak(repo) + 1
+    try:
+        path = dir_for(repo) / _RELAY_STREAK
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(str(n), encoding="utf-8")
+    except OSError:
+        pass
+    return n
+
+
+def reset_relay_streak(repo: Path) -> None:
+    """Clear the auto-continuation count — a fresh user prompt, a VERIFIED verdict, or a toggle."""
+    try:
+        (dir_for(repo) / _RELAY_STREAK).unlink(missing_ok=True)
+    except OSError:
+        pass
+
+
+_STATUSLINE = "statusline.json"
+
+
+def write_statusline_wrap(repo: Path, command: str, origin: str) -> None:
+    """Record a status command Tycho should compose with (TYCHO-47).
+
+    `origin` is "repo" (a foreign statusLine in this repo's own settings that we replaced —
+    restore it on uninstall) or "user" (a user-level line we never touched — it resurfaces
+    on its own when ours is removed). `tycho status` runs `command` and prepends its output.
+    """
+    _write_json(dir_for(repo) / _STATUSLINE, {"command": command, "origin": origin})
+
+
+def read_statusline_wrap(repo: Path) -> dict | None:
+    """The recorded compose target, or None. Our own state, so unreadable means "none"."""
+    return _read_json(dir_for(repo) / _STATUSLINE)
+
+
+def clear_statusline_wrap(repo: Path) -> None:
+    (dir_for(repo) / _STATUSLINE).unlink(missing_ok=True)

tycho/status.py

@@ -0,0 +1,171 @@
+"""`tycho status` — the one-line "am I on?" indicator, for a harness status bar (TYCHO-39).
+
+`doctor` answers the same question, but only when asked. A verifier nobody can see is a
+verifier that gets silently trusted while dead, so this is the passive form: the harness
+renders it in the terminal on every draw, and the user never has to run a command to know
+they're covered.
+
+The contract it's written against (Claude Code 2.1.210, read from the shipped binary —
+see `docs/harness-support.md`):
+
+- the command is spawned with the status payload as JSON on **stdin**, and gets ~5s
+  before it's aborted;
+- **stdout** is used only on **exit 0**, trimmed, blank lines dropped;
+- ANSI colour is supported and rendered dimmed; stderr is swallowed to a debug log.
+
+So this module reads *only* what the hook already wrote to disk (`state`), never verifies
+inline, imports no engine, and fails open to empty output — an empty line renders as
+nothing at all, which is the correct thing to show when we can't prove we're live.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+from . import state
+
+_RESET = "\033[0m"
+
+
+def _rgb(r: int, g: int, b: int) -> str:
+    return f"\033[38;2;{r};{g};{b}m"
+
+
+# Subdued, readable-on-black palette (TYCHO-94). Truecolor: the frost-blue mid-run beat is its
+# exact shade, and the verdict colours are desaturated from pure ANSI — Claude Code renders the
+# status line dark and dimmed, where full-saturation ANSI glares and is hard to read. Grey stays
+# the terminal's own bright-black: the honest "no signal", deliberately left as-is.
+_GREEN = _rgb(140, 198, 158)   # VERIFIED        — muted mint
+_RED = _rgb(224, 138, 138)     # FAILED / STALE  — muted rose (both adverse)
+_YELLOW = _rgb(216, 194, 130)  # INDETERMINATE   — muted amber (ran, couldn't conclude)
+_FROST = _rgb(172, 213, 243)   # verifying now   — frost blue #ACD5F3 (transient, mid-run)
+_GREY = "\033[90m"             # no signal       — never fired / UNSUPPORTED / nothing to verify
+
+# Five honest states for the `[TYCHO]` badge (TYCHO-47/59/94). The text never changes; the
+# colour carries the status:
+#   green  = VERIFIED            — proven good
+#   red    = FAILED / STALE      — adverse, something to look at
+#   frost  = verifying (pending) — a run is in flight this turn
+#   yellow = INDETERMINATE       — ran but couldn't conclude (attention, not alarm)
+#   grey   = no signal           — never fired, UNSUPPORTED, or a completed run with nothing to verify
+# It lands on green or red once a verdict exists; frost is only the in-flight moment, yellow is
+# inconclusive-but-noteworthy, and grey is the honest "nothing to say".
+_VERDICT_COLOUR = {"VERIFIED": _GREEN, "FAILED": _RED, "STALE": _RED, "INDETERMINATE": _YELLOW}
+
+
+def line(repo: Path) -> str:
+    """The indicator for `repo`, or "" when there's nothing honest to show."""
+    if not state.read_install(repo):
+        return ""  # not installed here — never clutter someone else's status bar
+    if os.environ.get("TYCHO_STATUS", "").strip().lower() in ("0", "off", "false", "no"):
+        return ""  # a global override, for a session where you want it quiet everywhere
+    if not state.status_enabled(repo):
+        return ""  # toggled off in this repo — the hook still runs, only the badge hides
+    beat = state.last_run(repo) or {}
+    if not isinstance(beat.get("at"), (int, float)):
+        return _paint(_GREY, "[TYCHO]")  # installed, never fired here — bootup, no signal yet
+    verdict = beat.get("verdict")
+    if verdict is None:
+        # A run with no verdict: mid-run (pending) is frost blue "verifying"; a completed run
+        # that reached nothing to verify is grey — not a false "working forever".
+        return _paint(_FROST if beat.get("pending") else _GREY, "[TYCHO]")
+    return _paint(_VERDICT_COLOUR.get(verdict, _GREY), "[TYCHO]")
+
+
+def _paint(colour: str, text: str) -> str:
+    if os.environ.get("NO_COLOR"):
+        return text
+    return f"{colour}{text}{_RESET}"
+
+
+def repo_of(payload: dict) -> Path:
+    """Which repo the bar is being drawn for.
+
+    `workspace.project_dir` is the project root; `cwd` follows the user around it. Prefer
+    the root — that's where `.tycho/` lives — and fall back to our own cwd for a human
+    running `tycho status` by hand.
+    """
+    workspace = payload.get("workspace")
+    if isinstance(workspace, dict) and isinstance(workspace.get("project_dir"), str):
+        return Path(workspace["project_dir"])
+    cwd = payload.get("cwd")
+    return Path(cwd) if isinstance(cwd, str) else Path.cwd()
+
+
+def _stdin_text() -> str:
+    """The harness's JSON on stdin as raw text — or "" when a human ran this in a terminal.
+
+    Raw, not parsed, because a *wrapped* status command (composition, TYCHO-47) needs the
+    exact same bytes forwarded to it. The isatty check keeps `tycho status` from hanging on
+    an interactive read: no payload is coming, and a status command that blocks is worse
+    than one that says nothing.
+    """
+    if sys.stdin.isatty():
+        return ""
+    try:
+        return sys.stdin.read() or ""
+    except (OSError, ValueError):
+        return ""
+
+
+def _parse(text: str) -> dict:
+    try:
+        payload = json.loads(text or "{}")
+    except (json.JSONDecodeError, ValueError):
+        return {}
+    return payload if isinstance(payload, dict) else {}
+
+
+def _wrapped_output(repo: Path, stdin_text: str) -> str:
+    """Run the status command Tycho is composing with, and return its line (TYCHO-47).
+
+    Claude Code's statusLine holds one slot, so to coexist with another status line (a
+    third-party badge, a shell prompt) Tycho *becomes* the slot and runs the other command
+    itself, forwarding the same payload on stdin. Fail-open to "": a slow or broken
+    neighbour must never take Tycho's own segment — or the whole line — down with it.
+    """
+    wrap = state.read_statusline_wrap(repo)
+    command = wrap.get("command") if isinstance(wrap, dict) else None
+    if not isinstance(command, str) or not command:
+        return ""
+    try:
+        proc = subprocess.run(
+            command, shell=True, input=stdin_text, capture_output=True,
+            text=True, timeout=3, encoding="utf-8", errors="replace",
+        )
+    except Exception:
+        return ""
+    return proc.stdout.strip() if proc.returncode == 0 else ""
+
+
+def main(off: bool = False, on: bool = False) -> int:
+    try:
+        # This line is UTF-8 (⬤, [TYCHO] colour codes). On Windows, stdout to a pipe
+        # defaults to cp1252, where writing it raises UnicodeEncodeError — the crash
+        # TYCHO-40 found in `doctor`. Say what encoding we speak instead of dying, and
+        # don't assume reconfigure exists (a wrapped stdout may not have it).
+        sys.stdout.reconfigure(encoding="utf-8", errors="replace")
+    except Exception:
+        pass
+    raw = _stdin_text()
+    repo = repo_of(_parse(raw))
+    if off or on:
+        # A human toggling from the terminal (TYCHO-47) — repo is our cwd, not a payload.
+        state.set_status_enabled(repo, enabled=on)
+        print(f"tycho: status indicator {'shown' if on else 'hidden'} for {repo}"
+              f"{'' if on else ' — the hook keeps verifying; run `tycho status --on` to show it'}")
+        return 0
+    try:
+        segments = [_wrapped_output(repo, raw), line(repo)]
+        text = " ".join(s for s in segments if s)
+        if text:
+            print(text)
+    except Exception:
+        # broad catch is the point — this draws in someone's terminal on every
+        # render. Empty output is the fail-open, and exit 0 keeps the harness quiet.
+        pass
+    return 0