subtask-mcp 0.2.3__py3-none-any.whl

subtask/install/clients.py

@@ -0,0 +1,355 @@
+"""Where each client keeps its MCP entry and skills, and how to read and change it."""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import shutil
+import subprocess
+import tomllib
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from . import tomledit
+from .fileops import atomic_write, read_bytes
+
+NAME = "subtask"
+CODEX_TOOL_TIMEOUT_SEC = 660
+KIMI_TOOL_TIMEOUT_MS = 660_000
+NATIVE_TIMEOUT_S = 60
+
+
+class InstallError(RuntimeError):
+    """A step failed; the message is safe to show."""
+
+
+@dataclass(frozen=True)
+class Step:
+    """One planned change: a native command (argv) or a file edit (description)."""
+
+    kind: str  # "run" | "edit" (set a key) | "unset" (remove a key)
+    target: str
+    argv: tuple[str, ...] = ()
+
+    def describe(self) -> str:
+        if self.kind == "run":
+            return "run: " + " ".join(_quote(a) for a in self.argv)
+        return f"{self.kind}: {self.target}"
+
+
+def _quote(arg: str) -> str:
+    import shlex
+
+    return shlex.quote(arg)
+
+
+def run_native(argv: list[str]) -> None:
+    try:
+        proc = subprocess.run(
+            argv,
+            stdin=subprocess.DEVNULL,
+            check=False,
+            capture_output=True,
+            text=True,
+            timeout=NATIVE_TIMEOUT_S,
+        )
+    except (OSError, subprocess.TimeoutExpired) as exc:
+        raise InstallError(f"{argv[0]} failed: {exc}") from exc
+    if proc.returncode != 0:
+        tail = (proc.stderr or proc.stdout).strip().splitlines()[-3:]
+        raise InstallError(f"{' '.join(argv[:3])} exited {proc.returncode}: {' | '.join(tail)}")
+
+
+def strip_jsonc(text: str) -> str:
+    """JSON with comments and trailing commas (OpenCode's opencode.jsonc) -> plain JSON text."""
+    out, i, n, in_str = [], 0, len(text), False
+    while i < n:
+        ch = text[i]
+        if in_str:
+            out.append(ch)
+            if ch == "\\":
+                out.append(text[i + 1 : i + 2])
+                i += 2
+                continue
+            if ch == '"':
+                in_str = False
+        elif ch == '"':
+            in_str = True
+            out.append(ch)
+        elif text.startswith("//", i):
+            while i < n and text[i] != "\n":
+                i += 1
+            continue
+        elif text.startswith("/*", i):
+            end = text.find("*/", i + 2)
+            i = n if end < 0 else end + 2
+            continue
+        else:
+            out.append(ch)
+        i += 1
+    return re.sub(r",(\s*[}\]])", r"\1", "".join(out))
+
+
+def _has_comments(raw: bytes) -> bool:
+    text = raw.decode("utf-8", errors="replace")
+    return strip_jsonc(text) != re.sub(r",(\s*[}\]])", r"\1", text)
+
+
+def _load_json(path: Path) -> dict[str, Any]:
+    raw = read_bytes(path)
+    if raw is None or not raw.strip():
+        return {}
+    try:
+        data = json.loads(strip_jsonc(raw.decode("utf-8")))
+    except (ValueError, UnicodeDecodeError) as exc:
+        raise InstallError(f"{path} is not plain JSON ({exc}); edit it by hand") from exc
+    if not isinstance(data, dict):
+        raise InstallError(f"{path}: top level is not an object")
+    return data
+
+
+def _dig(data: dict[str, Any], keys: tuple[str, ...]) -> Any:
+    for k in keys:
+        if not isinstance(data, dict):
+            return None
+        data = data.get(k)  # type: ignore[assignment]
+    return data
+
+
+def json_set(path: Path, keys: tuple[str, ...], value: Any | None) -> None:
+    """Set (or with None remove) one nested key; everything else is kept as parsed.
+
+    A file with comments is never rewritten (the comments would be lost): edit it by hand.
+    """
+    raw = read_bytes(path)
+    data = _load_json(path)
+    if value is None and _dig(data, keys) is None:
+        return  # nothing to remove: the file is not touched
+    if raw is not None and _has_comments(raw):
+        raise InstallError(
+            f"{path} has comments; rewriting it would drop them: change {'.'.join(keys)} by hand"
+        )
+    node = data
+    for k in keys[:-1]:
+        child = node.get(k)
+        if child is None:
+            if value is None:
+                return
+            child = {}
+        if not isinstance(child, dict):
+            raise InstallError(f"{path}: '{k}' is not an object")
+        node[k] = dict(child)
+        node = node[k]
+    if value is None:
+        node.pop(keys[-1], None)
+    else:
+        node[keys[-1]] = value
+    atomic_write(path, (json.dumps(data, indent=2) + "\n").encode())
+
+
+class Client:
+    name = ""
+    binary = ""
+    scopes: tuple[str, ...] = ("user", "project")
+
+    def __init__(self, cwd: Path | None = None) -> None:
+        self.cwd = cwd or Path.cwd()
+
+    # --- detection
+    def exe(self) -> str | None:
+        return shutil.which(self.binary)
+
+    def version(self) -> str | None:
+        exe = self.exe()
+        if not exe:
+            return None
+        try:
+            out = subprocess.run(
+                [exe, "--version"],
+                stdin=subprocess.DEVNULL,
+                check=False,
+                capture_output=True,
+                text=True,
+                timeout=20,
+            )
+        except (OSError, subprocess.TimeoutExpired):
+            return "unknown"
+        lines = (out.stdout or out.stderr).strip().splitlines()
+        return lines[0][:80] if lines else "unknown"
+
+    def check_scope(self, scope: str) -> None:
+        if scope not in self.scopes:
+            raise InstallError(f"{self.name} does not support --scope {scope}")
+
+    # --- per client
+    def config_path(self, scope: str) -> Path:
+        raise NotImplementedError
+
+    def read_entry(self, scope: str) -> dict[str, Any] | None:
+        raise NotImplementedError
+
+    def add_steps(self, scope: str, argv: list[str]) -> list[Step]:
+        raise NotImplementedError
+
+    def remove_steps(self, scope: str) -> list[Step]:
+        raise NotImplementedError
+
+    def apply(self, step: Step, scope: str, argv: list[str]) -> None:
+        if step.kind == "run":
+            run_native(list(step.argv))
+        else:
+            raise InstallError(f"unknown step {step.describe()}")
+
+    def skill_path(self, scope: str) -> Path:
+        raise NotImplementedError
+
+    @staticmethod
+    def target(entry: dict[str, Any] | None) -> list[str] | None:
+        """The launched argv of an entry, comparable across clients."""
+        if not entry:
+            return None
+        cmd = entry.get("command")
+        if isinstance(cmd, list):
+            return [str(c) for c in cmd]
+        return [str(cmd), *[str(a) for a in entry.get("args") or []]]
+
+
+class Claude(Client):
+    name = binary = "claude"
+
+    def config_path(self, scope: str) -> Path:
+        return Path.home() / ".claude.json" if scope == "user" else self.cwd / ".mcp.json"
+
+    def read_entry(self, scope: str) -> dict[str, Any] | None:
+        return _dig(_load_json(self.config_path(scope)), ("mcpServers", NAME))
+
+    def add_steps(self, scope: str, argv: list[str]) -> list[Step]:
+        cmd = (self.exe() or "claude", "mcp", "add", "-s", scope, NAME, "--", *argv)
+        return [Step("run", str(self.config_path(scope)), cmd)]
+
+    def remove_steps(self, scope: str) -> list[Step]:
+        cmd = (self.exe() or "claude", "mcp", "remove", "-s", scope, NAME)
+        return [Step("run", str(self.config_path(scope)), cmd)]
+
+    def skill_path(self, scope: str) -> Path:
+        base = Path.home() if scope == "user" else self.cwd
+        return base / ".claude" / "skills" / NAME / "SKILL.md"
+
+
+class Codex(Client):
+    name = binary = "codex"
+    scopes = ("user",)
+
+    def home(self) -> Path:
+        return Path(os.environ.get("CODEX_HOME") or Path.home() / ".codex")
+
+    def config_path(self, scope: str) -> Path:
+        return self.home() / "config.toml"
+
+    def read_entry(self, scope: str) -> dict[str, Any] | None:
+        raw = read_bytes(self.config_path(scope))
+        if not raw:
+            return None
+        try:
+            data = tomllib.loads(raw.decode())
+        except (ValueError, UnicodeDecodeError) as exc:
+            raise InstallError(f"{self.config_path(scope)} is not valid TOML: {exc}") from exc
+        return _dig(data, ("mcp_servers", NAME))
+
+    def add_steps(self, scope: str, argv: list[str]) -> list[Step]:
+        path = str(self.config_path(scope))
+        return [
+            Step("run", path, (self.exe() or "codex", "mcp", "add", NAME, "--", *argv)),
+            Step("edit", f"{path}: [mcp_servers.{NAME}] tool_timeout_sec = {CODEX_TOOL_TIMEOUT_SEC}"),
+        ]
+
+    def remove_steps(self, scope: str) -> list[Step]:
+        path = str(self.config_path(scope))
+        return [Step("run", path, (self.exe() or "codex", "mcp", "remove", NAME))]
+
+    def apply(self, step: Step, scope: str, argv: list[str]) -> None:
+        if step.kind != "edit":
+            return super().apply(step, scope, argv)
+        path = self.config_path(scope)
+        text = (read_bytes(path) or b"").decode()
+        try:
+            new = tomledit.set_key(
+                text, f"mcp_servers.{NAME}", "tool_timeout_sec", str(CODEX_TOOL_TIMEOUT_SEC)
+            )
+        except ValueError as exc:
+            raise InstallError(f"{path}: {exc}") from exc
+        atomic_write(path, new.encode())
+
+    def skill_path(self, scope: str) -> Path:
+        return Path.home() / ".agents" / "skills" / NAME / "SKILL.md"
+
+
+class Kimi(Client):
+    name = binary = "kimi"
+
+    def home(self) -> Path:
+        return Path(os.environ.get("KIMI_CODE_HOME") or Path.home() / ".kimi-code")
+
+    def config_path(self, scope: str) -> Path:
+        return self.home() / "mcp.json" if scope == "user" else self.cwd / ".kimi-code" / "mcp.json"
+
+    def read_entry(self, scope: str) -> dict[str, Any] | None:
+        return _dig(_load_json(self.config_path(scope)), ("mcpServers", NAME))
+
+    def add_steps(self, scope: str, argv: list[str]) -> list[Step]:
+        return [
+            Step("edit", f"{self.config_path(scope)}: mcpServers.{NAME} = {json.dumps(self.entry(argv))}")
+        ]
+
+    def remove_steps(self, scope: str) -> list[Step]:
+        return [Step("unset", f"{self.config_path(scope)}: mcpServers.{NAME}")]
+
+    @staticmethod
+    def entry(argv: list[str]) -> dict[str, Any]:
+        return {"command": argv[0], "args": argv[1:], "toolTimeoutMs": KIMI_TOOL_TIMEOUT_MS}
+
+    def apply(self, step: Step, scope: str, argv: list[str]) -> None:
+        value = None if step.kind == "unset" else self.entry(argv)
+        json_set(self.config_path(scope), ("mcpServers", NAME), value)
+
+    def skill_path(self, scope: str) -> Path:
+        base = self.home() if scope == "user" else self.cwd / ".kimi-code"
+        return base / "skills" / NAME / "SKILL.md"
+
+
+class OpenCode(Client):
+    name = binary = "opencode"
+
+    def config_path(self, scope: str) -> Path:
+        if scope == "project":
+            return self.cwd / "opencode.json"
+        base = Path(os.environ.get("XDG_CONFIG_HOME") or Path.home() / ".config") / "opencode"
+        if not (base / "opencode.json").exists() and (base / "opencode.jsonc").exists():
+            return base / "opencode.jsonc"  # what `opencode mcp add --global` writes by default
+        return base / "opencode.json"
+
+    def read_entry(self, scope: str) -> dict[str, Any] | None:
+        return _dig(_load_json(self.config_path(scope)), ("mcp", "servers", NAME))
+
+    def add_steps(self, scope: str, argv: list[str]) -> list[Step]:
+        flags = ("--global",) if scope == "user" else ()
+        cmd = (self.exe() or "opencode", "mcp", "add", NAME, *flags, "--", *argv)
+        return [Step("run", str(self.config_path(scope)), cmd)]
+
+    def remove_steps(self, scope: str) -> list[Step]:  # opencode has no `mcp remove`
+        return [Step("unset", f"{self.config_path(scope)}: mcp.servers.{NAME}")]
+
+    def apply(self, step: Step, scope: str, argv: list[str]) -> None:
+        if step.kind == "run":
+            return super().apply(step, scope, argv)
+        json_set(self.config_path(scope), ("mcp", "servers", NAME), None)
+
+    def skill_path(self, scope: str) -> Path:
+        if scope == "project":
+            return self.cwd / ".opencode" / "skills" / NAME / "SKILL.md"
+        return self.config_path("user").parent / "skills" / NAME / "SKILL.md"
+
+
+CLIENTS: dict[str, type[Client]] = {"claude": Claude, "codex": Codex, "kimi": Kimi, "opencode": OpenCode}

