pytest-live-pause 0.1.0__py3-none-any.whl

pytest_live_pause/__init__.py

@@ -0,0 +1,3 @@
+from .plugin import checkpoint
+
+__all__ = ["checkpoint"]

pytest_live_pause/cli.py

@@ -0,0 +1,234 @@
+from __future__ import annotations
+
+import argparse
+import sys
+import time
+from pathlib import Path
+
+from .runtime import (
+    default_pause_dir,
+    effective_pause_status,
+    is_local_process_alive,
+    list_pauses,
+    parse_result_token,
+    pause_created_at,
+    read_json_file,
+    write_json_file,
+)
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="pytest-live-pause")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    ls = subparsers.add_parser("ls")
+    ls.add_argument("--pause-dir", default=str(default_pause_dir()))
+    ls.add_argument("-a", "--all", action="store_true", dest="include_finished")
+
+    watch = subparsers.add_parser("watch")
+    watch.add_argument("--pause-dir", default=str(default_pause_dir()))
+    watch.add_argument("--run-id", required=True)
+    watch.add_argument("-a", "--all", action="store_true", dest="include_finished")
+    watch.add_argument("--interval", type=float, default=0.2)
+    watch.add_argument("--timeout", type=float, default=None)
+
+    resume = subparsers.add_parser("resume")
+    resume.add_argument("target", help="Pause request file path or pause_id.")
+    resume.add_argument("--pause-dir", default=str(default_pause_dir()))
+    resume.add_argument("--failure-reason", default=None)
+    resume.add_argument("--result", choices=["true", "false", "none"], default=None)
+    resume.add_argument("--reason", default=None)
+
+    args = parser.parse_args(argv)
+    if args.command == "ls":
+        return _ls(Path(args.pause_dir), args.include_finished)
+    if args.command == "watch":
+        return _watch(Path(args.pause_dir), args.run_id, args.include_finished, args.interval, args.timeout)
+    if args.command == "resume":
+        return _resume(args.target, Path(args.pause_dir), args.failure_reason, args.result, args.reason)
+    parser.error(f"unknown command: {args.command}")
+    return 2
+
+
+def _resume(target: str, root_dir: Path, failure_reason: str | None, result_token: str | None, reason: str | None) -> int:
+    pause_path = _resolve_pause_target(target, root_dir)
+    if pause_path is None:
+        print(f"pause target not found: {target}", file=sys.stderr)
+        return 1
+
+    pause_payload = read_json_file(pause_path)
+    pause_status = effective_pause_status(pause_payload)
+    if pause_status == "stale":
+        print(f"pause belongs to a dead process and is stale: {pause_path}", file=sys.stderr)
+        return 1
+    if pause_status != "pending":
+        print(f"pause is no longer pending: {pause_path}", file=sys.stderr)
+        return 1
+    validation_error = _validate_resume_args(pause_payload, failure_reason, result_token, reason)
+    if validation_error is not None:
+        print(validation_error, file=sys.stderr)
+        return 1
+
+    commands_dir = pause_path.parent.parent / "commands"
+    command_path = commands_dir / f"{pause_path.stem}.resume.json"
+    if command_path.exists():
+        print(f"resume command already exists: {command_path}", file=sys.stderr)
+        return 1
+    commands_dir.mkdir(parents=True, exist_ok=True)
+    payload: dict[str, object] = {}
+    if failure_reason is not None:
+        payload["failure_reason"] = failure_reason
+    if result_token is not None:
+        payload["result"] = parse_result_token(result_token)
+    if reason is not None:
+        payload["reason"] = reason
+    write_json_file(command_path, payload)
+    print(f"resume command accepted for {pause_path.stem}")
+    return 0
+
+
+def _validate_resume_args(
+    pause_payload: dict[str, object],
+    failure_reason: str | None,
+    result_token: str | None,
+    reason: str | None,
+) -> str | None:
+    pause_kind = pause_payload.get("kind")
+    if pause_kind == "failure":
+        if result_token is not None or reason is not None:
+            return "--result/--reason are only allowed for checkpoint pauses; got kind=failure"
+        return None
+    if pause_kind == "checkpoint":
+        if failure_reason is not None:
+            return "--failure-reason is only allowed for failure pauses; got kind=checkpoint"
+        return None
+    if failure_reason is not None or result_token is not None or reason is not None:
+        kind_text = str(pause_kind) if pause_kind is not None else "unknown"
+        return f"unsupported pause kind for supplied arguments: {kind_text}"
+    return None
+
+
+def _resolve_pause_target(target: str, root_dir: Path) -> Path | None:
+    direct_path = Path(target)
+    if direct_path.exists():
+        return direct_path
+
+    matches: list[Path] = []
+    for pause in list_pauses(root_dir, include_finished=True):
+        if pause.get("pause_id") != target:
+            continue
+        pause_file = pause.get("pause_file")
+        if isinstance(pause_file, str):
+            matches.append(Path(pause_file))
+    if not matches:
+        return None
+    if len(matches) > 1:
+        print(f"multiple pauses matched id {target}; use the full pause file path", file=sys.stderr)
+        return None
+    return matches[0]
+
+
+def _ls(root_dir: Path, include_finished: bool) -> int:
+    pauses = list_pauses(root_dir, include_finished=include_finished)
+    if not pauses:
+        return 0
+
+    for pause in pauses:
+        print(_format_pause_line(pause))
+    return 0
+
+
+def _watch(root_dir: Path, run_id: str, include_finished: bool, interval: float, timeout: float | None) -> int:
+    run_check = _check_run_watchable(root_dir, run_id)
+    if run_check is not None:
+        print(run_check, file=sys.stderr)
+        return 1
+
+    deadline = None if timeout is None else time.monotonic() + timeout
+
+    while True:
+        pauses = list_pauses(root_dir, include_finished=include_finished, run_id=run_id)
+        latest_pause = _select_latest_pause(pauses)
+        if latest_pause is not None:
+            print(_format_watch_details(latest_pause))
+            return 0
+
+        if deadline is not None and time.monotonic() >= deadline:
+            return 0
+        time.sleep(interval)
+
+
+def _select_latest_pause(pauses: list[dict[str, object]]) -> dict[str, object] | None:
+    if not pauses:
+        return None
+    return max(pauses, key=pause_created_at)
+
+
+def _check_run_watchable(root_dir: Path, run_id: str) -> str | None:
+    run_file = root_dir / "runs" / run_id / "run.json"
+    if not run_file.exists():
+        return f"run not found: {run_id}"
+
+    run_payload = read_json_file(run_file)
+
+    pid = run_payload.get("pid")
+    hostname = run_payload.get("hostname") if isinstance(run_payload.get("hostname"), str) else None
+    if not isinstance(pid, int) or not is_local_process_alive(pid, hostname):
+        return f"run is no longer active: {run_id}"
+    return None
+
+
+def _format_watch_details(pause: dict[str, object]) -> str:
+    pause_id = str(pause.get("pause_id", ""))
+    kind = str(pause.get("kind", "unknown"))
+    nodeid = str(pause.get("nodeid", ""))
+    task = _task_for_pause(pause)
+    lines = [
+        f"pause detected: {pause_id}",
+        f"kind: {kind}",
+        f"nodeid: {nodeid}",
+        f"task: {task}",
+    ]
+    failure_details = _failure_details(pause)
+    if failure_details is not None:
+        lines.append("failure:")
+        lines.extend(f"  {line}" for line in failure_details)
+    return "\n".join(lines)
+
+
+def _task_for_pause(pause: dict[str, object]) -> str:
+    task = pause.get("task")
+    if isinstance(task, str) and task.strip():
+        return task
+    if pause.get("kind") == "failure":
+        return "Inspect the failure and then resume the test."
+    return "Complete the pending task and then resume the paused test."
+
+
+def _failure_details(pause: dict[str, object]) -> list[str] | None:
+    original_failure = pause.get("original_failure")
+    if not isinstance(original_failure, str) or not original_failure.strip():
+        return None
+
+    lines = [line.rstrip() for line in original_failure.strip().splitlines() if line.strip()]
+    if not lines:
+        return None
+    return lines
+
+
+def _format_pause_line(pause: dict[str, object]) -> str:
+    worker_id = pause.get("worker_id") or "-"
+    return "\t".join(
+        [
+            str(pause.get("status", "unknown")),
+            str(pause.get("pause_id", "")),
+            str(pause.get("nodeid", "")),
+            f"pid={pause.get('pid', '')}",
+            f"worker={worker_id}",
+            str(pause.get("pause_file", "")),
+        ]
+    )
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

