tare-cli 0.2.0__py3-none-any.whl

tare/probe.py

@@ -0,0 +1,273 @@
+"""tare probe: measure the room before the run (CONCEPT.md, layer 3).
+
+Three readings, none of which asks the agent anything:
+
+- context: the real CLI runs inside the room against a fake model endpoint, which
+  keeps the request, i.e. the context the harness actually assembled;
+- control: the same run in the user's real setup (the dirty twin). The probe must find
+  the user's context there, or it is blind for that class;
+- reach: a plain script inside the room looks for the user's files and inherited
+  environment variables; the same script outside is its control.
+"""
+import os
+import re
+import subprocess
+import time
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from .agents import Capture, Real
+from .fake import Fake
+from .room import ROOM_HOME, TareError, bwrap, room_env, room_home
+
+SECRET_PATHS = (".claude", ".claude.json", ".codex", ".agents", ".config/gh", ".ssh", ".aws", ".netrc",
+                ".git-credentials", ".docker/config.json")
+REACH_SCRIPT = ('for p in "$@"; do if [ -e "$p" ]; then echo "path $p"; fi; done; '
+                'env | cut -d= -f1 | sed "s/^/env /"')
+SHELL_ENV = {"PWD", "OLDPWD", "SHLVL", "_"}
+LABELS = {"instructions": "global instructions", "memories": "memories"}
+# An offered MCP tool: an entry of the tools array, or a whole line of a deferred-tools
+# listing (tool search). A mention inside prose, e.g. in instructions, is not one.
+MCP_TOOL = re.compile(r"^(mcp__[A-Za-z0-9_.\-]+?__)[A-Za-z0-9_.\-]+$", re.M)
+# Under load a dirty twin can send its request before its MCP servers are connected. A blind
+# twin gets one more try after this pause, and the reading says so.
+TWIN_RETRY_PAUSE = 10
+
+
+@dataclass
+class Finding:
+    kind: str
+    what: str
+    source: str
+
+
+@dataclass
+class Reading:
+    agent: str = "?"
+    version: str = "?"
+    leaks: list[Finding] = field(default_factory=list)
+    declared: list[Finding] = field(default_factory=list)
+    seen: list[str] = field(default_factory=list)  # classes the control found in the dirty twin
+    blind: list[str] = field(default_factory=list)  # classes the user has but the dirty twin did not show
+    retried: list[str] = field(default_factory=list)  # classes a first dirty twin was blind for
+
+    @property
+    def zero(self) -> bool:
+        return not self.leaks and not self.blind
+
+
+def _capture(agent, argv: list[str], env: dict[str, str], cwd: Path, fake: Fake) -> Capture:
+    proc = subprocess.run(argv, env=env, cwd=cwd, capture_output=True, text=True, timeout=300,
+                          stdin=subprocess.DEVNULL)
+    capture = agent.capture(proc.stdout, fake.requests)
+    if capture is None:
+        detail = proc.stderr.strip()[-300:] or proc.stdout.strip()[-300:] or "no output"
+        raise TareError(f"{agent.name} never reached tare's fake model server, so the probe could not run "
+                        f"(exit {proc.returncode}): {detail}")
+    return capture
+
+
+def instruction_lines(path: Path) -> list[str]:
+    """Distinctive lines of a file of the user's, used as markers."""
+    try:
+        lines = [line.strip() for line in path.read_text().splitlines()]
+    except OSError:
+        return []
+    return [line[:80] for line in lines if len(line) >= 30][:5]
+
+
+def _mcp_prefixes(capture: Capture) -> set[str]:
+    return set(MCP_TOOL.findall(capture.text + "\n" + "\n".join(capture.tools)))
+
+
+def _without_paths(text: str) -> str:
+    """Skill lines with their "(path)" removed: agy names each skill's file, and the room's
+    path (/home/tare/...) differs from the user's for the same skill."""
+    return re.sub(r" \([^)\n]*\)", "", text)
+
+
+def _server_prefix(name: str) -> str:
+    return "mcp__" + re.sub(r"[^A-Za-z0-9_-]", "_", name) + "__"
+
+
+def parent_instructions(project: Path) -> list[Path]:
+    """Instruction files in the project's parent directories: the user's, not the project's."""
+    return [d / name for d in project.parents for name in ("AGENTS.md", "CLAUDE.md") if (d / name).is_file()]
+
+
+def score(agent, real: Real, twin: Capture, room: Capture, reach_in: str, reach_out: str,
+          bare: Capture | None = None, project: Path | None = None) -> Reading:
+    r = Reading(agent=agent.name, version=room.init.get("claude_code_version", "?"))
+
+    # instruction files above the project; an agent that does not read them cannot leak them
+    for path in parent_instructions(project) if project else []:
+        lines = instruction_lines(path)
+        if lines and any(line in twin.text for line in lines):
+            if "parent files" not in r.seen:
+                r.seen.append("parent files")
+            if any(line in room.text for line in lines):
+                r.leaks.append(Finding("parent files", "instructions above the project", str(path)))
+
+    # extensions: tools the dirty twin offers that a run without extensions does not
+    if bare is not None:
+        extension_tools = twin.tools - bare.tools
+        if extension_tools:
+            r.seen.append("extensions")
+        r.leaks += [Finding("extensions", name, "a tool of your extensions") for name in sorted(extension_tools & room.tools)]
+
+    # the user's own files: global instructions, and whatever else the agent reads (memories)
+    for kind, path in [("instructions", agent.instructions(real)), *agent.extra_markers(real)]:
+        lines = instruction_lines(path)
+        if lines:
+            (r.seen if any(line in twin.text for line in lines) else r.blind).append(kind)
+            if any(line in room.text for line in lines):
+                r.leaks.append(Finding(kind, LABELS.get(kind, kind), str(path)))
+
+    # the real home path: memory paths, parent-directory instruction files, hook output
+    home = f"{real.home}/"
+    if home in twin.text:
+        r.seen.append("home path")
+    if home in room.text:
+        r.leaks.append(Finding("home path", home, "your files"))
+
+    # MCP servers and connectors
+    twin_servers = _mcp_prefixes(twin)
+    connected = [s["name"] for s in twin.init.get("mcp_servers", []) if s.get("status") == "connected"]
+    if any(_server_prefix(name) not in twin_servers for name in connected):
+        r.blind.append("mcp")
+    elif twin_servers:
+        r.seen.append("mcp")
+    for prefix in sorted(_mcp_prefixes(room)):
+        source = "connected account (login)" if prefix.startswith("mcp__claude_ai_") else "MCP server"
+        r.leaks.append(Finding("mcp", prefix[5:-2], source))
+
+    # skills from plugins, the user's skill directories and the account
+    plugins = twin.init.get("plugins", [])
+    builtin = {p["name"] for p in plugins if p.get("path") == "builtin"}
+    user_plugins = {p["name"] for p in plugins if p.get("path") != "builtin"}
+    own: dict[str, Path] = {}
+    for skill_dir in agent.skill_dirs(real):
+        if skill_dir.is_dir():
+            own |= {d.name: skill_dir for d in skill_dir.iterdir() if d.is_dir() and not d.name.startswith(".")}
+    names = {s for s in twin.init.get("skills", []) if ":" in s and s.split(":")[0] not in builtin} | set(own)
+    listed = {}
+    for name in sorted(names):
+        # the skills listing has one "- name: description" line per skill ("- name (path): ..." in agy)
+        match = re.search(rf"^- {re.escape(name)}(?:[:( ].*)?$", twin.text, re.M)
+        if match:
+            namespace = name.split(":")[0] if ":" in name else None
+            source = (str(own[name]) if namespace is None
+                      else f"plugin {namespace}" if namespace in user_plugins else "login (account skills)")
+            listed[_without_paths(match.group(0))[:160]] = source
+    if names:
+        (r.seen if listed else r.blind).append("skills")
+    counts: dict[str, int] = {}
+    room_lines = _without_paths(room.text)
+    for line, source in listed.items():
+        if line in room_lines:
+            counts[source] = counts.get(source, 0) + 1
+    r.leaks += [Finding("skills", f"{n} skill{'s' if n != 1 else ''}", source) for source, n in sorted(counts.items())]
+    if user_plugins:
+        r.seen.append("plugins")
+    r.leaks += [Finding("plugin", p["name"], p.get("path", "?"))
+                for p in room.init.get("plugins", []) if p.get("path") != "builtin"]
+
+    # the account email comes with subscription auth: declared, not a leak
+    email = agent.email(real)
+    if email and email in twin.text:
+        r.seen.append("email")
+        if email in room.text:
+            r.declared.append(Finding("email", "account email", "subscription login"))
+
+    # reach: the same script outside (control) and inside the room
+    if any(line.startswith("path ") for line in reach_out.splitlines()):
+        r.seen.append("reach")
+    allowed = set(room_env(agent)) | SHELL_ENV
+    for line in reach_in.splitlines():
+        kind, _, value = line.partition(" ")
+        if kind == "path":
+            r.leaks.append(Finding("reach", value, "visible inside the room"))
+        elif kind == "env" and value not in allowed:
+            r.leaks.append(Finding("env", value, "inherited environment"))
+    for name in getattr(agent, "secret_files", [agent.credentials]):
+        r.declared.append(Finding("credentials", f"{agent.room_config}/{name}", "copy of the login, needed by the CLI"))
+    return r
+
+
+def settle(run_twin, read) -> Reading:
+    """Read with a dirty twin; a twin blind for some class gets one more try."""
+    reading = read(run_twin())
+    if reading.blind:
+        first = list(reading.blind)
+        time.sleep(TWIN_RETRY_PAUSE)
+        reading = read(run_twin())
+        reading.retried = first
+    return reading
+
+
+def probe(agent, real: Real, project: Path) -> Reading:
+    project = project.resolve()
+    targets = [str(real.home), str(real.config), *(str(real.home / p) for p in SECRET_PATHS)]
+    if Path("/mnt/c").is_dir():
+        targets.append("/mnt/c")  # WSL: the Windows drive and its user profile
+
+    # the dirty twin: the user's real setup, as a plain terminal would start it
+    twin_env = {k: v for k, v in os.environ.items() if not k.startswith("CLAUDE") or k == "CLAUDE_CONFIG_DIR"}
+
+    def run_twin() -> Capture:
+        with Fake() as fake:
+            args, env = agent.probe(fake.url)
+            with agent.twin(real, fake.url) as extra:
+                env = twin_env | env | extra
+                argv = [str(real.binary), *args]
+                if hasattr(agent, "twin_argv"):  # a twin that must not write into the real setup
+                    argv = agent.twin_argv(argv, env)
+                return _capture(agent, argv, env, project, fake)
+
+    def in_room(home: Path, flags: list[str]) -> Capture:
+        with Fake() as fake:
+            agent.prepare_probe(home / Path(agent.room_config).relative_to(ROOM_HOME), fake.url)
+            args, env = agent.probe(fake.url)
+            argv = bwrap(agent, real, home, project, [agent.name, *flags, *args], env)
+            return _capture(agent, argv, {**os.environ}, project, fake)
+
+    with room_home(agent, real) as home:
+        room = in_room(home, agent.room_flags)
+        # where an agent loads extensions, a run without them shows which tools are its own
+        bare = in_room(home, [*agent.room_flags, *agent.bare_flags]) if getattr(agent, "bare_flags", None) else None
+        reach = ["/bin/sh", "-c", REACH_SCRIPT, "reach", *targets]
+        reach_in = subprocess.run(bwrap(agent, real, home, project, reach), capture_output=True, text=True,
+                                  timeout=60, check=True).stdout
+    reach_out = subprocess.run(reach, capture_output=True, text=True, timeout=60, check=True).stdout
+    return settle(run_twin, lambda twin: score(agent, real, twin, room, reach_in, reach_out, bare=bare,
+                                                project=project))
+
+
+def render(reading: Reading, project: Path) -> str:
+    width = max((len(f.what) for f in reading.leaks + reading.declared), default=0) + 2
+
+    def rows(findings):
+        return [f"    {f.kind:<13}{f.what:<{width}}{f.source}" for f in findings]
+
+    version = f" {reading.version}" if reading.version != "?" else ""
+    out = [f"tare probe · {reading.agent}{version} · {project}",
+           f"  control   dirty twin shows: {', '.join(reading.seen) or 'nothing'}"]
+    if reading.retried:
+        out.append(f"  retried   the first dirty twin was blind for {', '.join(reading.retried)}. "
+                   "This reading comes from a second one.")
+    for cls in reading.blind:
+        out.append(f"  BLIND     {cls}: you have it, but the dirty twin did not show it, so the room cannot be "
+                   "proven clean of it")
+    if reading.leaks:
+        out += ["  leaks", *rows(reading.leaks)]
+    else:
+        out.append("  leaks     none")
+    if reading.declared:
+        out += ["  declared", *rows(reading.declared)]
+    if reading.zero:
+        out.append("tare: 0.00")
+    elif reading.leaks:
+        out.append(f"tare: {len(reading.leaks)} leak{'s' if len(reading.leaks) != 1 else ''}")
+    else:
+        out.append("tare: not proven (blind)")
+    return "\n".join(out)

