cairnmap 0.1.0__py3-none-any.whl

cairn/__init__.py

@@ -0,0 +1,3 @@
+"""cairn: a workspace-level repo map and router for coding agents."""
+
+__version__ = "0.1.0"

cairn/__main__.py

@@ -0,0 +1,3 @@
+from cairn.cli import app
+
+app()

cairn/authored_store.py

@@ -0,0 +1,135 @@
+"""Write harness/human-authored content (.cairn/authored/<repo>.yaml) without clobbering it."""
+
+import re
+from collections.abc import Iterable, Mapping
+from pathlib import Path
+from typing import Literal
+
+import yaml
+
+from cairn.errors import CairnError, CairnInputError
+from cairn.load import load_authored
+from cairn.model.graph import SYMMETRIC_TYPES, Edge, EdgeType
+from cairn.model.overrides import Authored
+from cairn.paths import authored_dir
+from cairn.resolve import resolve_repo
+from cairn.store.atomic import atomic_write_text
+from cairn.store.workspace_store import load_workspace
+
+_KEY = re.compile(r"^(?P<source>.+?)->(?P<target>.+):(?P<type>[a-z_]+)$")
+Review = Literal["confirmed", "rejected"]
+
+
+def parse_edge_key(key: str) -> tuple[str, str, EdgeType]:
+    match = _KEY.match(key.strip())
+    if not match:
+        raise CairnInputError(key, "expected an edge key like 'source->target:shares_db'")
+    try:
+        edge_type = EdgeType(match["type"])
+    except ValueError as exc:
+        raise CairnInputError(key, f"unknown edge type '{match['type']}'") from exc
+    return match["source"], match["target"], edge_type
+
+
+def save_authored(ws_root: Path, repo_id: str, authored: Authored) -> Path:
+    path = authored_dir(ws_root) / f"{repo_id}.yaml"
+    data = authored.model_dump(mode="json", exclude_defaults=True)
+    atomic_write_text(path, yaml.safe_dump(data, sort_keys=False, allow_unicode=True))
+    return path
+
+
+def annotate_edge(ws_root: Path, key: str, *, review: Review | None, why: str | None) -> Path:
+    """Record a review and/or explanation for an edge, keeping every other authored field.
+
+    The decision is stored under the edge's canonical key (its current direction), and any
+    stale copy under the reversed key is removed, so the newest decision always wins.
+    An edge the user rejected earlier is no longer in the map but can still be re-decided.
+    """
+    _, _, edge_type = parse_edge_key(key)
+    workspace = load_workspace(ws_root)
+    if workspace is None:
+        raise CairnError("No map found. Run `cairn scan` first.")
+    authored = load_authored(ws_root)
+    variants = _key_variants(key, edge_type)
+    canonical = _canonical_key(variants, edge_type, workspace.edges, authored)
+    if canonical is None:
+        raise CairnError(f"No edge '{key}' in the current map. `cairn status` lists edge keys.")
+    carried = _drop_variants(ws_root, authored, set(variants) - {canonical})
+    source = parse_edge_key(canonical)[0]
+    current = load_authored(ws_root).get(source, Authored())
+    reviews = {**current.edge_reviews}
+    whys = {**current.edge_whys}
+    if carried.edge_whys and canonical not in whys:
+        whys[canonical] = next(iter(carried.edge_whys.values()))  # keep the old explanation
+    if review is not None:
+        reviews[canonical] = review
+    if why:
+        whys[canonical] = why
+    update = {"edge_reviews": reviews, "edge_whys": whys}
+    return save_authored(ws_root, source, current.model_copy(update=update))
+
+
+def _key_variants(key: str, edge_type: EdgeType) -> tuple[str, ...]:
+    source, target, _ = parse_edge_key(key)
+    flipped = f"{target}->{source}:{edge_type.value}"
+    return (key, flipped) if edge_type in SYMMETRIC_TYPES else (key,)
+
+
+def _canonical_key(
+    variants: tuple[str, ...],
+    edge_type: EdgeType,
+    edges: Iterable[Edge],
+    authored: Mapping[str, Authored],
+) -> str | None:
+    live = next((e.key for e in edges if e.type is edge_type and e.key in variants), None)
+    if live is not None:
+        return live
+    decided = [k for a in authored.values() for k in (*a.edge_reviews, *a.edge_whys)]
+    return next((k for k in decided if k in variants), None)
+
+
+def _drop_variants(ws_root: Path, authored: Mapping[str, Authored], stale: set[str]) -> Authored:
+    """Remove stale keys from every authored file; return their whys so they can be carried over."""
+    carried: dict[str, str] = {}
+    for repo_id, entry in authored.items():
+        if not stale & {*entry.edge_reviews, *entry.edge_whys}:
+            continue
+        carried.update({k: v for k, v in entry.edge_whys.items() if k in stale})
+        cleaned = entry.model_copy(
+            update={
+                "edge_reviews": {k: v for k, v in entry.edge_reviews.items() if k not in stale},
+                "edge_whys": {k: v for k, v in entry.edge_whys.items() if k not in stale},
+            }
+        )
+        save_authored(ws_root, repo_id, cleaned)
+    return Authored(edge_whys=carried)
+
+
+SUMMARY_LIMIT = 500
+
+
+def set_summary(ws_root: Path, repo_id: str, summary: str, *, aliases: Iterable[str] = ()) -> Path:
+    """Store a harness/human-written summary (spec §9.2), stamped with the repo's current HEAD."""
+    text = " ".join(summary.split())
+    if not text:
+        raise CairnInputError("summary", "must not be empty")
+    if len(text) > SUMMARY_LIMIT:
+        raise CairnInputError(
+            "summary", f"is {len(text)} characters; keep it under {SUMMARY_LIMIT}"
+        )
+    workspace = load_workspace(ws_root)
+    if workspace is None:
+        raise CairnError("No map found. Run `cairn scan` first.")
+    repo = workspace.repo(repo_id)
+    if repo is None:
+        matches = resolve_repo(workspace, load_authored(ws_root), repo_id, limit=3)
+        hint = ", ".join(m.repo_id for m in matches) or "none"
+        raise CairnError(f"No repo '{repo_id}'. Did you mean: {hint}?")
+    current = load_authored(ws_root).get(repo_id, Authored())
+    extra = (a.strip().lower() for a in aliases if a.strip())
+    update = {
+        "summary": text,
+        "summary_sha": repo.head_sha,
+        "aliases": tuple(dict.fromkeys((*current.aliases, *extra))),
+    }
+    return save_authored(ws_root, repo_id, current.model_copy(update=update))

