crapkit 0.7.0__tar.gz → 0.7.2__tar.gz

{crapkit-0.7.0/src/crapkit.egg-info → crapkit-0.7.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: crapkit
-Version: 0.7.0
+Version: 0.7.2
 Summary: Scores every function on complexity times uncovered risk, ranks the worst, and blocks commits that add more.
 Author: Jean-Francois Gagne
 License: MIT
@@ -30,7 +30,7 @@ Requires-Dist: lizard>=1.24.0
 Provides-Extra: dev
 Requires-Dist: pytest>=8; extra == "dev"
 Requires-Dist: pytest-cov>=5; extra == "dev"
-Requires-Dist: pytest-xdist>=3; extra == "dev"
+Requires-Dist: pytest-xdist>=3.7; extra == "dev"
 Requires-Dist: coverage>=7.10.6; extra == "dev"
 Requires-Dist: PyYAML>=6; extra == "dev"
 Requires-Dist: Pillow; extra == "dev"
@@ -199,7 +199,7 @@ files. Review those commands before running Crapkit in a repository you do not t
 
 ```
 $ crapkit --version
-crapkit 0.7.0
+crapkit 0.7.2
 ```
 
 `python -m crapkit` works identically to the console script and is what to use from a
@@ -455,7 +455,7 @@ crapkit ships a `.pre-commit-hooks.yaml` declaring `id: crapkit-gate`. In your
 repos:
   - repo: https://github.com/JeanFrancoisGagne/crapkit
     # crapkit's release step rewrites this line to the tag it just cut
-    rev: v0.7.0
+    rev: v0.7.2
     hooks:
       - id: crapkit-gate
 ```
@@ -563,7 +563,7 @@ to a workflow, and every input has a default:
       - uses: actions/checkout@v4
         with:
           fetch-depth: 0
-      - uses: JeanFrancoisGagne/crapkit@v0.7.0
+      - uses: JeanFrancoisGagne/crapkit@v0.7.2
 ```
 
 The whole job those four lines sit in:
@@ -583,7 +583,7 @@ jobs:
         with:
           python-version: "3.12"       # the interpreter the install below lands in
       - run: pip install -e ".[dev]"   # whatever your lanes need to run
-      - uses: JeanFrancoisGagne/crapkit@v0.7.0
+      - uses: JeanFrancoisGagne/crapkit@v0.7.2
         with:
           gate: "false"
 ```
@@ -754,6 +754,10 @@ on PATH fails that step. Both leave the rendered text in the job log.
 
 ## Subcommands
 
+`crapkit clean --dry-run --json` previews policy-based cleanup. See
+[resource policies](https://github.com/JeanFrancoisGagne/crapkit/blob/main/docs/resources.md)
+for shared analysis workers, process lifetime, bounded logs and retained evidence.
+
 Every subcommand takes `--repo PATH`, and the flag goes **after** the subcommand. Without
 it the root is the nearest `crapkit.toml` at or above the current directory
 ([ADR 0002](https://github.com/JeanFrancoisGagne/crapkit/blob/main/docs/adr/0002-configuration-is-found-upward-nearest-wins.md)): from a
@@ -780,6 +784,7 @@ crapkit: error: argument command: invalid choice: '/path/to/repo' (choose from '
 
 | Command | What it does |
 |---|---|
+| `clean [--dry-run] [--json]` | Applies configured retention to recognized idle default test evidence and recovers abandoned temporary mutation worktrees. Preserves active runs, caller-managed output and intentional mutation pools. `--dry-run` reports planned removals. |
 | `init` | Sniffs tracked source into per-directory scopes, writes a self-validated starter `crapkit.toml` whose lanes report into `.crapkit/cov/`, and appends `.crapkit/` plus each runner's own droppings to `.gitignore`. Writes a live `[[lane]]` when it can detect the test runner, otherwise a commented template. Refuses to clobber an existing config. |
 | `doctor [--show-files] [--json] [--tune] [--plugin-root [PATH]]` | Checks the config still describes the repo: unknown keys (with the accepted spellings), zero-file scopes, tracked source no scope claims, scopes no lane covers, lane cwds and commands that no longer resolve, lizard importable, oversized files. It reads each lane command with the shell that will run it, so a quoted interpreter path is one word and a runner after `&&` is checked too, and it FAILs a lane whose runner does not resolve or that the shell cannot start, naming the word to change; a bare name is looked for on PATH and a runner spelled as a path is looked for under the directory the lane runs in, so `.venv/bin/python` answers the same from any directory you run `doctor` in; each distinct runner is probed once, not once per lane. It WARNs on a lane writing its artifact at the repo root, a `coveragepy` or `istanbul` lane with no `results_artifact` (the crashed-worker and no-new-failures checks are off for it, whichever runner the lane spells), a committed hook under `core.hooksPath` that is not executable in the index, a directory whose functions are all `untested` while its tests exist, and a scope a lane measures with no `[crapkit.scoped_tests]` template behind it, which is the loop's step 4 with nothing to run. `--tune` prints suggested parallelism knobs and writes nothing. `--plugin-root PATH` reads no repo at all: it checks an installed [plugin](https://github.com/JeanFrancoisGagne/crapkit/tree/main/plugin) against the `crapkit` on PATH (the bare name its hooks and MCP server spawn) on both version and hook `--protocol`, and FAILs when PATH carries no `crapkit` at all, one line per disagreement and silence when they agree; PATH is the plugin root or any directory above it, `~/.claude` included (only manifests named `crapkit` count, and the newest install wins), and with no PATH it looks in Claude Code's plugin cache. A root it found rather than one you typed is named first, as `crapkit doctor: checking PATH`. See [docs/agent-json.md](https://github.com/JeanFrancoisGagne/crapkit/blob/main/docs/agent-json.md#doctor---json). |
 | `inventory [--db PATH] [--export PATH] [--json]` | One lizard pass over every in-scope file into a SQLite snapshot run, cached by content hash. `--db` is the only way to point crapkit at a store outside `.crapkit/`, and only this command accepts it. |
@@ -1177,7 +1182,7 @@ exit 5:
 
 ```
 $ crapkit coverage
-crapkit: lane 'js' FAILED: lane 'js' produced no artifact at .crapkit/cov/js/coverage-final.json (command exit 1); full log: /repo/.crapkit/lane-js.log; last output: $ npm run test -- --coverage --coverage.reportsDirectory=.crapkit/cov/js --coverage.reportOnFailure --reporter=default --reporter=junit --outputFile=.crapkit/cov/js/junit.xml
+crapkit: lane 'js' FAILED: lane 'js' produced no artifact at .crapkit/cov/js/coverage-final.json (command exit 1); lane log: /repo/.crapkit/lane-js.log; last output: $ npm run test -- --coverage --coverage.reportsDirectory=.crapkit/cov/js --coverage.reportOnFailure --reporter=default --reporter=junit --outputFile=.crapkit/cov/js/junit.xml
 
  MISSING DEPENDENCY  Cannot find dependency '@vitest/coverage-v8'
 
@@ -1339,6 +1344,7 @@ with no debt.
 | [docs/adoption.md](https://github.com/JeanFrancoisGagne/crapkit/blob/main/docs/adoption.md) | The judgment layer over the quickstarts: scope granularity, exclude vs lane, scoped_tests wiring, the first-verify taint hazard. |
 | [docs/configuration.md](https://github.com/JeanFrancoisGagne/crapkit/blob/main/docs/configuration.md) | Every `crapkit.toml` key: type, default, and what it does. |
 | [docs/lanes.md](https://github.com/JeanFrancoisGagne/crapkit/blob/main/docs/lanes.md) | The lane model, vitest and jest and pytest recipes, artifact reuse, flake retest, containers. |
+| [docs/resources.md](https://github.com/JeanFrancoisGagne/crapkit/blob/main/docs/resources.md) | Worker budgets, command cleanup, log rotation, test evidence retention and safe cleanup. |
 | [docs/ratchet.md](https://github.com/JeanFrancoisGagne/crapkit/blob/main/docs/ratchet.md) | Seeding, pruning, the git merge driver, metric stamps, debt policy, overrides. |
 | [docs/upgrading.md](https://github.com/JeanFrancoisGagne/crapkit/blob/main/docs/upgrading.md) | Existing installations: analysis and key versions, saved state, plugin alignment and Windows upgrades. |
 | [docs/portable-records.md](https://github.com/JeanFrancoisGagne/crapkit/blob/main/docs/portable-records.md) | Lossless exports, portable baselines and ratchets, including filenames with delimiters. |

{crapkit-0.7.0 → crapkit-0.7.2}/README.md

@@ -158,7 +158,7 @@ files. Review those commands before running Crapkit in a repository you do not t
 
 ```
 $ crapkit --version
-crapkit 0.7.0
+crapkit 0.7.2
 ```
 
 `python -m crapkit` works identically to the console script and is what to use from a
@@ -414,7 +414,7 @@ crapkit ships a `.pre-commit-hooks.yaml` declaring `id: crapkit-gate`. In your
 repos:
   - repo: https://github.com/JeanFrancoisGagne/crapkit
     # crapkit's release step rewrites this line to the tag it just cut
-    rev: v0.7.0
+    rev: v0.7.2
     hooks:
       - id: crapkit-gate
 ```
@@ -522,7 +522,7 @@ to a workflow, and every input has a default:
       - uses: actions/checkout@v4
         with:
           fetch-depth: 0
-      - uses: JeanFrancoisGagne/crapkit@v0.7.0
+      - uses: JeanFrancoisGagne/crapkit@v0.7.2
 ```
 
 The whole job those four lines sit in:
@@ -542,7 +542,7 @@ jobs:
         with:
           python-version: "3.12"       # the interpreter the install below lands in
       - run: pip install -e ".[dev]"   # whatever your lanes need to run
-      - uses: JeanFrancoisGagne/crapkit@v0.7.0
+      - uses: JeanFrancoisGagne/crapkit@v0.7.2
         with:
           gate: "false"
 ```
@@ -713,6 +713,10 @@ on PATH fails that step. Both leave the rendered text in the job log.
 
 ## Subcommands
 
+`crapkit clean --dry-run --json` previews policy-based cleanup. See
+[resource policies](https://github.com/JeanFrancoisGagne/crapkit/blob/main/docs/resources.md)
+for shared analysis workers, process lifetime, bounded logs and retained evidence.
+
 Every subcommand takes `--repo PATH`, and the flag goes **after** the subcommand. Without
 it the root is the nearest `crapkit.toml` at or above the current directory
 ([ADR 0002](https://github.com/JeanFrancoisGagne/crapkit/blob/main/docs/adr/0002-configuration-is-found-upward-nearest-wins.md)): from a
@@ -739,6 +743,7 @@ crapkit: error: argument command: invalid choice: '/path/to/repo' (choose from '
 
 | Command | What it does |
 |---|---|
+| `clean [--dry-run] [--json]` | Applies configured retention to recognized idle default test evidence and recovers abandoned temporary mutation worktrees. Preserves active runs, caller-managed output and intentional mutation pools. `--dry-run` reports planned removals. |
 | `init` | Sniffs tracked source into per-directory scopes, writes a self-validated starter `crapkit.toml` whose lanes report into `.crapkit/cov/`, and appends `.crapkit/` plus each runner's own droppings to `.gitignore`. Writes a live `[[lane]]` when it can detect the test runner, otherwise a commented template. Refuses to clobber an existing config. |
 | `doctor [--show-files] [--json] [--tune] [--plugin-root [PATH]]` | Checks the config still describes the repo: unknown keys (with the accepted spellings), zero-file scopes, tracked source no scope claims, scopes no lane covers, lane cwds and commands that no longer resolve, lizard importable, oversized files. It reads each lane command with the shell that will run it, so a quoted interpreter path is one word and a runner after `&&` is checked too, and it FAILs a lane whose runner does not resolve or that the shell cannot start, naming the word to change; a bare name is looked for on PATH and a runner spelled as a path is looked for under the directory the lane runs in, so `.venv/bin/python` answers the same from any directory you run `doctor` in; each distinct runner is probed once, not once per lane. It WARNs on a lane writing its artifact at the repo root, a `coveragepy` or `istanbul` lane with no `results_artifact` (the crashed-worker and no-new-failures checks are off for it, whichever runner the lane spells), a committed hook under `core.hooksPath` that is not executable in the index, a directory whose functions are all `untested` while its tests exist, and a scope a lane measures with no `[crapkit.scoped_tests]` template behind it, which is the loop's step 4 with nothing to run. `--tune` prints suggested parallelism knobs and writes nothing. `--plugin-root PATH` reads no repo at all: it checks an installed [plugin](https://github.com/JeanFrancoisGagne/crapkit/tree/main/plugin) against the `crapkit` on PATH (the bare name its hooks and MCP server spawn) on both version and hook `--protocol`, and FAILs when PATH carries no `crapkit` at all, one line per disagreement and silence when they agree; PATH is the plugin root or any directory above it, `~/.claude` included (only manifests named `crapkit` count, and the newest install wins), and with no PATH it looks in Claude Code's plugin cache. A root it found rather than one you typed is named first, as `crapkit doctor: checking PATH`. See [docs/agent-json.md](https://github.com/JeanFrancoisGagne/crapkit/blob/main/docs/agent-json.md#doctor---json). |
 | `inventory [--db PATH] [--export PATH] [--json]` | One lizard pass over every in-scope file into a SQLite snapshot run, cached by content hash. `--db` is the only way to point crapkit at a store outside `.crapkit/`, and only this command accepts it. |
@@ -1136,7 +1141,7 @@ exit 5:
 
 ```
 $ crapkit coverage
-crapkit: lane 'js' FAILED: lane 'js' produced no artifact at .crapkit/cov/js/coverage-final.json (command exit 1); full log: /repo/.crapkit/lane-js.log; last output: $ npm run test -- --coverage --coverage.reportsDirectory=.crapkit/cov/js --coverage.reportOnFailure --reporter=default --reporter=junit --outputFile=.crapkit/cov/js/junit.xml
+crapkit: lane 'js' FAILED: lane 'js' produced no artifact at .crapkit/cov/js/coverage-final.json (command exit 1); lane log: /repo/.crapkit/lane-js.log; last output: $ npm run test -- --coverage --coverage.reportsDirectory=.crapkit/cov/js --coverage.reportOnFailure --reporter=default --reporter=junit --outputFile=.crapkit/cov/js/junit.xml
 
  MISSING DEPENDENCY  Cannot find dependency '@vitest/coverage-v8'
 
@@ -1298,6 +1303,7 @@ with no debt.
 | [docs/adoption.md](https://github.com/JeanFrancoisGagne/crapkit/blob/main/docs/adoption.md) | The judgment layer over the quickstarts: scope granularity, exclude vs lane, scoped_tests wiring, the first-verify taint hazard. |
 | [docs/configuration.md](https://github.com/JeanFrancoisGagne/crapkit/blob/main/docs/configuration.md) | Every `crapkit.toml` key: type, default, and what it does. |
 | [docs/lanes.md](https://github.com/JeanFrancoisGagne/crapkit/blob/main/docs/lanes.md) | The lane model, vitest and jest and pytest recipes, artifact reuse, flake retest, containers. |
+| [docs/resources.md](https://github.com/JeanFrancoisGagne/crapkit/blob/main/docs/resources.md) | Worker budgets, command cleanup, log rotation, test evidence retention and safe cleanup. |
 | [docs/ratchet.md](https://github.com/JeanFrancoisGagne/crapkit/blob/main/docs/ratchet.md) | Seeding, pruning, the git merge driver, metric stamps, debt policy, overrides. |
 | [docs/upgrading.md](https://github.com/JeanFrancoisGagne/crapkit/blob/main/docs/upgrading.md) | Existing installations: analysis and key versions, saved state, plugin alignment and Windows upgrades. |
 | [docs/portable-records.md](https://github.com/JeanFrancoisGagne/crapkit/blob/main/docs/portable-records.md) | Lossless exports, portable baselines and ratchets, including filenames with delimiters. |

{crapkit-0.7.0 → crapkit-0.7.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "crapkit"
-version = "0.7.0"
+version = "0.7.2"
 description = "Scores every function on complexity times uncovered risk, ranks the worst, and blocks commits that add more."
 readme = { file = "README.md", content-type = "text/markdown" }
 license = { text = "MIT" }
@@ -63,7 +63,8 @@ Source = "https://github.com/JeanFrancoisGagne/crapkit"
 # about 8 minutes serial against about 1m30 parallel on the same tree. Nothing
 # here needs pytest-timeout: no test takes a `--timeout` and none carries the
 # marker.
-dev = ["pytest>=8", "pytest-cov>=5", "pytest-xdist>=3", "coverage>=7.10.6", "PyYAML>=6", "Pillow"]
+# xdist 3.7 supports Python 3.13 and atomic reassignment for work stealing.
+dev = ["pytest>=8", "pytest-cov>=5", "pytest-xdist>=3.7", "coverage>=7.10.6", "PyYAML>=6", "Pillow"]
 # coverage>=7.10.6 in both extras is the floor `[tool.coverage.run] patch` needs,
 # and it is not decoration: coverage 7.9 answers an unrecognized `[run] patch=`
 # with a CoverageWarning that pytest-cov 6.2.0 and later file under

{crapkit-0.7.0 → crapkit-0.7.2}/src/crapkit/__init__.py

@@ -1,2 +1,2 @@
 """crapkit: deterministic CRAP-score framework."""
-__version__ = "0.7.0"
+__version__ = "0.7.2"

crapkit-0.7.2/src/crapkit/_analysis_pool.py

@@ -0,0 +1,190 @@
+"""Keep shared worker slots until every gated analysis worker has stopped."""
+from __future__ import annotations
+
+from concurrent.futures import ProcessPoolExecutor
+from concurrent.futures.process import BrokenProcessPool
+from contextlib import ExitStack, contextmanager
+import multiprocessing
+from multiprocessing.connection import wait
+import os
+from pathlib import Path
+import threading
+
+from .errors import ToolError
+from .locks import exclusive_lock
+from .procs import own_processes
+from .resources import available_slots, resource_status, worker_lock
+
+
+def _lock_worker_descriptor(descriptor):
+    if os.name == "nt":
+        import msvcrt
+        msvcrt.locking(descriptor, msvcrt.LK_NBLCK, 1)
+    else:
+        import fcntl
+        fcntl.flock(descriptor, fcntl.LOCK_EX | fcntl.LOCK_NB)
+
+
+def _claim_worker_slot(path):
+    descriptor = os.open(worker_lock(path), os.O_CREAT | os.O_RDWR, 0o600)
+    try:
+        _lock_worker_descriptor(descriptor)
+    except OSError:
+        os.close(descriptor)
+        return False
+    # No Python file object or finalizer may release this before process exit.
+    return True
+
+
+def _retain_worker_slot(paths):
+    for path in paths:
+        if _claim_worker_slot(path):
+            return
+    raise ToolError("no analysis worker slot remains available")
+
+
+def _stop_with_parent(parent):
+    wait([parent.sentinel])
+    os._exit(1)
+
+
+def _worker_gate(registrations, paths) -> None:
+    if os.name != "nt":
+        os.setsid()
+    parent = multiprocessing.parent_process()
+    directory, names = paths
+    _retain_worker_slot(Path(directory) / name for name in names)
+    receive, send = multiprocessing.Pipe(duplex=False)
+    registrations.put((os.getpid(), send))
+    try:
+        ready = wait([receive, parent.sentinel])
+        if parent.sentinel in ready or receive.recv() != "go":
+            os._exit(1)
+    finally:
+        receive.close()
+        send.close()
+    threading.Thread(target=_stop_with_parent, args=(parent,), daemon=True).start()
+
+
+def _release_worker(owner, pid: int, gate, errors: list) -> None:
+    try:
+        owner.register_then(pid, lambda: gate.send("go"))
+    except Exception as error:
+        errors.append(str(error))
+        _refuse_gate(gate)
+    finally:
+        gate.close()
+
+
+def _refuse_gate(gate):
+    try:
+        gate.send("refused")
+    except OSError:
+        pass  # The worker can already have exited after its caller died.
+
+
+def _register_workers(owner, registrations, errors: list) -> None:
+    for entry in iter(registrations.get, None):
+        _release_worker(owner, *entry, errors)
+
+
+class _OwnedPool:
+    def __init__(self, owner, paths):
+        context = multiprocessing.get_context()
+        self.start_before_submit = context.get_start_method() != "fork"
+        self.registrations = context.Queue()
+        # Windows spawn writes this descriptor through a bounded bootstrap pipe.
+        packed = (str(Path(paths[0]).parent), tuple(Path(path).name for path in paths))
+        self.executor = ProcessPoolExecutor(max_workers=len(paths), mp_context=context,
+                                           initializer=_worker_gate,
+                                           initargs=(self.registrations, packed))
+        self.errors = []
+        self.registrar = threading.Thread(target=_register_workers,
+                                          args=(owner, self.registrations, self.errors), daemon=True)
+        self.started = False
+
+    def map(self, function, jobs, *, chunksize=1):
+        # Submit starts all fork workers before adding our registration thread.
+        if self.start_before_submit:
+            self._start_registrar()
+        try:
+            results = self.executor.map(function, jobs, chunksize=chunksize)
+        finally:
+            self._start_registrar()
+        try:
+            yield from results
+        except BrokenProcessPool as error:
+            if self.errors:
+                raise ToolError(self.errors[0]) from error
+            raise
+
+    def _start_registrar(self):
+        if not self.started:
+            self.registrar.start()
+            self.started = True
+
+    def close(self):
+        self.executor.shutdown(wait=True, cancel_futures=True)
+        if self.started:
+            self.registrations.put(None)
+            self.registrar.join()
+        self.registrations.close()
+        self.registrations.join_thread()
+
+
+@contextmanager
+def _pool_owner(paths):
+    with ExitStack() as stack:
+        owned = paths
+        if os.name == "nt":
+            if not _claim_primary_slots(stack, paths):
+                yield None
+                return
+            owned = ()
+        owner = stack.enter_context(own_processes(owned, optional=True, label="analysis workers"))
+        yield owner if owner.held else None
+
+
+def _claim_primary_slots(stack, paths):
+    try:
+        for path in paths:
+            stack.enter_context(exclusive_lock(path, label="analysis workers"))
+    except (OSError, ToolError):
+        return False
+    return True
+
+
+@contextmanager
+def _held_pool(paths):
+    with _pool_owner(paths) as owner:
+        if owner is None:
+            yield None
+            return
+        pool = _OwnedPool(owner, paths)
+        try:
+            yield pool
+        except BaseException:
+            owner.cancel()
+            raise
+        finally:
+            pool.close()
+
+
+@contextmanager
+def analysis_pool(*, workers: int | None = None, worker_budget: int = 0):
+    """Yield an owned pool, or None for cheap serial work or busy shared slots.
+
+    Probing does not reserve capacity. The caller on Windows, or a guardian on
+    POSIX, claims primary slots before workers start. Actual workers retain
+    companion slots through process exit. A competing claim falls back.
+    """
+    status = resource_status(analysis_workers=workers or 0, worker_budget=worker_budget)
+    if status["pool_worker_limit"] == 1:
+        yield None
+        return
+    paths = available_slots(status)
+    if len(paths) < 2:
+        yield None
+        return
+    with _held_pool(paths) as pool:
+        yield pool

crapkit-0.7.2/src/crapkit/_mcp_stdio.py

@@ -0,0 +1,208 @@
+"""A bounded stdio session with one owned tool request at a time."""
+from concurrent.futures import ThreadPoolExecutor
+from contextlib import ExitStack
+import json
+import os
+import queue
+import sys
+import threading
+
+from .procs import CommandCancelled, own_processes
+
+
+class _OutputClosed(Exception):
+    """The client stopped accepting protocol output."""
+
+
+def _lines(source):
+    try:
+        descriptor = source.fileno()
+    except (AttributeError, OSError):
+        yield from iter(source.readline, '')
+        return
+    pending = b''
+    while chunk := os.read(descriptor, 65536):
+        pieces = (pending + chunk).split(b'\n')
+        pending = pieces.pop()
+        yield from (piece.decode('utf-8') for piece in pieces)
+    if pending:
+        yield pending.decode('utf-8')
+
+
+def _read(source, events, slots):
+    try:
+        for line in _lines(source):
+            slots.acquire()
+            events.put(('input', line))
+    except (OSError, ValueError):
+        pass
+    finally:
+        events.put(('eof', None))
+
+
+class Session:
+    """Keep protocol input responsive while a single CLI child is running."""
+
+    def __init__(self, source, target, reply, run_cli):
+        self.source, self.target = source, target
+        self.reply, self.run_cli = reply, run_cli
+        self.events = queue.SimpleQueue()
+        self.input_slots = threading.Semaphore(32)
+        self.stack = ExitStack()
+        self.owner_context = None
+        self.lock = threading.Lock()
+        self.owner = self.pool = self.active = None
+        self.request_id = None
+
+    def run(self):
+        threading.Thread(target=_read, args=(self.source, self.events, self.input_slots),
+                         daemon=True).start()
+        try:
+            while self._event(*self.events.get()):
+                pass
+        finally:
+            self._cleanup()
+        return 0
+
+    def _cleanup(self):
+        failure = sys.exception()
+        for cleanup in (self._cancel_for_cleanup, self.stack.close, self._retire_owner):
+            try:
+                cleanup()
+            except BaseException as error:
+                failure = failure or error
+        if failure is not None:
+            raise failure
+
+    def _cancel_for_cleanup(self):
+        try:
+            self._cancel()
+        except BaseException as error:
+            try:
+                self._retire_owner()
+            finally:
+                raise error
+
+    def _event(self, kind, value):
+        if kind == 'eof':
+            return False
+        if kind == 'done':
+            self._done(value)
+        else:
+            self.input_slots.release()
+            self._input(value)
+        return True
+
+    def _input(self, line):
+        try:
+            message = json.loads(line)
+        except ValueError:
+            return
+        if not isinstance(message, dict):
+            return
+        if message.get('method') == 'notifications/cancelled' and 'id' not in message:
+            self._notification(message)
+            return
+        self.request_id = message.get('id')
+        response = self.reply(message, self._submit)
+        if self._immediate(response):
+            self._write(response)
+
+    def _immediate(self, response):
+        if response is None:
+            return False
+        return self.active is None or response.get('result') is not self.active
+
+    def _notification(self, message):
+        params = message.get('params') or {}
+        if not isinstance(params, dict):
+            return
+        if self._matches(params.get('requestId')):
+            self._cancel()
+
+    def _matches(self, request_id):
+        if self.active is None:
+            return False
+        current = self.active['id']
+        return type(request_id) is type(current) and request_id == current
+
+    def _submit(self, tool, arguments, repo):
+        if self.active is not None:
+            return {'content': [{'type': 'text', 'text': 'another tool is running; retry after it finishes'}],
+                    'isError': True}
+        if self.pool is None:
+            self.pool = self.stack.enter_context(ThreadPoolExecutor(max_workers=1))
+        request = {'id': self.request_id, 'cancelled': False}
+        self.active = request
+        future = self.pool.submit(self._execute, request, tool, arguments, repo)
+        request['future'] = future
+        future.add_done_callback(lambda done: self.events.put(('done', request)))
+        return request
+
+    def _execute(self, request, tool, arguments, repo):
+        with self.lock:
+            if request['cancelled']:
+                raise CommandCancelled('request was cancelled before it started')
+            if self.owner is None:
+                context = own_processes(())
+                self.owner = context.__enter__()
+                self.owner_context = context
+            if request['cancelled']:
+                raise CommandCancelled('request was cancelled during owner startup')
+            owner = self.owner
+        return self.run_cli(tool, arguments, repo, owner=owner)
+
+    def _cancel(self):
+        request = self.active
+        if request is None:
+            return
+        request['cancelled'] = True
+        with self.lock:
+            if self.owner is not None:
+                self.owner.cancel()
+
+    def _done(self, request):
+        self.active = None
+        if request['cancelled']:
+            self._retire_owner()
+            return
+        self._write(self._response(request))
+
+    def _retire_owner(self):
+        if self.owner_context is not None:
+            self.owner_context.__exit__(None, None, None)
+        self.owner_context = None
+        self.owner = None
+
+    def _response(self, request):
+        response = {'jsonrpc': '2.0', 'id': request['id']}
+        try:
+            response['result'] = request['future'].result()
+        except Exception as error:
+            response['error'] = {'code': -32603, 'message': f'{type(error).__name__}: {error}'}
+        return response
+
+    def _write(self, response):
+        try:
+            self.target.write(json.dumps(response) + '\n')
+            self.target.flush()
+        except OSError as error:
+            _silence_output(self.target)
+            raise _OutputClosed from error
+
+
+def _silence_output(target):
+    # Prevent the interpreter's final stdout flush from repeating a broken pipe.
+    try:
+        with open(os.devnull, 'w') as sink:
+            os.dup2(sink.fileno(), target.fileno())
+    except (AttributeError, OSError):
+        pass
+
+
+def serve(source, target, reply, run_cli):
+    try:
+        return Session(source, target, reply, run_cli).run()
+    except _OutputClosed:
+        # A client can close its read pipe independently of stdin.
+        return 0

crapkit-0.7.2/src/crapkit/_process_family.py

@@ -0,0 +1,83 @@
+"""POSIX nested guardians retain ancestor completion until their writers stop.
+
+Command groups cannot kill a nested guardian before it finishes cleanup. Each
+guardian runs in a separate session and holds a lease in every ancestor family.
+Closing admission before killing a group makes late guardian starts refuse.
+"""
+from contextlib import ExitStack, contextmanager
+import json
+import os
+from pathlib import Path
+import shutil
+import tempfile
+import uuid
+
+from .errors import ToolError
+
+_ENV = 'CRAPKIT_COMMAND_FAMILIES'
+
+
+def command_environment(environment):
+    """Name a family before spawn; only successful registration creates it."""
+    family = str(Path(tempfile.gettempdir()) / ('crapkit-family-' + uuid.uuid4().hex))
+    parents = json.loads(os.environ.get(_ENV, '[]'))
+    return family, {**(os.environ if environment is None else environment),
+                    _ENV: json.dumps([*parents, family])}
+
+
+@contextmanager
+def _locked(path, mode='r+b'):
+    import fcntl
+    with path.open(mode) as stream:
+        fcntl.flock(stream, fcntl.LOCK_EX)
+        yield stream
+
+
+def _register(path, stack):
+    with _locked(path / 'admission'):
+        if (path / 'closed').exists():
+            raise ToolError('ancestor command has stopped; no new work can start')
+        lease = path / (uuid.uuid4().hex + '.lease')
+        stack.enter_context(_locked(lease, 'x+b'))
+
+
+@contextmanager
+def ancestor_leases():
+    """Keep all ancestor commands incomplete until this guardian exits."""
+    with ExitStack() as stack:
+        try:
+            for path in json.loads(os.environ.get(_ENV, '[]')):
+                _register(Path(path), stack)
+        except OSError as error:
+            raise ToolError('ancestor command has stopped; cannot retain ownership') from error
+        yield
+
+
+class Family:
+    def __init__(self, path):
+        self.path = Path(path)
+        self.path.mkdir(mode=0o700)
+        try:
+            (self.path / 'admission').touch()
+        except OSError:
+            self.path.rmdir()
+            raise
+
+    def close_admission(self):
+        with _locked(self.path / 'admission'):
+            (self.path / 'closed').touch()
+            return list(self.path.glob('*.lease'))
+
+    def finish(self, leases):
+        for lease in leases:
+            with _locked(lease):
+                pass
+        shutil.rmtree(self.path)
+
+    @contextmanager
+    def stopping(self):
+        leases = self.close_admission()
+        try:
+            yield
+        finally:
+            self.finish(leases)