tare/recipe.py

@@ -0,0 +1,102 @@
+"""Recipes: how to repeat a Cliff or Swap run exactly.
+
+Every run directory gets a recipe.json: the command, the task and check, a digest of the
+project as it was, the agents with their CLI versions and arguments, and the parameters.
+`tare rerun DIR` repeats the command and says what has changed since.
+"""
+import hashlib
+import json
+import os
+import subprocess
+import time
+from importlib import metadata
+from pathlib import Path
+
+# directories that hold tooling, not the project's content
+SKIP = {".git", ".venv", "venv", "node_modules", "__pycache__", ".pytest_cache", ".ruff_cache"}
+
+
+def project_digest(project: Path) -> str:
+    digest = hashlib.sha256()
+    for root, dirs, files in os.walk(project):
+        dirs[:] = sorted(d for d in dirs if d not in SKIP)
+        for name in sorted(files):
+            path = Path(root) / name
+            if path.is_symlink() or not path.is_file():
+                continue
+            digest.update(str(path.relative_to(project)).encode() + b"\0")
+            digest.update(hashlib.sha256(path.read_bytes()).digest())
+    return digest.hexdigest()
+
+
+def cli_version(real) -> str:
+    try:
+        proc = subprocess.run([str(real.binary), "--version"], capture_output=True, text=True, timeout=30,
+                              stdin=subprocess.DEVNULL)
+        return (proc.stdout or proc.stderr).strip().splitlines()[0]
+    except (OSError, subprocess.TimeoutExpired, IndexError):
+        return "unknown"
+
+
+def tare_version() -> str:
+    try:
+        return metadata.version("tare-cli")
+    except metadata.PackageNotFoundError:
+        return "unknown"
+
+
+def without_out(argv: list[str]) -> list[str]:
+    """The command without its --out, so a rerun gets a run directory of its own."""
+    result, skip = [], False
+    for i, arg in enumerate(argv):
+        if skip:
+            skip = False
+            continue
+        if arg == "--":
+            return result + argv[i:]
+        if arg == "--out":
+            skip = True
+            continue
+        if not arg.startswith("--out="):
+            result.append(arg)
+    return result
+
+
+def with_out(argv: list[str], out: Path) -> list[str]:
+    at = argv.index("--") if "--" in argv else len(argv)
+    return argv[:at] + ["--out", str(out)] + argv[at:]
+
+
+def write(out: Path, argv: list[str], kind: str, project: Path, task: str, check: str,
+          agents: dict[str, tuple[object, object, list[str]]], params: dict) -> dict:
+    recipe = {
+        "kind": kind, "argv": without_out(argv), "out": str(out), "created": time.strftime("%Y-%m-%dT%H:%M:%S%z"),
+        "tare": tare_version(), "task": task, "check": check, "project": str(project),
+        "project_digest": project_digest(project),
+        "agents": {key: {"name": agent.name, "args": args, "version": cli_version(real)}
+                   for key, (agent, real, args) in agents.items()},
+        "params": params,
+    }
+    (out / "recipe.json").write_text(json.dumps(recipe, indent=2, ensure_ascii=False) + "\n")
+    return recipe
+
+
+def read(out: Path) -> dict:
+    return json.loads((out / "recipe.json").read_text())
+
+
+def drift(recipe: dict, reals: dict[str, object]) -> list[str]:
+    """What is no longer as it was when the recipe was written."""
+    notes = []
+    project = Path(recipe["project"])
+    if not project.is_dir():
+        notes.append(f"the project {project} is gone")
+    elif project_digest(project) != recipe["project_digest"]:
+        notes.append(f"the project {project} has changed since the recipe was written")
+    for key, agent in recipe["agents"].items():
+        real = reals.get(agent["name"])
+        if real is not None and (now := cli_version(real)) != agent["version"]:
+            notes.append(f"agent {key} ({agent['name']}) was {agent['version']}, is now {now}")
+    if (now := tare_version()) != recipe["tare"]:
+        notes.append(f"tare was {recipe['tare']}, is now {now}")
+    return notes