cairn/bench/conditions.py

@@ -0,0 +1,60 @@
+"""Set up one isolated workspace copy per benchmark condition (spec §11 E2).
+
+A: cold (no map, no CLAUDE.md)      B: hand-written RELATED_REPOS-style doc as CLAUDE.md
+C: cairn INDEX only (no cards/graph)  D: INDEX + cards          E: D + the cairn MCP server
+"""
+
+import json
+import shutil
+from dataclasses import dataclass
+from pathlib import Path
+
+from cairn.bench.suite import Suite
+from cairn.bench.workspace import materialize
+from cairn.emit import write_outputs
+from cairn.integrations.claude import install_claude
+from cairn.integrations.server_command import server_command
+from cairn.paths import cairn_dir, index_file
+from cairn.render.index import render_index
+from cairn.scan import scan_workspace
+from cairn.store.atomic import atomic_write_text
+
+CONDITIONS = ("A", "B", "C", "D", "E")
+
+
+@dataclass(frozen=True)
+class Prepared:
+    ws: Path
+    mcp_config: Path | None
+
+
+def prepare(condition: str, suite: Suite, suite_dir: Path, run_dir: Path) -> Prepared:
+    ws = materialize(suite_dir / suite.workspace, run_dir / "ws")
+    if condition in ("A", "B"):
+        shutil.rmtree(cairn_dir(ws), ignore_errors=True)  # no authored summaries either
+        if condition == "B":
+            doc = (suite_dir / suite.related_repos_doc).read_text(encoding="utf-8")
+            atomic_write_text(ws / "CLAUDE.md", doc)
+        return Prepared(ws, None)
+    result = scan_workspace(ws)
+    write_outputs(ws, result)
+    if condition == "C":
+        # INDEX only: no card pointer in the text, and no cards or graph JSON to read instead.
+        text = render_index(
+            result.workspace,
+            result.authored,
+            threshold=result.config.index_threshold,
+            with_cards=False,
+        )
+        atomic_write_text(index_file(ws), text)
+        install_claude(ws)
+        shutil.rmtree(cairn_dir(ws))
+        return Prepared(ws, None)
+    install_claude(ws)
+    if condition != "E":
+        return Prepared(ws, None)
+    config = run_dir / "mcp.json"
+    command = [*server_command(), "--workspace", ws.as_posix()]
+    entry = {"command": command[0], "args": command[1:]}
+    atomic_write_text(config, json.dumps({"mcpServers": {"cairn": entry}}, indent=2))
+    return Prepared(ws, config)