pytest_live_pause/plugin.py

@@ -0,0 +1,175 @@
+from __future__ import annotations
+
+from contextvars import ContextVar
+from dataclasses import dataclass
+from pathlib import Path
+
+import pytest
+
+from .runtime import PauseManager, ResumeDecision, default_pause_dir, parse_result_token
+
+_MANAGER_KEY = object()
+_RUN_ID_ANNOUNCED_KEY = object()
+_ACTIVE_ITEM: ContextVar[pytest.Item | None] = ContextVar("pytest_live_pause_active_item", default=None)
+
+
+@dataclass(slots=True)
+class LivePause:
+    manager: PauseManager
+    item: pytest.Item
+
+    @property
+    def run_id(self) -> str:
+        return self.manager.run_id
+
+    def checkpoint(self, *, task: str, timeout: float | None = None) -> ResumeDecision:
+        return _checkpoint_for_item(self.item, task=task, timeout=timeout)
+
+
+def pytest_addoption(parser: pytest.Parser) -> None:
+    group = parser.getgroup("live-pause")
+    group.addoption(
+        "--pause-on-failure",
+        action="store_true",
+        default=False,
+        help="Pause failed tests before teardown and wait for an external resume command.",
+    )
+    group.addoption(
+        "--pause-dir",
+        action="store",
+        default=str(default_pause_dir()),
+        help="Directory used for live pause state and resume commands.",
+    )
+    group.addoption(
+        "--pause-timeout",
+        action="store",
+        type=float,
+        default=300.0,
+        help="Maximum number of seconds to wait before resuming automatically. Default is 300 seconds (5 minutes).",
+    )
+    group.addoption(
+        "--pause-checkpoint-mock",
+        action="store",
+        choices=["true", "false", "none"],
+        default=None,
+        help="Mock checkpoint result and skip creating an external pause.",
+    )
+
+
+def pytest_configure(config: pytest.Config) -> None:
+    config.stash[_MANAGER_KEY] = _create_manager(config)
+    config.stash[_RUN_ID_ANNOUNCED_KEY] = False
+
+
+def pytest_report_header(config: pytest.Config) -> list[str] | None:
+    manager = config.stash[_MANAGER_KEY]
+    config.stash[_RUN_ID_ANNOUNCED_KEY] = True
+    return [
+        f"pytest-live-pause: run_id={manager.run_id}",
+    ]
+
+
+def checkpoint(*, task: str, timeout: float | None = None):
+    if not task.strip():
+        raise ValueError("checkpoint task must not be empty")
+
+    item = _ACTIVE_ITEM.get()
+    if item is None:
+        raise RuntimeError("checkpoint can only be used while a pytest test is running")
+
+    return _checkpoint_for_item(item, task=task, timeout=timeout)
+
+
+@pytest.fixture
+def live_pause(request: pytest.FixtureRequest) -> LivePause:
+    item = request.node
+    assert isinstance(item, pytest.Item)
+    manager = _get_or_create_manager(item.config)
+    return LivePause(manager=manager, item=item)
+
+
+@pytest.fixture
+def pause_run_id(live_pause: LivePause) -> str:
+    return live_pause.run_id
+
+
+@pytest.hookimpl(hookwrapper=True)
+def pytest_runtest_protocol(item: pytest.Item, nextitem: pytest.Item | None) -> object:
+    token = _ACTIVE_ITEM.set(item)
+    try:
+        yield
+    finally:
+        _ACTIVE_ITEM.reset(token)
+
+
+@pytest.hookimpl(hookwrapper=True)
+def pytest_runtest_makereport(item: pytest.Item, call: pytest.CallInfo[None]) -> object:
+    outcome = yield
+    report = outcome.get_result()
+
+    if report.when != "call" or not report.failed:
+        return
+    if not item.config.getoption("pause_on_failure"):
+        return
+
+    manager = _get_or_create_manager(item.config)
+    decision = manager.pause_on_failure(
+        nodeid=item.nodeid,
+        original_failure=report.longreprtext,
+        timeout=item.config.getoption("pause_timeout"),
+    )
+    if decision.failure_reason:
+        report.sections.append(("live pause", f"External failure reason: {decision.failure_reason}"))
+
+
+def _create_manager(config: pytest.Config) -> PauseManager:
+    root_dir = Path(config.getoption("pause_dir"))
+    timeout = config.getoption("pause_timeout")
+    return PauseManager(root_dir=root_dir, default_timeout=timeout)
+
+
+def _get_or_create_manager(config: pytest.Config) -> PauseManager:
+    try:
+        manager = config.stash[_MANAGER_KEY]
+    except KeyError:
+        manager = _create_manager(config)
+        config.stash[_MANAGER_KEY] = manager
+        config.stash[_RUN_ID_ANNOUNCED_KEY] = False
+        _announce_run_id(config, manager)
+        return manager
+    return manager
+
+
+def _announce_run_id(config: pytest.Config, manager: PauseManager) -> None:
+    try:
+        announced = config.stash[_RUN_ID_ANNOUNCED_KEY]
+    except KeyError:
+        announced = False
+    if announced:
+        return
+
+    terminal = config.pluginmanager.get_plugin("terminalreporter")
+    if terminal is not None:
+        terminal.write_line(f"pytest-live-pause: run_id={manager.run_id}")
+    config.stash[_RUN_ID_ANNOUNCED_KEY] = True
+
+
+def _checkpoint_for_item(item: pytest.Item, *, task: str, timeout: float | None) -> ResumeDecision:
+    mock_decision = _mock_checkpoint_decision(item.config)
+    if mock_decision is not None:
+        return mock_decision
+
+    manager = _get_or_create_manager(item.config)
+    return manager.pause_checkpoint(nodeid=item.nodeid, task=task, timeout=timeout)
+
+
+def _mock_checkpoint_decision(config: pytest.Config) -> ResumeDecision | None:
+    result_token = config.getoption("pause_checkpoint_mock")
+    if result_token is None:
+        return None
+
+    return ResumeDecision(
+        outcome="resumed",
+        result=parse_result_token(result_token),
+        reason="Mock",
+    )