tare/room.py

@@ -0,0 +1,67 @@
+"""The room: a bubblewrap sandbox where nothing of the user's came along.
+
+Inside, /home is an empty tmpfs. Only a fresh per-run home (with a copy of the agent's
+login), the CLI and the project directory are mounted, and the environment is cleared
+down to an allowlist. Linux and WSL only (bubblewrap, user namespaces).
+"""
+import os
+import shutil
+import tempfile
+from contextlib import contextmanager
+from pathlib import Path
+
+ROOM_HOME = "/home/tare"
+ROOM_PROJECT = "/work"
+# Copied from the caller when set; everything else stays outside.
+PASS_ENV = ("TERM", "COLORTERM", "LANG", "LC_ALL")
+# The room must not refresh the login: a refresh may rotate the token family the real
+# session depends on (CONCEPT.md, layer 2). An hour covers ordinary runs.
+MIN_TOKEN_LIFETIME = 3600
+
+
+class TareError(Exception):
+    pass
+
+
+@contextmanager
+def room_home(agent, real):
+    """A fresh home for one room, holding a copy of the agent's login; removed afterwards."""
+    left = agent.token_lifetime(real)
+    if left < MIN_TOKEN_LIFETIME:
+        raise TareError(f"the {agent.name} login token expires in {max(0, int(left // 60))} min: "
+                        f"start any {agent.name} session to refresh it, then retry")
+    home = Path(tempfile.mkdtemp(prefix="tare-room-"))
+    try:
+        config = home / Path(agent.room_config).relative_to(ROOM_HOME)
+        config.mkdir(parents=True)
+        agent.seed(real, config)
+        yield home
+    finally:
+        shutil.rmtree(home, ignore_errors=True)
+
+
+def room_env(agent, extra: dict[str, str] | None = None) -> dict[str, str]:
+    env = {k: os.environ[k] for k in PASS_ENV if k in os.environ}
+    env |= {"HOME": ROOM_HOME, "PATH": "/opt/agent:/usr/bin:/bin", **agent.room_env()}
+    return env | (extra or {})
+
+
+def bwrap(agent, real, home: Path, project: Path, command: list[str], extra_env: dict[str, str] | None = None,
+          extra_binds: list[str] | None = None) -> list[str]:
+    """The bwrap command for one room. `command[0]` may be the agent's own name."""
+    binds, executable = agent.binds(real)
+    if command and command[0] == agent.name:
+        command = [executable, *command[1:]]
+    argv = ["bwrap", "--ro-bind", "/usr", "/usr", "--ro-bind", "/etc", "/etc",
+            "--symlink", "usr/bin", "/bin", "--symlink", "usr/lib", "/lib", "--symlink", "usr/lib64", "/lib64"]
+    if Path("/mnt/wsl").is_dir():
+        # WSL keeps the resolver behind a symlink into /mnt/wsl; without it DNS fails.
+        argv += ["--ro-bind", "/mnt/wsl", "/mnt/wsl"]
+    argv += ["--proc", "/proc", "--dev", "/dev", "--tmpfs", "/tmp", "--tmpfs", "/home",
+             "--bind", str(home), ROOM_HOME, *binds, *(extra_binds or []),
+             "--bind", str(project), ROOM_PROJECT, "--chdir", ROOM_PROJECT,
+             "--unshare-user", "--unshare-pid", "--unshare-ipc", "--unshare-uts", "--die-with-parent",
+             "--clearenv"]
+    for key, value in room_env(agent, extra_env).items():
+        argv += ["--setenv", key, value]
+    return argv + ["--", *command]