cairn/bench/grading.py

@@ -0,0 +1,119 @@
+"""Deterministic grading of benchmark answers (spec §11): file recall or required keywords."""
+
+import posixpath
+import re
+from dataclasses import dataclass
+from pathlib import Path
+
+from cairn.bench.suite import Task
+
+_SEGMENT = r"[\w@.\-\[\]]+"
+# Windows absolute, POSIX absolute, then relative `a/b/c` paths (either slash).
+_PATH = re.compile(rf"[A-Za-z]:[\\/][^\s`'\"()]+|/[^\s`'\"()]+|{_SEGMENT}(?:[\\/]{_SEGMENT})+")
+_TRAILING = ".,;:)"
+_DRIVE = re.compile(r"([A-Za-z]):/(.*)")
+_MSYS = re.compile(r"/([A-Za-z])/(.*)")
+PASS_RECALL = 0.8
+
+
+@dataclass(frozen=True)
+class Grade:
+    success: bool
+    recall: float
+    precision: float
+
+
+def _root_spellings(ws_root: Path) -> tuple[str, ...]:
+    """The workspace root as an agent might print it: as given, resolved, Git Bash style."""
+    spellings: set[str] = set()
+    for root in {ws_root.as_posix(), ws_root.resolve().as_posix()}:
+        root = root.rstrip("/") + "/"
+        spellings.add(root)
+        drive = _DRIVE.fullmatch(root)
+        if drive:
+            spellings.add(f"/{drive.group(1).lower()}/{drive.group(2)}")
+    return tuple(sorted(spellings, key=len, reverse=True))
+
+
+def _inside(path: str, roots: tuple[str, ...]) -> str | None:
+    """`path` relative to the workspace, or None when it points elsewhere."""
+    for root in roots:
+        if path.casefold().startswith(root.casefold()):
+            return path[len(root) :]
+    windows = any(_DRIVE.match(root) for root in roots)
+    try:  # 8.3 short names, symlinked temp dirs (macOS /var -> /private/var)
+        msys = _MSYS.fullmatch(path) if windows else None
+        real = Path(f"{msys.group(1)}:/{msys.group(2)}" if msys else path)
+        resolved = real.resolve().as_posix()
+    except (OSError, ValueError):
+        return None
+    for root in roots:
+        if resolved.casefold().startswith(root.casefold()):
+            return resolved[len(root) :]
+    return None
+
+
+def _heading_repo(line: str, repo_ids: set[str]) -> str | None | bool:
+    """For a heading-like line with no paths: the one repo it names, or None.
+
+    Returns False when the line isn't a heading (the current context carries on).
+    """
+    stripped = line.strip().strip("-* ").strip()
+    heading = line.lstrip().startswith("#") or stripped.endswith(":") or line.strip().endswith("**")
+    if not stripped or not heading or _PATH.search(line):
+        return False
+    named = [r for r in repo_ids if re.search(rf"(?<![\w-]){re.escape(r)}(?![\w-])", line)]
+    return named[0] if len(named) == 1 else None
+
+
+def _strip_root_tail(path: str, ws_parts: tuple[str, ...], repo_ids: set[str]) -> str:
+    """`ws/orders-svc/x` (relative to the workspace's parent) -> `orders-svc/x`."""
+    segments = path.split("/")
+    for i in range(1, min(len(segments), len(ws_parts) + 1)):
+        if segments[i] in repo_ids and tuple(segments[:i]) == ws_parts[-i:]:
+            return "/".join(segments[i:])
+    return path
+
+
+def mentioned_files(text: str, ws_root: Path, working_repo: str, repo_ids: set[str]) -> set[str]:
+    """Workspace paths (`repo/path`) named in `text`.
+
+    A bare path belongs to the repo named by the heading it sits under (`**orders-svc:**`),
+    else to the working repo.
+    """
+    roots = _root_spellings(ws_root)
+    ws_parts = tuple(p for p in ws_root.as_posix().split("/") if p)
+    found: set[str] = set()
+    context = working_repo
+    for line in text.splitlines():
+        heading = _heading_repo(line, repo_ids)
+        if heading is not False:
+            context = heading or working_repo
+            continue
+        for token in _PATH.findall(line):
+            path = token.replace("\\", "/").rstrip(_TRAILING)
+            if path.startswith("/") or _DRIVE.match(path):
+                inside = _inside(path, roots)
+                if inside is None:
+                    continue
+                path = inside
+            else:
+                path = _strip_root_tail(path, ws_parts, repo_ids)
+                if path.split("/", 1)[0] not in repo_ids:
+                    path = f"{context}/{path}"
+            path = posixpath.normpath(path)
+            if not path.startswith(".."):
+                found.add(path)
+    return found
+
+
+def grade(task: Task, text: str, ws_root: Path, repo_ids: set[str]) -> Grade:
+    keywords_ok = all(k.lower() in text.lower() for k in task.expect_keywords)
+    if not task.expect_files:
+        return Grade(success=keywords_ok, recall=1.0 if keywords_ok else 0.0, precision=1.0)
+    found = mentioned_files(text, ws_root, task.repo, repo_ids)
+    expected = set(task.expect_files)
+    hits = len(found & expected)
+    recall = hits / len(expected)
+    precision = hits / len(found) if found else 0.0
+    return Grade(success=keywords_ok and recall >= PASS_RECALL, recall=recall, precision=precision)