pytest_live_pause/runtime.py

@@ -0,0 +1,288 @@
+from __future__ import annotations
+
+import json
+import os
+import socket
+import sys
+import tempfile
+import time
+import uuid
+from dataclasses import dataclass, asdict
+from pathlib import Path
+from typing import Literal
+
+
+def default_pause_dir() -> Path:
+    return Path(tempfile.gettempdir()) / "pytest-live-pause"
+
+
+def is_local_process_alive(pid: int, hostname: str | None) -> bool:
+    if pid <= 0:
+        return False
+    if hostname and hostname != socket.gethostname():
+        return False
+
+    try:
+        os.kill(pid, 0)
+    except ProcessLookupError:
+        return False
+    except PermissionError:
+        return True
+    return True
+
+
+def is_pause_stale(payload: dict[str, object]) -> bool:
+    if payload.get("status") != "pending":
+        return False
+
+    hostname = payload.get("hostname")
+    pid = payload.get("pid")
+    if not isinstance(pid, int) or pid <= 0:
+        return False
+    return not is_local_process_alive(pid, hostname if isinstance(hostname, str) else None)
+
+
+def effective_pause_status(payload: dict[str, object]) -> str:
+    if is_pause_stale(payload):
+        return "stale"
+    status = payload.get("status")
+    return str(status) if status is not None else "unknown"
+
+
+def parse_result_token(result_token: str) -> bool | None:
+    if result_token == "true":
+        return True
+    if result_token == "false":
+        return False
+    return None
+
+
+def pause_created_at(payload: dict[str, object]) -> float:
+    created_at = payload.get("created_at")
+    if isinstance(created_at, int | float):
+        return float(created_at)
+    return 0.0
+
+
+def read_json_file(path: Path) -> dict[str, object]:
+    with path.open("r", encoding="utf-8") as handle:
+        return json.load(handle)
+
+
+def write_json_file(path: Path, payload: dict[str, object]) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    temp_path = path.with_suffix(path.suffix + ".tmp")
+    with temp_path.open("w", encoding="utf-8") as handle:
+        json.dump(payload, handle, ensure_ascii=True, indent=2)
+    temp_path.replace(path)
+
+
+@dataclass(slots=True)
+class ResumeDecision:
+    outcome: Literal["resumed", "timed_out"]
+    failure_reason: str | None = None
+    result: bool | None = None
+    reason: str | None = None
+
+
+@dataclass(slots=True)
+class PauseRequest:
+    pause_id: str
+    run_id: str
+    kind: Literal["failure", "checkpoint"]
+    nodeid: str
+    task: str | None
+    timeout: float
+    original_failure: str
+    status: Literal["pending", "resumed", "timed_out"]
+    created_at: float
+    pid: int
+    hostname: str
+    cwd: str
+    worker_id: str | None = None
+    finished_at: float | None = None
+    failure_reason: str | None = None
+
+
+@dataclass(slots=True)
+class RunMetadata:
+    run_id: str
+    pid: int
+    hostname: str
+    cwd: str
+    argv: list[str]
+    started_at: float
+    worker_id: str | None = None
+
+
+class PauseManager:
+    def __init__(self, root_dir: Path, default_timeout: float) -> None:
+        self.root_dir = root_dir
+        self.default_timeout = default_timeout
+        self.run_id = uuid.uuid4().hex
+        self.run_dir = self.root_dir / "runs" / self.run_id
+        self.pauses_dir = self.run_dir / "pauses"
+        self.commands_dir = self.run_dir / "commands"
+        self.events_file = self.run_dir / "events.jsonl"
+        self.run_file = self.run_dir / "run.json"
+        self.worker_id = os.environ.get("PYTEST_XDIST_WORKER")
+        self.pauses_dir.mkdir(parents=True, exist_ok=True)
+        self.commands_dir.mkdir(parents=True, exist_ok=True)
+        metadata = RunMetadata(
+            run_id=self.run_id,
+            pid=os.getpid(),
+            hostname=socket.gethostname(),
+            cwd=os.getcwd(),
+            argv=sys.argv.copy(),
+            started_at=time.time(),
+            worker_id=self.worker_id,
+        )
+        write_json_file(self.run_file, asdict(metadata))
+        self._emit(
+            {
+                "event": "run_started",
+                "run_id": self.run_id,
+                "pid": metadata.pid,
+                "worker_id": metadata.worker_id,
+            }
+        )
+
+    def pause_on_failure(self, nodeid: str, original_failure: str, timeout: float | None) -> ResumeDecision:
+        request = self._build_request(
+            kind="failure",
+            nodeid=nodeid,
+            task="Inspect the failure and then resume the test.",
+            timeout=timeout,
+            original_failure=original_failure,
+        )
+        return self._pause(request)
+
+    def pause_checkpoint(self, nodeid: str, task: str, timeout: float | None) -> ResumeDecision:
+        request = self._build_request(
+            kind="checkpoint",
+            nodeid=nodeid,
+            task=task,
+            timeout=timeout,
+            original_failure="",
+        )
+        return self._pause(request)
+
+    def _build_request(
+        self,
+        kind: Literal["failure", "checkpoint"],
+        nodeid: str,
+        task: str | None,
+        timeout: float | None,
+        original_failure: str,
+    ) -> PauseRequest:
+        return PauseRequest(
+            pause_id=uuid.uuid4().hex,
+            run_id=self.run_id,
+            kind=kind,
+            nodeid=nodeid,
+            task=task,
+            timeout=timeout if timeout is not None else self.default_timeout,
+            original_failure=original_failure,
+            status="pending",
+            created_at=time.time(),
+            pid=os.getpid(),
+            hostname=socket.gethostname(),
+            cwd=os.getcwd(),
+            worker_id=self.worker_id,
+        )
+
+    def _pause(self, request: PauseRequest) -> ResumeDecision:
+        pause_path = self.pauses_dir / f"{request.pause_id}.json"
+        write_json_file(pause_path, asdict(request))
+        self._emit(
+            {
+                "event": "pause_created",
+                "kind": request.kind,
+                "pause_id": request.pause_id,
+                "nodeid": request.nodeid,
+                "timeout": request.timeout,
+                "pid": request.pid,
+                "worker_id": request.worker_id,
+            }
+        )
+        decision = self._wait_for_resume(request)
+        write_json_file(
+            pause_path,
+            {
+                **asdict(request),
+                "status": "resumed" if decision.outcome == "resumed" else "timed_out",
+                "finished_at": time.time(),
+                "failure_reason": decision.failure_reason,
+                "result": decision.result,
+                "reason": decision.reason,
+            },
+        )
+        self._emit(
+            {
+                "event": "pause_finished",
+                "pause_id": request.pause_id,
+                "outcome": decision.outcome,
+                "failure_reason": decision.failure_reason,
+                "result": decision.result,
+                "reason": decision.reason,
+            }
+        )
+        return decision
+
+    def _wait_for_resume(self, request: PauseRequest) -> ResumeDecision:
+        deadline = time.monotonic() + request.timeout
+        command_file = self.commands_dir / f"{request.pause_id}.resume.json"
+
+        while time.monotonic() < deadline:
+            if command_file.exists():
+                payload = read_json_file(command_file)
+                try:
+                    command_file.unlink()
+                except FileNotFoundError:
+                    pass
+                failure_reason = payload.get("failure_reason")
+                result = payload.get("result")
+                reason = payload.get("reason")
+                return ResumeDecision(
+                    outcome="resumed",
+                    failure_reason=failure_reason if isinstance(failure_reason, str) else None,
+                    result=result if isinstance(result, bool) or result is None else None,
+                    reason=reason if isinstance(reason, str) else None,
+                )
+            time.sleep(0.1)
+
+        return ResumeDecision(outcome="timed_out")
+
+    def _emit(self, payload: dict[str, object]) -> None:
+        payload = {
+            "ts": time.time(),
+            **payload,
+        }
+        self.events_file.parent.mkdir(parents=True, exist_ok=True)
+        with self.events_file.open("a", encoding="utf-8") as handle:
+            handle.write(json.dumps(payload, ensure_ascii=True) + os.linesep)
+
+
+def list_pauses(root_dir: Path, include_finished: bool = False, run_id: str | None = None) -> list[dict[str, object]]:
+    pause_files = sorted(_iter_pause_files(root_dir, run_id))
+    items: list[dict[str, object]] = []
+    for pause_file in pause_files:
+        payload = read_json_file(pause_file)
+        if run_id is not None and payload.get("run_id") != run_id:
+            continue
+        status = effective_pause_status(payload)
+        if not include_finished and status != "pending":
+            continue
+        payload["recorded_status"] = payload.get("status")
+        payload["status"] = status
+        payload["pause_file"] = str(pause_file)
+        items.append(payload)
+    items.sort(key=lambda item: (str(item.get("status")), pause_created_at(item)))
+    return items
+
+
+def _iter_pause_files(root_dir: Path, run_id: str | None) -> list[Path]:
+    runs_dir = root_dir / "runs"
+    if run_id is not None:
+        return list((runs_dir / run_id / "pauses").glob("*.json"))
+    return list(runs_dir.glob("*/pauses/*.json"))