tare/swap.py

@@ -0,0 +1,219 @@
+"""Swap: the room or the model (epic Swap).
+
+Two agents, a and b, each run the task once in a room, with a capsule per step. At each cut,
+a fraction of each run, both rooms are crossed with both agents: every agent continues
+every room, by the same rendered handoff, so diagonal and off-diagonal cells read the
+same kind of input. The state effect is how much better the tails do in room a than in
+room b, averaged over the agents; the model effect is how much better agent a does than
+agent b, averaged over the rooms. Where an agent can resume its own session natively, a
+native cell on its own room prices the handoff itself (foreignness). At cut 0 both rooms
+are the untouched project, so the state effect there must be zero: the null check.
+"""
+import math
+from concurrent.futures import ThreadPoolExecutor
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from . import capsule as caps
+from . import usage as usages
+from .cliff import wilson
+from .journal import Journal
+
+
+@dataclass
+class Side:
+    key: str  # "a" or "b"
+    agent: object
+    real: object
+    args: list[str]
+    out: Path
+    steps: list = field(default_factory=list)
+    events: list = field(default_factory=list)
+    original: str = ""
+
+
+def newcombe(x1: int, n1: int, x2: int, n2: int) -> tuple[float, float, float]:
+    """Difference of two pass rates with a 95 % interval (Newcombe's hybrid score method)."""
+    p1, p2 = x1 / n1, x2 / n2
+    l1, u1 = wilson(x1, n1)
+    l2, u2 = wilson(x2, n2)
+    d = p1 - p2
+    return d, d - math.sqrt((p1 - l1) ** 2 + (u2 - p2) ** 2), d + math.sqrt((u1 - p1) ** 2 + (p2 - l2) ** 2)
+
+
+def mean_effect(differences: list[tuple[float, float, float]]) -> tuple[float, float, float]:
+    """Mean of independent differences; interval half-widths combine in quadrature."""
+    k = len(differences)
+    e = sum(d for d, _, _ in differences) / k
+    down = math.sqrt(sum((d - lo) ** 2 for d, lo, _ in differences)) / k
+    up = math.sqrt(sum((hi - d) ** 2 for d, _, hi in differences)) / k
+    return e, e - down, e + up
+
+
+@dataclass
+class Cut:
+    fraction: float
+    steps: dict[str, int]  # side -> step of its run
+    cells: dict[tuple[str, str], list[bool]] = field(default_factory=dict)  # (room, agent) -> passes
+    native: dict[str, list[bool]] = field(default_factory=dict)  # side -> passes of its own native resume
+
+    def count(self, room: str, agent: str) -> tuple[int, int]:
+        r = self.cells[(room, agent)]
+        return sum(r), len(r)
+
+    def state(self) -> tuple[float, float, float]:
+        return mean_effect([newcombe(*self.count("a", m), *self.count("b", m)) for m in "ab"])
+
+    def model(self) -> tuple[float, float, float]:
+        return mean_effect([newcombe(*self.count(r, "a"), *self.count(r, "b")) for r in "ab"])
+
+    def foreignness(self, side: str) -> tuple[float, float, float] | None:
+        if side not in self.native:
+            return None
+        native = self.native[side]
+        return newcombe(sum(native), len(native), *self.count(side, side))
+
+
+def swap(a: Side, b: Side, project: Path, prompt: str, check: str, out: Path, *, cuts: list[float],
+         tails: int = 3, jobs: int = 3, workspace_only: bool = False, env: dict[str, str] | None = None,
+         journal: Journal | None = None) -> str:
+    sides = {"a": a, "b": b}
+    journal = journal or Journal(None)
+    journal("start", kind="swap", task=prompt, check=check, project=str(project), tails=tails, cuts=cuts,
+            sides={s.key: {"agent": s.agent.name, "args": s.args, "dir": s.out.name,
+                           "billing": usages.billing(s.agent, s.real)} for s in (a, b)})
+    journal("phase", phase="original runs")
+    with ThreadPoolExecutor(max_workers=2) as pool:
+        list(pool.map(lambda s: caps.record(s.agent, s.real, project, s.out, prompt, s.args, env), (a, b)))
+    for side in (a, b):
+        passed, detail, spent = caps.check_original(side.agent, side.out, check)
+        side.steps = caps.capsules(side.out, side.agent)
+        side.events = side.agent.trail(caps.session_lines(side.out)).events
+        side.original = f"{'passed' if passed else 'failed'} ({detail}) after {len(side.steps) - 1} steps"
+        journal("original", side=side.key, passed=passed, detail=detail, steps=[s.tool for s in side.steps], **spent)
+
+    plan = [Cut(f, {k: round(f * (len(s.steps) - 1)) for k, s in sides.items()}) for f in cuts]
+    journal("plan", cuts=[{"fraction": c.fraction, "steps": c.steps} for c in plan])
+    journal("phase", phase="tails")
+    jobs_list = []
+    for i, cut in enumerate(plan):
+        for room in "ab":
+            capsule = sides[room].steps[cut.steps[room]]
+            for agent in "ab":
+                cut.cells[(room, agent)] = []
+                for n in range(tails):
+                    jobs_list.append(("cell", i, room, agent, n, capsule))
+            if sides[room].agent.native_resume:
+                cut.native[room] = []
+                for n in range(tails):
+                    jobs_list.append(("native", i, room, room, n, capsule))
+
+    def run(job):
+        kind, i, room, agent, n, capsule = job
+        name = f"cut{i}/{kind}-room-{room}-agent-{agent}-{n}"
+        tail_dir = out / "swap" / name
+        journal("tail", id=name, status="running", cut=i, room=room, agent=agent, kind=kind,
+                agent_name=sides[agent].agent.name, dir=f"swap/{name}")
+        if kind == "native":
+            s = sides[room]
+            tail = caps.run_tail(s.agent, s.real, s.out, capsule, prompt, s.args, check, n, env, tail_dir=tail_dir)
+        else:
+            s = sides[agent]
+            tail = caps.run_handoff(s.agent, s.real, tail_dir, capsule, sides[room].events, prompt, s.args, check,
+                                    env, workspace_only)
+        journal("tail", id=name, status="passed" if tail.passed else "failed", detail=tail.detail,
+                usage=tail.usage, check_usage=tail.check_usage)
+        return job, tail.passed
+
+    with ThreadPoolExecutor(max_workers=jobs) as pool:
+        for (kind, i, room, agent, _, _), passed in pool.map(run, jobs_list):
+            (plan[i].native[room] if kind == "native" else plan[i].cells[(room, agent)]).append(passed)
+
+    text = "\n".join(report(sides, plan, prompt, check, project, len(jobs_list), workspace_only)
+                     + usages.report(out)) + "\n"
+    (out / "report.txt").write_text(text)
+    journal("report", text=text)
+    journal("phase", phase="done")
+    return text
+
+
+def _leader(state: tuple[float, float, float], model: tuple[float, float, float]) -> str:
+    """Which explains more of the gap at a cut: the room, the model, both alike, or neither (both near zero)."""
+    if abs(state[0]) < 0.1 and abs(model[0]) < 0.1:
+        return "neither"
+    if abs(abs(state[0]) - abs(model[0])) < 0.1:
+        return "tie"
+    return "room" if abs(state[0]) > abs(model[0]) else "model"
+
+
+def _sign(effect: tuple[float, float, float]) -> str:
+    e, lo, hi = effect
+    return f"{e:+.2f} [{lo:+.2f}, {hi:+.2f}]"
+
+
+def report(sides: dict[str, Side], plan: list[Cut], prompt: str, check: str, project: Path, spent: int,
+           workspace_only: bool) -> list[str]:
+    def who(s: Side) -> str:
+        return f"{s.agent.name}{' ' + ' '.join(s.args) if s.args else ''}"
+
+    lines = [f"tare swap · a: {who(sides['a'])} · b: {who(sides['b'])} · {project}",
+             f"  task      {prompt}", f"  check     {check}",
+             f"  run a     {sides['a'].original}", f"  run b     {sides['b'].original}",
+             f"  handoff   {'workspace only' if workspace_only else 'workspace and a written summary of the steps so far'}"]
+    dominant, deciding = [], []
+    for cut in plan:
+        lines += ["", f"  cut {cut.fraction:.2f}: workspace a at step {cut.steps['a']}, workspace b at step {cut.steps['b']}",
+                  "                agent a          agent b"]
+        for room in "ab":
+            row = []
+            for agent in "ab":
+                x, n = cut.count(room, agent)
+                lo, hi = wilson(x, n)
+                row.append(f"{x}/{n} {lo:.2f}-{hi:.2f}")
+            lines.append(f"    workspace {room} {row[0]:<17}{row[1]}")
+        state, model = cut.state(), cut.model()
+        lines.append(f"    state effect  {_sign(state)}  (positive: workspace a better)")
+        lines.append(f"    model effect  {_sign(model)}  (positive: agent a better)")
+        for side in "ab":
+            cost = cut.foreignness(side)
+            if cost:
+                native, (passed, n) = cut.native[side], cut.count(side, side)
+                lines.append(f"    handoff cost {side} {_sign(cost)}  (own session {sum(native)}/{len(native)} against "
+                             f"handoff {passed}/{n}, both in its own workspace)")
+        dominant.append(_leader(state, model))
+        deciding.append(state if dominant[-1] in ("room", "tie") else model)
+    lines.append("")
+    first = plan[0]
+    if first.fraction == 0:
+        _, lo, hi = first.state()
+        lines.append("  null check   " + ("passed: no state effect at cut 0, where both workspaces are the untouched "
+                                          "project" if lo <= 0 <= hi else
+                                          f"FAILED: a state effect at cut 0 ({_sign(first.state())}), where both "
+                                          "workspaces are the same. Do not trust the effects above."))
+    shown = [i for i, d in enumerate(dominant) if d != "neither"]
+    late = next((i for i, d in enumerate(dominant) if d in ("room", "tie") and "model" in dominant[:i]), None)
+    if late is not None and dominant[late] == "tie" and "room" not in dominant:
+        verdict = (f"The model explains more than the workspace until cut {plan[late - 1].fraction:.2f}. From cut "
+                   f"{plan[late].fraction:.2f} on, workspace and model explain about the same.")
+    elif "room" in dominant and "model" in dominant[:dominant.index("room")]:
+        at = dominant.index("room")
+        before = max(i for i in range(at) if dominant[i] == "model")
+        verdict = (f"Blame passes from the model to the workspace between cut {plan[before].fraction:.2f} "
+                   f"and cut {plan[at].fraction:.2f}.")
+    elif not shown:
+        verdict = "Neither the workspace nor the model makes a difference at any cut."
+    elif {dominant[i] for i in shown} == {"model"}:
+        verdict = "The model explains more than the workspace " + ("at every cut." if len(shown) == len(plan)
+                                                                    else "wherever there is an effect.")
+    elif {dominant[i] for i in shown} == {"room"}:
+        verdict = "The workspace explains more than the model " + ("at every cut." if len(shown) == len(plan)
+                                                                    else "wherever there is an effect.")
+    else:
+        names = {"room": "workspace", "model": "model", "tie": "both alike", "neither": "neither"}
+        verdict = "No single pattern. What explains more, per cut: " + ", ".join(
+            f"{c.fraction:.2f} {names[d]}" for c, d in zip(plan, dominant)) + "."
+    if any(deciding[i][1] <= 0 <= deciding[i][2] for i in shown):
+        verdict += " The intervals behind this verdict include zero. More tails would settle it."
+    lines.append(f"  verdict      {verdict}")
+    lines.append(f"  tails        {spent}")
+    return lines