cairn/bench/report.py

@@ -0,0 +1,76 @@
+"""Markdown summary of a benchmark run: per-condition totals, then condition × task."""
+
+from collections.abc import Mapping, Sequence
+from statistics import fmean
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from cairn.bench.run import RunRecord
+
+
+def _mean(values: Sequence[float]) -> float:
+    return fmean(values) if values else 0.0
+
+
+def _summary(records: Sequence["RunRecord"]) -> list[str]:
+    """Success counts every run; token/cost/turn means use only runs that didn't error,
+    since an errored run reports zeros that would flatter its condition."""
+    lines = [
+        "| Condition | Runs | Success | Fresh tokens | Cache-read tokens | Cost (USD) | Turns "
+        "| Errors |",
+        "|---|---|---|---|---|---|---|---|",
+    ]
+    for condition in dict.fromkeys(r.condition for r in records):
+        rows = [r for r in records if r.condition == condition]
+        ok = [r for r in rows if not r.result.is_error]
+        success = sum(r.grade.success for r in rows) / len(rows)
+        lines.append(
+            f"| {condition} | {len(rows)} | {success:.0%} "
+            f"| {_mean([r.result.fresh_tokens for r in ok]):,.0f} "
+            f"| {_mean([r.result.cache_read_tokens for r in ok]):,.0f} "
+            f"| {_mean([r.result.cost_usd for r in ok]):.4f} "
+            f"| {_mean([r.result.num_turns for r in ok]):.1f} "
+            f"| {len(rows) - len(ok)} |"
+        )
+    return lines
+
+
+def _per_task(records: Sequence["RunRecord"]) -> list[str]:
+    lines = [
+        "| Condition | Task | Success | Recall | Cost (USD) |",
+        "|---|---|---|---|---|",
+    ]
+    for condition in dict.fromkeys(r.condition for r in records):
+        for task_id in dict.fromkeys(r.task_id for r in records):
+            rows = [r for r in records if r.condition == condition and r.task_id == task_id]
+            if not rows:
+                continue
+            passed = sum(r.grade.success for r in rows)
+            lines.append(
+                f"| {condition} | {task_id} | {passed}/{len(rows)} "
+                f"| {_mean([r.grade.recall for r in rows]):.2f} "
+                f"| {_mean([r.result.cost_usd for r in rows if not r.result.is_error]):.4f} |"
+            )
+    return lines
+
+
+def render_markdown(
+    records: Sequence["RunRecord"], *, meta: Mapping[str, object] | None = None
+) -> str:
+    errors = sum(r.result.is_error for r in records)
+    about = [f"{key}: {value}" for key, value in (meta or {}).items() if key != "tasks"]
+    parts = [
+        "# cairn benchmark",
+        "",
+        *([", ".join(about), ""] if about else []),
+        "Conditions: A cold, B hand-written doc, C cairn INDEX, D INDEX + cards, E D + MCP",
+        "",
+        *_summary(records),
+        "",
+        "## Per task",
+        "",
+        *_per_task(records),
+    ]
+    if errors:
+        parts += ["", f"{errors} run(s) ended in an agent error; see the JSON for details."]
+    return "\n".join(parts) + "\n"