pytest_live_pause-0.1.0.dist-info/METADATA

@@ -0,0 +1,204 @@
+Metadata-Version: 2.4
+Name: pytest-live-pause
+Version: 0.1.0
+Summary: Pytest plugin and protocol for pausing live test execution and resuming in-process
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: pytest>=9.0.3
+Description-Content-Type: text/markdown
+
+## pytest-live-pause
+
+`pytest-live-pause` is intended to be a standalone pytest plugin and runtime protocol for pausing a live test process, inspecting state before teardown, and resuming the same process through a structured control channel.
+
+The repository is currently in bootstrap stage. The design target is:
+
+- a transport-neutral pause runtime
+- a thin pytest plugin adapter
+- structured stdout and JSONL events
+- packaged CLI commands for monitoring and resuming paused runs
+- a compatibility layer for existing QAMule-style workflows
+
+The current design scope lives in `CURRENT_SCOPE.md`.
+
+## Current Status
+
+The first working slice is `--pause-on-failure` using a file-backed control channel.
+
+Checkpoint pauses are also supported through `pytest_live_pause.checkpoint(...)`.
+
+The plugin also auto-registers `live_pause` and `pause_run_id` fixtures for direct injection into test function arguments.
+
+When a test fails in the `call` phase and `--pause-on-failure` is enabled, the plugin:
+
+- writes a pause request JSON file
+- waits for an external resume command file or timeout
+- resumes the same pytest process before teardown starts
+- appends any externally supplied failure reason to the pytest report
+
+Tests can also pause explicitly:
+
+```python
+from pytest_live_pause import checkpoint
+
+
+def test_example():
+	decision = checkpoint(task="Approve the external step", timeout=300)
+	if decision.result is False:
+		raise AssertionError(decision.reason or "checkpoint failed")
+```
+
+	Or through the auto-registered fixture:
+
+	```python
+	def test_example(live_pause, pause_run_id):
+		assert live_pause.run_id == pause_run_id
+		decision = live_pause.checkpoint(task="Approve the external step", timeout=300)
+		assert decision.result is True
+	```
+
+Checkpoint resumes use `--result` and `--reason`:
+
+```bash
+pytest-live-pause resume <pause_id> --result true --reason "approved"
+```
+
+Checkpoint behavior can also be mocked during pytest startup:
+
+```bash
+pytest --pause-checkpoint-mock false
+```
+
+## Usage
+
+Run pytest with pause-on-failure enabled:
+
+```bash
+pytest --pause-on-failure --pause-timeout 300
+```
+
+By default, pause state is written under `/tmp/pytest-live-pause`.
+
+You can still override it explicitly:
+
+```bash
+pytest --pause-on-failure --pause-dir /some/other/path --pause-timeout 300
+```
+
+When a test fails, a pause file appears under the run directory:
+
+```text
+
+/tmp/pytest-live-pause/
+	runs/<run_id>/
+		events.jsonl
+		run.json
+		pauses/<pause_id>.json
+		commands/
+```
+
+Resume the paused failure by pointing the CLI at the pause file:
+
+```bash
+pytest-live-pause resume \
+	/tmp/pytest-live-pause/runs/<run_id>/pauses/<pause_id>.json \
+	--failure-reason "manually confirmed"
+```
+
+You can also resume directly by `pause_id`, which is more convenient when multiple pytest processes share the same pause directory:
+
+```bash
+pytest-live-pause resume <pause_id> --failure-reason "manually confirmed"
+```
+
+If you are using a non-default pause directory, pass it explicitly:
+
+```bash
+pytest-live-pause resume <pause_id> --pause-dir /some/other/path --failure-reason "manually confirmed"
+```
+
+For failure pauses, `--failure-reason` appends an extra explanation to the pytest failure report. Non-failure pauses must not receive `--failure-reason`; the CLI will reject that combination.
+
+For checkpoint pauses, use `--result true|false|none` and optional `--reason`.
+
+For mocked checkpoint pauses, `reason` is fixed to `Mock`.
+
+The CLI writes the matching command file into `commands/`. The pytest process polls for that command and then continues into teardown.
+
+When multiple pytest processes share the same pause directory, each process gets its own `runs/<run_id>/` directory. `run.json` and each pause file also record `pid`, `hostname`, `cwd`, and optional `worker_id` metadata.
+
+You can inspect currently pending pauses across all runs with:
+
+```bash
+pytest-live-pause ls
+```
+
+You can also watch for newly paused tests in real time:
+
+```bash
+pytest-live-pause watch --run-id <run_id>
+```
+
+`watch` requires a specific pytest `run_id`:
+
+```bash
+pytest-live-pause watch --run-id <run_id>
+```
+
+For bounded monitoring, pass a timeout:
+
+```bash
+pytest-live-pause watch --run-id <run_id> --timeout 30
+```
+
+`watch` waits until the latest matching pending pause appears, prints the pause details, and then exits.
+
+By default, `ls` only shows currently resumable `pending` pauses. To include `stale`, `resumed`, and `timed_out` entries, use:
+
+```bash
+pytest-live-pause ls -a
+```
+
+If a pytest process is killed while paused, its pause file remains on disk. The CLI treats that as `stale` when the recorded `pid` is no longer alive on the current host. `ls -a` will show the stale state, and `resume` will refuse to write a command for it.
+
+If no command arrives before `--pause-timeout`, the test resumes automatically without adding an external failure reason.
+
+When pytest starts, it prints the current `run_id`, so you can monitor that specific pytest process with `pytest-live-pause watch --run-id <run_id>`.
+
+## File Protocol
+
+`pauses/<pause_id>.json` currently contains:
+
+```json
+{
+	"pause_id": "...",
+	"run_id": "...",
+	"nodeid": "tests/test_sample.py::test_failure",
+	"timeout": 300.0,
+	"original_failure": "AssertionError: boom",
+	"status": "pending",
+	"created_at": 1710000000.0,
+	"pid": 12345,
+	"hostname": "host.local",
+	"cwd": "/repo"
+}
+```
+
+`commands/<pause_id>.resume.json` currently contains:
+
+```json
+{
+	"failure_reason": "manually confirmed"
+}
+```
+
+Or for a checkpoint pause:
+
+```json
+{
+	"result": true,
+	"reason": "approved"
+}
+```
+
+This file transport is only the first implementation. The runtime can be split from the transport later if you want to add sockets or HTTP.