subtask/install/commands.py

@@ -0,0 +1,122 @@
+"""`subtask install | uninstall | doctor` argument parsing and output."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+from .clients import CLIENTS, Client, InstallError
+from .doctor import doctor
+from .installer import install, uninstall
+
+CHOICES = [*CLIENTS, "all"]
+
+
+def add_parsers(sub: argparse._SubParsersAction) -> None:
+    i = sub.add_parser(
+        "install", help="register the MCP server and skill in a client (plan only without --yes)"
+    )
+    u = sub.add_parser("uninstall", help="remove what `subtask install` added (plan only without --yes)")
+    d = sub.add_parser("doctor", help="check a client: app, config entry, server handshake")
+    for p in (i, u, d):
+        p.add_argument(
+            "--client", required=p is not d, choices=CHOICES, help="doctor without --client checks engines"
+        )
+        p.add_argument("--scope", default="user", choices=["user", "project"])
+        p.add_argument("--json", action="store_true", help="machine-readable output on stdout")
+    for p in (i, u):
+        p.add_argument(
+            "--yes", action="store_true", help="apply the plan (default: print it, change nothing)"
+        )
+        p.add_argument(
+            "--dry-run", action="store_true", help="print the plan only (the default without --yes)"
+        )
+    i.add_argument(
+        "--force", action="store_true", help="replace an existing 'subtask' entry that is not ours"
+    )
+    i.add_argument("--command", help="server command to register (default: subtask-mcp next to this python)")
+
+
+def server_command(override: str | None) -> list[str]:
+    if override:
+        return [override]
+    here = Path(sys.executable).parent / "subtask-mcp"
+    if here.is_file():
+        return [str(here.absolute())]
+    import shutil
+
+    found = shutil.which("subtask-mcp")
+    if not found:
+        raise InstallError("subtask-mcp not found next to this python nor on PATH; pass --command PATH")
+    return [str(Path(found).absolute())]
+
+
+def _selected(name: str) -> tuple[list[Client], list[str]]:
+    if name != "all":
+        return [CLIENTS[name]()], []
+    clients = [cls() for cls in CLIENTS.values()]
+    return [c for c in clients if c.exe()], [c.name for c in clients if not c.exe()]
+
+
+def run(a: argparse.Namespace) -> int:
+    clients, missing = _selected(a.client)
+    if a.cmd == "doctor":
+        reports = [doctor(c, a.scope) for c in clients]
+        ok = all(r.get("connects") for r in reports) and bool(reports)
+        _emit(a.json, {"action": "doctor", "clients": reports, "not_detected": missing}, _doctor_text)
+        return 0 if ok else 1
+    apply = a.yes and not a.dry_run
+    try:
+        argv = server_command(a.command) if a.cmd == "install" else []
+    except InstallError as exc:
+        _emit(a.json, {"action": a.cmd, "error": str(exc)}, lambda d: f"error: {d['error']}")
+        return 2
+    results = []
+    for c in clients:
+        if a.cmd == "install" and not c.exe():
+            results.append({"client": c.name, "scope": a.scope, "status": "skipped",
+                            "steps": [], "notes": [f"{c.binary} not found on PATH; install the app first"]})  # fmt: skip
+            continue
+        out = (
+            install(c, a.scope, argv, apply, a.force) if a.cmd == "install" else uninstall(c, a.scope, apply)
+        )
+        results.append(out.as_dict())
+    data = {"action": a.cmd, "applied": apply, "command": argv, "clients": results, "not_detected": missing}
+    _emit(a.json, data, _plan_text)
+    bad = any(r["status"] in ("error", "collision") for r in results)
+    return 1 if bad else 0
+
+
+def _emit(as_json: bool, data: dict[str, Any], render) -> None:
+    print(json.dumps(data, indent=2) if as_json else render(data))
+
+
+def _plan_text(d: dict[str, Any]) -> str:
+    lines = [] if d["applied"] else ["Plan only. Nothing changed. Run again with --yes to apply."]
+    if d.get("command"):
+        lines.append("server command: " + " ".join(d["command"]))
+    for r in d["clients"]:
+        lines.append(f"[{r['client']}] {r['status']}")
+        lines += [f"  {s}" for s in r["steps"]] + [f"  note: {n}" for n in r["notes"]]
+    if d["not_detected"]:
+        lines.append("not detected (skipped): " + ", ".join(d["not_detected"]))
+    return "\n".join(lines)
+
+
+def _doctor_text(d: dict[str, Any]) -> str:
+    lines = []
+    for r in d["clients"]:
+        hs = r.get("handshake") or {}
+        lines.append(f"[{r['client']}] app: {'yes ' + str(r['version']) if r['present'] else 'not found'}")
+        lines.append(f"  config: {r.get('config')}  configured: {'yes' if r.get('configured') else 'no'}")
+        if r.get("command"):
+            lines.append(f"  command: {' '.join(r['command'])}  exists: {r.get('command_exists')}")
+        conn = f"yes ({hs.get('tools')} tools, {hs.get('protocol')})" if r.get("connects") else \
+            f"no ({hs.get('error') or r.get('error') or 'not configured'})"  # fmt: skip
+        lines.append(f"  connects: {conn}  auth: {r.get('auth', 'not needed')}")
+    if d["not_detected"]:
+        lines.append("not detected: " + ", ".join(d["not_detected"]))
+    return "\n".join(lines)

subtask/install/doctor.py

@@ -0,0 +1,112 @@
+"""Client-side health check: app present, entry configured, server answers over stdio."""
+
+from __future__ import annotations
+
+import json
+import os
+import selectors
+import shutil
+import subprocess
+import time
+from pathlib import Path
+from typing import Any
+
+from .clients import Client, InstallError
+
+HANDSHAKE_TIMEOUT_S = 10.0
+PROTOCOL = "2025-06-18"
+
+
+def _read_reply(proc: subprocess.Popen[bytes], want_id: int, deadline: float) -> dict[str, Any]:
+    assert proc.stdout is not None
+    sel = selectors.DefaultSelector()
+    sel.register(proc.stdout, selectors.EVENT_READ)
+    buf = b""
+    while True:
+        left = deadline - time.monotonic()
+        if left <= 0:
+            raise TimeoutError("no reply within the time limit")
+        if not sel.select(left):
+            continue
+        chunk = os.read(proc.stdout.fileno(), 65536)
+        if not chunk:
+            raise ConnectionError(f"server exited (code {proc.poll()})")
+        buf += chunk
+        while b"\n" in buf:
+            line, buf = buf.split(b"\n", 1)
+            try:
+                msg = json.loads(line)
+            except ValueError:
+                continue
+            if isinstance(msg, dict) and msg.get("id") == want_id:
+                return msg
+
+
+def handshake(
+    argv: list[str],
+    env: dict[str, str] | None = None,
+    timeout: float = HANDSHAKE_TIMEOUT_S,
+    cwd: str | None = None,
+) -> dict:
+    """Spawn the server, send initialize + tools/list, return server name and tool count."""
+    deadline = time.monotonic() + timeout
+    full_env = {**os.environ, **(env or {})}
+    try:
+        proc = subprocess.Popen(argv, stdin=subprocess.PIPE, stdout=subprocess.PIPE,
+                                stderr=subprocess.DEVNULL, env=full_env, cwd=cwd)  # fmt: skip
+    except OSError as exc:
+        return {"ok": False, "error": f"cannot start: {exc}"}
+    assert proc.stdin is not None
+    try:
+        init = {"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {
+            "protocolVersion": PROTOCOL, "capabilities": {},
+            "clientInfo": {"name": "subtask-doctor", "version": "1"}}}  # fmt: skip
+        proc.stdin.write((json.dumps(init) + "\n").encode())
+        proc.stdin.flush()
+        r1 = _read_reply(proc, 1, deadline)
+        if "error" in r1:
+            return {"ok": False, "error": f"initialize: {r1['error'].get('message')}"}
+        notes = {"jsonrpc": "2.0", "method": "notifications/initialized"}
+        listing = {"jsonrpc": "2.0", "id": 2, "method": "tools/list", "params": {}}
+        proc.stdin.write((json.dumps(notes) + "\n" + json.dumps(listing) + "\n").encode())
+        proc.stdin.flush()
+        r2 = _read_reply(proc, 2, deadline)
+        tools = (r2.get("result") or {}).get("tools") or []
+        info = (r1.get("result") or {}).get("serverInfo") or {}
+        return {"ok": bool(tools), "server": info.get("name"), "version": info.get("version"),
+                "protocol": (r1.get("result") or {}).get("protocolVersion"), "tools": len(tools)}  # fmt: skip
+    except (TimeoutError, ConnectionError, OSError) as exc:
+        return {"ok": False, "error": str(exc)}
+    finally:
+        try:
+            proc.stdin.close()
+        except OSError:
+            pass  # the server already died: nothing to flush
+        try:
+            proc.wait(timeout=3)
+        except subprocess.TimeoutExpired:
+            proc.kill()
+            proc.wait()
+
+
+def doctor(c: Client, scope: str) -> dict[str, Any]:
+    exe = c.exe()
+    report: dict[str, Any] = {"client": c.name, "scope": scope, "present": bool(exe), "binary": exe,
+                              "version": c.version() if exe else None}  # fmt: skip
+    try:
+        c.check_scope(scope)
+        path = c.config_path(scope)
+        entry = c.read_entry(scope)
+    except InstallError as exc:
+        return {**report, "configured": False, "connects": False, "error": str(exc)}
+    argv = Client.target(entry)
+    report |= {"config": str(path), "configured": bool(argv), "command": argv}
+    if not argv:
+        return {**report, "connects": False, "auth": "not needed"}
+    launcher = argv[0] if os.path.isabs(argv[0]) else shutil.which(argv[0])
+    report["command_exists"] = bool(launcher and Path(launcher).is_file() and os.access(launcher, os.X_OK))
+    env = (entry or {}).get("env") or {}
+    hs = handshake(argv, {str(k): str(v) for k, v in env.items()}) if report["command_exists"] else {
+        "ok": False, "error": "command not found or not executable"}  # fmt: skip
+    # The subtask server needs no credentials to connect; engines read theirs only when a job runs.
+    return {**report, "connects": hs.pop("ok"), "handshake": hs, "auth": "not needed"}

subtask/install/fileops.py

@@ -0,0 +1,69 @@
+"""Safe file edits: backup, atomic write that keeps the mode, restore."""
+
+from __future__ import annotations
+
+import hashlib
+import os
+import tempfile
+import time
+from dataclasses import dataclass
+from pathlib import Path
+
+
+def sha256(data: bytes) -> str:
+    return hashlib.sha256(data).hexdigest()
+
+
+def read_bytes(path: Path) -> bytes | None:
+    try:
+        return path.read_bytes()
+    except FileNotFoundError:
+        return None
+
+
+def atomic_write(path: Path, data: bytes) -> None:
+    """Write via a temp file in the same dir, then os.replace; keep the old mode."""
+    path.parent.mkdir(parents=True, exist_ok=True)
+    try:
+        mode: int | None = path.stat().st_mode & 0o7777
+    except FileNotFoundError:
+        mode = None
+    fd, tmp = tempfile.mkstemp(prefix=f".{path.name}.", suffix=".tmp", dir=path.parent)
+    try:
+        with os.fdopen(fd, "wb") as fh:
+            fh.write(data)
+            fh.flush()
+            os.fsync(fh.fileno())
+        if mode is not None:
+            os.chmod(tmp, mode)
+        os.replace(tmp, path)
+    except BaseException:
+        Path(tmp).unlink(missing_ok=True)
+        raise
+
+
+@dataclass(frozen=True)
+class Snapshot:
+    """What a file held before we touched it; `backup` is the copy on disk, if any."""
+
+    path: Path
+    before: bytes | None
+    backup: Path | None
+
+    def restore(self) -> None:
+        if self.before is None:
+            self.path.unlink(missing_ok=True)
+        else:
+            atomic_write(self.path, self.before)
+
+
+def snapshot(path: Path, keep_copy: bool = True) -> Snapshot:
+    """Remember the file; with keep_copy leave a `<file>.subtask-bak-<timestamp>` copy next to it."""
+    before = read_bytes(path)
+    backup = None
+    if before is not None and keep_copy:
+        stamp = time.strftime("%Y%m%d-%H%M%S") + f"-{time.time_ns() % 1_000_000:06d}"
+        backup = path.with_name(f"{path.name}.subtask-bak-{stamp}")
+        atomic_write(backup, before)
+        os.chmod(backup, path.stat().st_mode & 0o7777)
+    return Snapshot(path, before, backup)