cairn/bench/run.py

@@ -0,0 +1,77 @@
+"""Run a benchmark suite across conditions and write a report (spec §11 E2)."""
+
+import json
+import tempfile
+from collections.abc import Mapping, Sequence
+from dataclasses import asdict, dataclass
+from datetime import UTC, datetime
+from pathlib import Path
+
+import cairn
+from cairn.bench.conditions import prepare
+from cairn.bench.grading import Grade, grade
+from cairn.bench.report import render_markdown
+from cairn.bench.runner import Runner, RunResult
+from cairn.bench.suite import load_suite
+from cairn.store.atomic import atomic_write_text
+
+__all__ = ["RunRecord", "render_markdown", "run_bench"]
+
+
+@dataclass(frozen=True)
+class RunRecord:
+    condition: str
+    task_id: str
+    run: int
+    grade: Grade
+    result: RunResult
+
+
+def run_bench(
+    suite_dir: Path,
+    *,
+    conditions: Sequence[str],
+    runs: int,
+    task_ids: Sequence[str] | None,
+    runner: Runner,
+    out_dir: Path,
+    now: str,
+    meta: Mapping[str, object] | None = None,
+) -> tuple[RunRecord, ...]:
+    """Each finished run is appended to `<now>.jsonl` at once, so an interrupted (paid)
+    benchmark keeps what it already measured; `<now>.json` and `.md` are written at the end."""
+    suite = load_suite(suite_dir)
+    tasks = [t for t in suite.tasks if not task_ids or t.id in task_ids]
+    header = {
+        "cairn_version": cairn.__version__,
+        "suite": suite.name,
+        "conditions": list(conditions),
+        "runs": runs,
+        "tasks": [t.id for t in tasks],
+        "started_at": datetime.now(UTC).isoformat(timespec="seconds"),
+        **(meta or {}),
+    }
+    out_dir.mkdir(parents=True, exist_ok=True)
+    log = out_dir / f"{now}.jsonl"
+    records: list[RunRecord] = []
+    for condition in conditions:
+        for task in tasks:
+            for index in range(runs):
+                # The MCP server of condition E may still hold files for a moment on Windows.
+                with tempfile.TemporaryDirectory(
+                    prefix="cairn-bench-", ignore_cleanup_errors=True
+                ) as tmp:
+                    prepared = prepare(condition, suite, suite_dir, Path(tmp))
+                    ws = prepared.ws
+                    repo_ids = {p.name for p in ws.iterdir() if (p / ".git").exists()}
+                    result = runner.run(task.prompt, ws / task.repo, ws, prepared.mcp_config)
+                    graded = grade(task, result.result_text, ws, repo_ids)
+                record = RunRecord(condition, task.id, index, graded, result)
+                records.append(record)
+                with log.open("a", encoding="utf-8") as handle:
+                    handle.write(json.dumps(asdict(record)) + "\n")
+    out = tuple(records)
+    report = {"meta": header, "records": [asdict(r) for r in out]}
+    atomic_write_text(out_dir / f"{now}.json", json.dumps(report, indent=2))
+    atomic_write_text(out_dir / f"{now}.md", render_markdown(out, meta=header))
+    return out