pytest_live_pause-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+pytest_live_pause/__init__.py,sha256=VMyQiRUpYa23UsOnYA2zObHr52mVtFd3t9PmcU5sjHo,57
+pytest_live_pause/cli.py,sha256=4LxEGPYxdg0_q_g0Ioq_RSnMVuQ-uVNTt7vJUohNicA,8404
+pytest_live_pause/plugin.py,sha256=6p7RkfwNbMo_caeadlniJdTq2hL_ON8G_3cq80GJ_YM,5400
+pytest_live_pause/runtime.py,sha256=RqC7Y1l7jdtQjTps24-boMuqAsaJ996jakoLDAoT-e0,9346
+pytest_live_pause-0.1.0.dist-info/METADATA,sha256=Bhu6Ld0a0kBsEx92_hJj1vZnYi-cx9QudOHXaZkSmhE,5965
+pytest_live_pause-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+pytest_live_pause-0.1.0.dist-info/entry_points.txt,sha256=wHzbD8y6F_ENS9qmZsPAO4m-VsEeSQfBnH0v00s1KG0,122
+pytest_live_pause-0.1.0.dist-info/licenses/LICENSE,sha256=hYRaJ2ed2IMo9RmO96UxUSTt9iwL49leBY5kVtDymRo,1063
+pytest_live_pause-0.1.0.dist-info/RECORD,,

pytest_live_pause-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

pytest_live_pause-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,5 @@
+[console_scripts]
+pytest-live-pause = pytest_live_pause.cli:main
+
+[pytest11]
+pytest_live_pause = pytest_live_pause.plugin

pytest_live_pause-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lanbao
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.