cairn/bench/runner.py

@@ -0,0 +1,176 @@
+"""Run one benchmark prompt through a headless agent (spec §11 E2).
+
+ClaudeRunner drives `claude -p` in an isolated, read-only session: user settings and
+memory are not loaded (`--setting-sources project,local`), only the MCP servers in the
+condition's config are visible (`--strict-mcp-config`), and only read tools are allowed
+(no shell: even `find` can delete or run programs through `-delete`/`-exec`).
+"""
+
+import json
+import os
+import re
+import shutil
+import subprocess
+from collections.abc import Callable
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Protocol
+
+READ_ONLY_TOOLS = ("Read", "Grep", "Glob", "mcp__cairn")
+
+
+@dataclass(frozen=True)
+class RunResult:
+    result_text: str
+    num_turns: int = 0
+    cost_usd: float = 0.0
+    input_tokens: int = 0
+    cache_creation_tokens: int = 0
+    cache_read_tokens: int = 0
+    output_tokens: int = 0
+    duration_ms: int = 0
+    is_error: bool = False
+    models: tuple[str, ...] = ()
+
+    @property
+    def fresh_tokens(self) -> int:
+        """Tokens the model actually processed fresh (cache reads are near-free)."""
+        return self.input_tokens + self.cache_creation_tokens + self.output_tokens
+
+
+def parse_result(raw: str) -> RunResult:
+    try:
+        data = json.loads(raw)
+    except json.JSONDecodeError:
+        return RunResult(result_text=raw[-2000:], is_error=True)
+    if not isinstance(data, dict):
+        return RunResult(result_text=raw[-2000:], is_error=True)
+    usage = data.get("usage") or {}
+    model_usage = data.get("modelUsage")
+    return RunResult(
+        result_text=str(data.get("result") or ""),
+        num_turns=int(data.get("num_turns") or 0),
+        cost_usd=float(data.get("total_cost_usd") or 0.0),
+        input_tokens=int(usage.get("input_tokens") or 0),
+        cache_creation_tokens=int(usage.get("cache_creation_input_tokens") or 0),
+        cache_read_tokens=int(usage.get("cache_read_input_tokens") or 0),
+        output_tokens=int(usage.get("output_tokens") or 0),
+        duration_ms=int(data.get("duration_ms") or 0),
+        is_error=bool(data.get("is_error")),
+        models=tuple(sorted(model_usage)) if isinstance(model_usage, dict) else (),
+    )
+
+
+def claude_home() -> Path:
+    """Claude Code's config folder (the user's real one: benchmarks only clean up after runs)."""
+    override = os.environ.get("CLAUDE_CONFIG_DIR")
+    return Path(override) if override else Path.home() / ".claude"
+
+
+def project_slug(cwd: Path) -> str:
+    """How Claude Code names a working directory's folder under `projects/`."""
+    return re.sub(r"[^A-Za-z0-9]", "-", str(cwd))
+
+
+def forget_project(home: Path, cwd: Path) -> None:
+    """Remove the per-cwd folder a headless run leaves behind, if it holds no files."""
+    target = home / "projects" / project_slug(cwd)
+    if target.is_dir() and not any(p.is_file() for p in target.rglob("*")):
+        shutil.rmtree(target, ignore_errors=True)
+
+
+class Runner(Protocol):
+    def run(self, prompt: str, cwd: Path, ws: Path, mcp_config: Path | None) -> RunResult: ...
+
+
+@dataclass(frozen=True)
+class ClaudeRunner:
+    model: str = "haiku"
+    timeout: float = 900.0
+    home: Path | None = None  # Claude Code's config folder; default claude_home()
+
+    def isolation_settings(self, ws: Path) -> dict[str, object]:
+        """Keep the benchmarking user's own instructions out of every run.
+
+        `--setting-sources project,local` doesn't cover memory files: ~/.claude/CLAUDE.md
+        and ~/.claude/rules still load, as would a CLAUDE.md in any folder above the
+        temporary workspace. Only the condition's workspace CLAUDE.md may load.
+        """
+        home = (self.home or claude_home()).as_posix().rstrip("/")
+        above = [p.as_posix().rstrip("/") for p in ws.parents]
+        excludes = [f"{home}/**"]
+        excludes += [f"{d}/{name}" for d in above for name in ("CLAUDE.md", "CLAUDE.local.md")]
+        excludes += [f"{d}/.claude/**" for d in above]
+        return {"claudeMdExcludes": excludes, "autoMemoryEnabled": False}
+
+    def command(self, prompt: str, ws: Path, mcp_config: Path | None) -> list[str]:
+        # The resolved path, so npm's `claude.cmd` shim launches on Windows too.
+        cmd = [
+            shutil.which("claude") or "claude",
+            "-p",
+            prompt,
+            "--output-format",
+            "json",
+            "--model",
+            self.model,
+            "--setting-sources",
+            "project,local",
+            "--settings",
+            json.dumps(self.isolation_settings(ws)),
+            "--no-session-persistence",
+            "--permission-mode",
+            "dontAsk",
+            "--allowedTools",
+            *READ_ONLY_TOOLS,
+            "--add-dir",
+            str(ws),
+            "--strict-mcp-config",
+        ]
+        if mcp_config is not None:
+            cmd += ["--mcp-config", str(mcp_config)]
+        return cmd
+
+    def run(self, prompt: str, cwd: Path, ws: Path, mcp_config: Path | None) -> RunResult:
+        try:
+            proc = subprocess.run(
+                self.command(prompt, ws, mcp_config),
+                cwd=cwd,
+                capture_output=True,
+                text=True,
+                encoding="utf-8",
+                errors="replace",
+                timeout=self.timeout,
+                check=False,
+            )
+        except (OSError, subprocess.TimeoutExpired) as exc:
+            return RunResult(result_text=f"runner error: {exc}", is_error=True)
+        finally:
+            home = self.home or claude_home()
+            for path in {cwd, cwd.resolve()}:
+                forget_project(home, path)
+        return parse_result(proc.stdout or proc.stderr)
+
+    def version(self) -> str:
+        try:
+            done = subprocess.run(
+                [shutil.which("claude") or "claude", "--version"],
+                capture_output=True,
+                text=True,
+                encoding="utf-8",
+                errors="replace",
+                timeout=60,
+                check=False,
+            )
+        except (OSError, subprocess.TimeoutExpired):
+            return "unknown"
+        return done.stdout.strip() or "unknown"
+
+
+@dataclass(frozen=True)
+class FakeRunner:
+    """Test double: `reply(prompt, cwd)` returns the raw JSON claude would print."""
+
+    reply: Callable[[str, Path], str]
+
+    def run(self, prompt: str, cwd: Path, ws: Path, mcp_config: Path | None) -> RunResult:
+        return parse_result(self.reply(prompt, cwd))