subtask-mcp 0.2.3__tar.gz

subtask_mcp-0.2.3/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 subtask contributors
+
+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.

subtask_mcp-0.2.3/PKG-INFO

@@ -0,0 +1,164 @@
+Metadata-Version: 2.4
+Name: subtask-mcp
+Version: 0.2.3
+Summary: Background sub-agents for Claude Code, Codex, Kimi and OpenCode, over MCP or CLI, with a spend cap
+License: MIT
+Project-URL: Homepage, https://github.com/tedin7/subtask
+Project-URL: Repository, https://github.com/tedin7/subtask
+Project-URL: Issues, https://github.com/tedin7/subtask/issues
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: POSIX
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: claude-agent-sdk>=0.2
+Requires-Dist: mcp<2,>=1.28
+Provides-Extra: dsh
+Requires-Dist: deepseek-harness-sdk==0.1.5rc1; extra == "dsh"
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Requires-Dist: jsonschema>=4; extra == "dev"
+Requires-Dist: tqdm>=4; extra == "dev"
+Dynamic: license-file
+
+# subtask
+
+<!-- mcp-name: io.github.tedin7/subtask -->
+
+A local delegation scheduler for coding agents. One MCP server (and a twin
+CLI) lets Claude Code, Codex, Kimi Code or OpenCode start work in parallel,
+wait for it with a single call, and read back a short summary with evidence.
+It picks an engine that can take the job, books money and slots safely across
+processes, and says honestly how isolated each run is.
+
+```
+start_many([{task: "Fix the flaky test in tests/test_sync.py", repo: "/src/app", verify: "pytest -q tests/test_sync.py"},
+            {task: "List every caller of parse_date()", kind: "read", readonly: true, cwd: "/src/app"}])
+  -> st-4f2a91 started · sonnet-api · branch subtask/st-4f2a91 · sandbox
+     st-77c0de started · haiku-api · /src/app · readonly
+wait(["st-4f2a91", "st-77c0de"])          # Claude Code shows: Subtask · 01:16 · 1/2 ended — st-4f2a91 running tests: pytest -q
+  -> st-4f2a91 done · sonnet-api · 6m · 0.412$ · verified · ...
+     ## Summary (≤10 lines: the answer, files, commits, tests, what is left)
+result("st-4f2a91", evidence=True)        # JSON: base/head, changed files, observed commands, verify exit code, cost
+```
+
+## Why
+
+- **Save the caller's context.** The worker's search, test runs and dead ends
+  stay in its own session; the caller reads about ten lines.
+- **Few round trips.** `start_many` + one `wait` replace a polling loop.
+- **Use whatever has room.** `engine="auto"` filters engines that can enforce
+  the requested isolation, are installed, fit the budget and have quota, then
+  ranks them with an explicit utility (`subtask routing explain`).
+- **Money is a primitive.** Paid engines reserve their budget before any work,
+  under one lock with the slot; every reservation is closed exactly once.
+- **Evidence, not claims.** `verify="..."` runs your check on the commit the
+  worker left; `result(evidence=True)` separates what subtask observed from
+  what the worker reported.
+
+## Install
+
+The distribution is `subtask-mcp` (the PyPI name `subtask` is an unrelated
+project). Full guide, per client, with native commands: [docs/install.md](docs/install.md).
+
+```sh
+uv tool install "git+https://github.com/tedin7/subtask@v0.2.3"   # or: uv tool install /path/to/checkout
+subtask install --client all          # prints the plan for every detected client
+subtask install --client all --yes    # applies it: MCP server + skill
+subtask doctor --client all           # checks app, config entry and a real handshake
+```
+
+Claude Code plugin: `claude plugin marketplace add tedin7/subtask` then
+`claude plugin install subtask@subtask`. Codex: `codex plugin marketplace add tedin7/subtask`.
+API engines read `ANTHROPIC_API_KEY` from `~/.config/subtask/env` (chmod 600).
+
+## Engines
+
+| engine | pays with | read-only | isolation it can enforce |
+|---|---|---|---|
+| `haiku-api`, `sonnet-api`, `opus-api` | API key, monthly cap | yes | sandbox (Claude Code OS sandbox) |
+| `codex` | Codex login (quota from local session files) | yes | sandbox (`workspace-write`), isolated |
+| `opencode-go` | opencode-go subscription | no | worktree, isolated |
+| `kimi` | Kimi login | no | worktree, isolated |
+| `dsh` | DeepSeek key, same cap (`subtask-mcp[dsh]`) | no | worktree |
+| `opencode` | OpenCode default provider (manual only) | no | worktree, isolated |
+
+Add an engine without touching the core: an `EngineAdapter` registered under the
+`subtask.engines` entry point (see [CONTRIBUTING.md](CONTRIBUTING.md)).
+
+## Isolation, honestly
+
+- `worktree` (default): a git worktree and branch per writing job. It prevents
+  collisions; it is **not** a host sandbox.
+- `sandbox`: the engine's own sandbox. Same user: a guard rail.
+- `isolated`: bubblewrap. Read-only system, writable worktree and git dir only,
+  a private HOME with only the engine's own state. Needs `bwrap`.
+- `untrusted`: sandbox or stronger, and no network for the worker's commands.
+
+A job that cannot get the policy it asked for is refused, never downgraded.
+Output is redacted for common secret formats before it is saved or shown;
+redaction is a second layer, not a guarantee. See [SECURITY.md](SECURITY.md).
+
+## Tools (MCP) and CLI
+
+| tool | what it does |
+|---|---|
+| `start(task, kind, repo, cwd, files, readonly, engine, max_usd, effort, base, max_turns, policy, verify)` | start one job |
+| `start_many(tasks)` | start several; partial success is listed per item |
+| `wait(ids, timeout=300, any=False, since=None)` | block until they end; progress notifications while waiting; `since` cursor for clients without progress |
+| `status(id)` / `result(id, full, evidence)` | one line / summary or full text or JSON envelope |
+| `reply(id, message)` / `stop(id)` / `cleanup(id)` | continue / stop the work / remove a clean worktree (branch kept) |
+| `engines()` | capacity per engine with source, freshness and confidence, plus spend |
+| `step(title, path, how, decisions)` | an independent cheap model narrates the step from the repo's real state |
+
+CLI only: `subtask doctor`, `gc [--apply]`, `du`, `roi`, `routing explain|calibrate`,
+`watch ID...`, `install`, `uninstall`, and `--model`, `--no-sandbox`, `--untrusted` on start.
+
+## Progress in the chat
+
+| client | during a `wait` |
+|---|---|
+| Claude Code 2.1 (TUI) | live line under the tool call, verified |
+| OpenCode 2.0 | notifications received, not shown: use `wait(since=...)` |
+| Kimi Code 2.1 | client does not request progress: `wait(since=...)` |
+| Codex 0.162 | not yet verified (account at its usage limit) |
+
+Details and evidence: [docs/progress-matrix.md](docs/progress-matrix.md).
+
+## Settings
+
+| variable | default |
+|---|---|
+| `SUBTASK_HOME` | `~/.local/share/subtask` (jobs, worktrees, ledger, telemetry) |
+| `SUBTASK_ENV_FILE` | `~/.config/subtask/env` |
+| `SUBTASK_MONTHLY_CAP_USD` / `SUBTASK_DEFAULT_MAX_USD` / `SUBTASK_MAX_JOB_USD` | `180` / `2` / `20` |
+| `SUBTASK_MAX_RUNNING` | `4` (global across all processes) |
+| `SUBTASK_ROUTING` | `~/.config/subtask/routing.json` (weights, `"mode": "legacy"`) |
+| `SUBTASK_JOB_RETENTION_DAYS` / `SUBTASK_TELEMETRY_DAYS` | `30` / `90` |
+| `SUBTASK_PROGRESS_MIN_S` / `SUBTASK_PROGRESS_HEARTBEAT_S` | `2` / `10` |
+
+Costs of API engines come from the SDK's estimate; a run whose real cost is
+unknown is charged its whole reservation. Telemetry stays on this machine.
+
+## Platforms
+
+Linux: supported. macOS: degraded (no `/proc` start times for liveness, no
+bwrap: `isolated` refused). Windows: not supported (`fcntl`).
+
+## Documentation
+
+[Architecture](docs/architecture.md) · [Requirements matrix](docs/requirements.md) ·
+[Benefits and measurements](docs/benefits.md) · [Benchmark protocol](docs/benchmark.md) ·
+[Install](docs/install.md) · [Releasing](RELEASING.md) · [Contributing](CONTRIBUTING.md)
+
+## License
+
+MIT

subtask_mcp-0.2.3/README.md

@@ -0,0 +1,133 @@
+# subtask
+
+<!-- mcp-name: io.github.tedin7/subtask -->
+
+A local delegation scheduler for coding agents. One MCP server (and a twin
+CLI) lets Claude Code, Codex, Kimi Code or OpenCode start work in parallel,
+wait for it with a single call, and read back a short summary with evidence.
+It picks an engine that can take the job, books money and slots safely across
+processes, and says honestly how isolated each run is.
+
+```
+start_many([{task: "Fix the flaky test in tests/test_sync.py", repo: "/src/app", verify: "pytest -q tests/test_sync.py"},
+            {task: "List every caller of parse_date()", kind: "read", readonly: true, cwd: "/src/app"}])
+  -> st-4f2a91 started · sonnet-api · branch subtask/st-4f2a91 · sandbox
+     st-77c0de started · haiku-api · /src/app · readonly
+wait(["st-4f2a91", "st-77c0de"])          # Claude Code shows: Subtask · 01:16 · 1/2 ended — st-4f2a91 running tests: pytest -q
+  -> st-4f2a91 done · sonnet-api · 6m · 0.412$ · verified · ...
+     ## Summary (≤10 lines: the answer, files, commits, tests, what is left)
+result("st-4f2a91", evidence=True)        # JSON: base/head, changed files, observed commands, verify exit code, cost
+```
+
+## Why
+
+- **Save the caller's context.** The worker's search, test runs and dead ends
+  stay in its own session; the caller reads about ten lines.
+- **Few round trips.** `start_many` + one `wait` replace a polling loop.
+- **Use whatever has room.** `engine="auto"` filters engines that can enforce
+  the requested isolation, are installed, fit the budget and have quota, then
+  ranks them with an explicit utility (`subtask routing explain`).
+- **Money is a primitive.** Paid engines reserve their budget before any work,
+  under one lock with the slot; every reservation is closed exactly once.
+- **Evidence, not claims.** `verify="..."` runs your check on the commit the
+  worker left; `result(evidence=True)` separates what subtask observed from
+  what the worker reported.
+
+## Install
+
+The distribution is `subtask-mcp` (the PyPI name `subtask` is an unrelated
+project). Full guide, per client, with native commands: [docs/install.md](docs/install.md).
+
+```sh
+uv tool install "git+https://github.com/tedin7/subtask@v0.2.3"   # or: uv tool install /path/to/checkout
+subtask install --client all          # prints the plan for every detected client
+subtask install --client all --yes    # applies it: MCP server + skill
+subtask doctor --client all           # checks app, config entry and a real handshake
+```
+
+Claude Code plugin: `claude plugin marketplace add tedin7/subtask` then
+`claude plugin install subtask@subtask`. Codex: `codex plugin marketplace add tedin7/subtask`.
+API engines read `ANTHROPIC_API_KEY` from `~/.config/subtask/env` (chmod 600).
+
+## Engines
+
+| engine | pays with | read-only | isolation it can enforce |
+|---|---|---|---|
+| `haiku-api`, `sonnet-api`, `opus-api` | API key, monthly cap | yes | sandbox (Claude Code OS sandbox) |
+| `codex` | Codex login (quota from local session files) | yes | sandbox (`workspace-write`), isolated |
+| `opencode-go` | opencode-go subscription | no | worktree, isolated |
+| `kimi` | Kimi login | no | worktree, isolated |
+| `dsh` | DeepSeek key, same cap (`subtask-mcp[dsh]`) | no | worktree |
+| `opencode` | OpenCode default provider (manual only) | no | worktree, isolated |
+
+Add an engine without touching the core: an `EngineAdapter` registered under the
+`subtask.engines` entry point (see [CONTRIBUTING.md](CONTRIBUTING.md)).
+
+## Isolation, honestly
+
+- `worktree` (default): a git worktree and branch per writing job. It prevents
+  collisions; it is **not** a host sandbox.
+- `sandbox`: the engine's own sandbox. Same user: a guard rail.
+- `isolated`: bubblewrap. Read-only system, writable worktree and git dir only,
+  a private HOME with only the engine's own state. Needs `bwrap`.
+- `untrusted`: sandbox or stronger, and no network for the worker's commands.
+
+A job that cannot get the policy it asked for is refused, never downgraded.
+Output is redacted for common secret formats before it is saved or shown;
+redaction is a second layer, not a guarantee. See [SECURITY.md](SECURITY.md).
+
+## Tools (MCP) and CLI
+
+| tool | what it does |
+|---|---|
+| `start(task, kind, repo, cwd, files, readonly, engine, max_usd, effort, base, max_turns, policy, verify)` | start one job |
+| `start_many(tasks)` | start several; partial success is listed per item |
+| `wait(ids, timeout=300, any=False, since=None)` | block until they end; progress notifications while waiting; `since` cursor for clients without progress |
+| `status(id)` / `result(id, full, evidence)` | one line / summary or full text or JSON envelope |
+| `reply(id, message)` / `stop(id)` / `cleanup(id)` | continue / stop the work / remove a clean worktree (branch kept) |
+| `engines()` | capacity per engine with source, freshness and confidence, plus spend |
+| `step(title, path, how, decisions)` | an independent cheap model narrates the step from the repo's real state |
+
+CLI only: `subtask doctor`, `gc [--apply]`, `du`, `roi`, `routing explain|calibrate`,
+`watch ID...`, `install`, `uninstall`, and `--model`, `--no-sandbox`, `--untrusted` on start.
+
+## Progress in the chat
+
+| client | during a `wait` |
+|---|---|
+| Claude Code 2.1 (TUI) | live line under the tool call, verified |
+| OpenCode 2.0 | notifications received, not shown: use `wait(since=...)` |
+| Kimi Code 2.1 | client does not request progress: `wait(since=...)` |
+| Codex 0.162 | not yet verified (account at its usage limit) |
+
+Details and evidence: [docs/progress-matrix.md](docs/progress-matrix.md).
+
+## Settings
+
+| variable | default |
+|---|---|
+| `SUBTASK_HOME` | `~/.local/share/subtask` (jobs, worktrees, ledger, telemetry) |
+| `SUBTASK_ENV_FILE` | `~/.config/subtask/env` |
+| `SUBTASK_MONTHLY_CAP_USD` / `SUBTASK_DEFAULT_MAX_USD` / `SUBTASK_MAX_JOB_USD` | `180` / `2` / `20` |
+| `SUBTASK_MAX_RUNNING` | `4` (global across all processes) |
+| `SUBTASK_ROUTING` | `~/.config/subtask/routing.json` (weights, `"mode": "legacy"`) |
+| `SUBTASK_JOB_RETENTION_DAYS` / `SUBTASK_TELEMETRY_DAYS` | `30` / `90` |
+| `SUBTASK_PROGRESS_MIN_S` / `SUBTASK_PROGRESS_HEARTBEAT_S` | `2` / `10` |
+
+Costs of API engines come from the SDK's estimate; a run whose real cost is
+unknown is charged its whole reservation. Telemetry stays on this machine.
+
+## Platforms
+
+Linux: supported. macOS: degraded (no `/proc` start times for liveness, no
+bwrap: `isolated` refused). Windows: not supported (`fcntl`).
+
+## Documentation
+
+[Architecture](docs/architecture.md) · [Requirements matrix](docs/requirements.md) ·
+[Benefits and measurements](docs/benefits.md) · [Benchmark protocol](docs/benchmark.md) ·
+[Install](docs/install.md) · [Releasing](RELEASING.md) · [Contributing](CONTRIBUTING.md)
+
+## License
+
+MIT

subtask_mcp-0.2.3/pyproject.toml

@@ -0,0 +1,60 @@
+[project]
+name = "subtask-mcp"
+dynamic = ["version"]
+description = "Background sub-agents for Claude Code, Codex, Kimi and OpenCode, over MCP or CLI, with a spend cap"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+readme = "README.md"
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: POSIX",
+    "Operating System :: POSIX :: Linux",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+]
+dependencies = ["claude-agent-sdk>=0.2", "mcp>=1.28,<2"]
+
+[project.optional-dependencies]
+dsh = ["deepseek-harness-sdk==0.1.5rc1"]
+dev = ["pytest>=8", "ruff>=0.6", "jsonschema>=4", "tqdm>=4"]
+
+[project.urls]
+Homepage = "https://github.com/tedin7/subtask"
+Repository = "https://github.com/tedin7/subtask"
+Issues = "https://github.com/tedin7/subtask/issues"
+
+[project.scripts]
+subtask = "subtask.cli:run"
+subtask-mcp = "subtask.fastserver:main"
+subtask-mcp-fastmcp = "subtask.server:main"
+
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools]
+packages = ["subtask", "subtask.engines", "subtask.install"]
+
+[tool.setuptools.dynamic]
+version = { attr = "subtask.__version__" }
+
+[tool.setuptools.package-data]
+subtask = ["tools.json", "skill/SKILL.md"]
+
+[tool.ruff]
+line-length = 110
+
+[tool.ruff.lint.per-file-ignores]
+"subtask/worker.py" = ["BLE001"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]  # bench/corpus/acceptance targets the frozen 3f731f6, not this tree
+markers = [
+    "contract: offline adapter contract tests",
+    "live: needs real engines and budget (skipped by default)",
+]
+addopts = "-m 'not live'"

subtask_mcp-0.2.3/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

subtask_mcp-0.2.3/subtask/__init__.py

@@ -0,0 +1,3 @@
+"""subtask: background sub-agents for coding agents."""
+
+__version__ = "0.2.3"

subtask_mcp-0.2.3/subtask/admission.py

@@ -0,0 +1,254 @@
+"""Global admission: at most MAX_RUNNING active jobs across every CLI and MCP process.
+
+The active index (<HOME>/active.json) is the source of truth for slots and is
+only changed under <HOME>/admission.lock. It is rebuildable: `rebuild()` scans
+job folders when the index is missing or corrupt. Entries:
+
+  {"job": id, "phase": "admitting"|"running", "owner": identity, "worker": identity|None, "since": ts}
+
+Lock order: a job lock, then admission.lock, then the ledger lock. Nothing
+slow (git, spawn, network) runs while admission.lock is held.
+"""
+
+from __future__ import annotations
+
+import fcntl
+import json
+import os
+import time
+from collections.abc import Iterator
+from contextlib import contextmanager
+from pathlib import Path
+
+from . import config, procid
+
+ADMIT_GRACE_S = 120  # an 'admitting' entry whose owner is alive but silent this long is stale
+
+
+def _index() -> Path:
+    return config.HOME / "active.json"
+
+
+def _markers() -> Path:
+    """One file per job between admission and its first status: survives a corrupt index."""
+    return config.HOME / "admitting"
+
+
+@contextmanager
+def locked() -> Iterator[None]:
+    config.HOME.mkdir(parents=True, exist_ok=True)
+    with (config.HOME / "admission.lock").open("a") as lock:
+        fcntl.flock(lock, fcntl.LOCK_EX)
+        yield
+
+
+def _valid_ident(ident: object) -> bool:
+    if not isinstance(ident, dict):
+        return False
+    try:
+        return int(ident.get("pid")) > 0  # type: ignore[arg-type]
+    except (TypeError, ValueError):
+        return False
+
+
+def _valid_entry(entry: object) -> bool:
+    if not isinstance(entry, dict) or not isinstance(entry.get("job"), str):
+        return False
+    for key in ("owner", "worker"):
+        if entry.get(key) is not None and not _valid_ident(entry[key]):
+            return False
+    return True
+
+
+def _read() -> dict[str, dict] | None:
+    """The index, or None when it is missing or corrupt (callers then rebuild)."""
+    try:
+        data = json.loads(_index().read_text())
+    except (FileNotFoundError, json.JSONDecodeError, OSError, UnicodeDecodeError):
+        return None
+    if not isinstance(data, dict) or not isinstance(data.get("jobs"), dict):
+        return None
+    return {k: v for k, v in data["jobs"].items() if _valid_entry(v)}  # a bad entry is dropped, not fatal
+
+
+def _write(entries: dict[str, dict]) -> None:
+    path = _index()
+    tmp = path.with_suffix(f".{os.getpid()}.tmp")
+    tmp.write_text(json.dumps({"v": 1, "jobs": entries}, indent=1))
+    os.replace(tmp, path)
+
+
+def _mark(entry: dict) -> None:
+    _markers().mkdir(parents=True, exist_ok=True)
+    tmp = _markers() / f".{entry['job']}.{os.getpid()}.tmp"
+    tmp.write_text(json.dumps(entry))
+    os.replace(tmp, _markers() / f"{entry['job']}.json")
+
+
+def _unmark(job_id: str) -> None:
+    (_markers() / f"{job_id}.json").unlink(missing_ok=True)
+
+
+def rebuild() -> dict[str, dict]:
+    """Index from the job folders (queued/running) and the admission markers."""
+    entries: dict[str, dict] = {}
+    if _markers().is_dir():
+        for path in _markers().glob("*.json"):
+            try:
+                entry = json.loads(path.read_text())
+            except (OSError, json.JSONDecodeError):
+                continue
+            if _valid_entry(entry):
+                entries[entry["job"]] = entry
+    if config.JOBS.is_dir():
+        for folder in config.JOBS.iterdir():
+            try:
+                status = json.loads((folder / "status.json").read_text())
+            except (OSError, json.JSONDecodeError):
+                continue
+            if status.get("state") in ("queued", "running"):
+                worker = status.get("proc") or ({"pid": status["pid"]} if status.get("pid") else None)
+                entry = entries.get(folder.name) or {"job": folder.name, "owner": None}
+                entry.update(
+                    phase="running" if worker else entry.get("phase", "running"),
+                    since=status.get("updated", time.time()),
+                )
+                if _valid_ident(worker):
+                    entry["worker"] = worker
+                entries[folder.name] = entry
+    return entries
+
+
+def _live(entry: dict) -> bool:
+    """False only with proof the entry no longer holds a slot."""
+    status, attempt = _job_state(entry["job"]), _job_attempt(entry["job"])
+    newer = entry.get("phase") == "admitting" and int(entry.get("attempt") or 1) > attempt
+    if status in ("done", "failed", "stopped") and not newer:
+        return False
+    if entry.get("phase") == "running":
+        worker = entry.get("worker")
+        if worker:
+            return procid.alive(worker) != procid.DEAD
+        return status in ("queued", "running", None)
+    owner = entry.get("owner")
+    verdict = procid.alive(owner) if owner else procid.UNKNOWN
+    if verdict == procid.DEAD:
+        return False
+    return not (verdict == procid.UNKNOWN and time.time() - float(entry.get("since") or 0) > ADMIT_GRACE_S)
+
+
+def _job_state(job_id: str) -> str | None:
+    try:
+        return json.loads((config.JOBS / job_id / "status.json").read_text()).get("state")
+    except (OSError, json.JSONDecodeError, AttributeError):
+        return None
+
+
+def _job_attempt(job_id: str) -> int:
+    try:
+        return int(json.loads((config.JOBS / job_id / "status.json").read_text()).get("attempt") or 1)
+    except (OSError, json.JSONDecodeError, AttributeError, TypeError, ValueError):
+        return 0
+
+
+def _drop(entry: dict) -> None:
+    """An entry lost its slot. If its job never got a status, nothing ran: release its money."""
+    _unmark(entry["job"])
+    if entry.get("phase") == "admitting" and _job_state(entry["job"]) is None:
+        from . import ledger
+
+        for row in ledger.open_for(entry["job"]):
+            ledger.close(row["rid"], 0.0, "release")
+
+
+def _current() -> dict[str, dict]:
+    entries = _read()
+    if entries is None:
+        entries = rebuild()
+    live = {}
+    for key, entry in entries.items():
+        if _live(entry):
+            live[key] = entry
+        else:
+            _drop(entry)
+    return live
+
+
+def admit(job_id: str, limit: int | None = None, attempt: int = 1) -> str | None:
+    """Take a slot for job_id. None on success, else the refusal reason. Caller holds nothing."""
+    with locked():
+        return admit_locked(job_id, limit, attempt)
+
+
+def admit_locked(job_id: str, limit: int | None = None, attempt: int = 1) -> str | None:
+    """Same as admit() for a caller already holding admission.lock."""
+    limit = config.MAX_RUNNING if limit is None else limit
+    entries = _current()
+    if len(entries) >= limit:
+        _write(entries)
+        return f"{limit} sub-tasks already running: use wait()"
+    entry = {
+        "job": job_id,
+        "attempt": attempt,
+        "phase": "admitting",
+        "owner": procid.identity(),
+        "worker": None,
+        "since": time.time(),
+    }
+    _mark(entry)
+    entries[job_id] = entry
+    _write(entries)
+    return None
+
+
+def running(job_id: str, worker: dict) -> None:
+    with locked():
+        entries = _read()
+        if entries is None:
+            entries = rebuild()
+        entries[job_id] = {
+            **entries.get(job_id, {"job": job_id}),
+            "phase": "running",
+            "worker": worker,
+            "since": time.time(),
+        }
+        _write(entries)
+        _unmark(job_id)
+
+
+def _mine(entry: dict) -> bool:
+    """May the calling process free this entry? Its owner or worker may; anyone may once they are dead."""
+    me = procid.identity()
+    holder = entry.get("worker") if entry.get("phase") == "running" else entry.get("owner")
+    if not holder:
+        return True
+    if int(holder.get("pid", -1)) == me["pid"] and holder.get("start") in (None, me.get("start")):
+        return True
+    return procid.alive(holder) == procid.DEAD
+
+
+def release(job_id: str) -> bool:
+    """Free the job's slot, unless a newer attempt (another live process) holds it now."""
+    with locked():
+        entries = _read()
+        if entries is None:
+            entries = rebuild()
+        entry = entries.get(job_id)
+        if entry is not None and not _mine(entry):
+            return False  # a stale release (e.g. an old worker after a new reply): keep the slot
+        entries.pop(job_id, None)
+        _unmark(job_id)
+        _write(entries)
+        return True
+
+
+def active() -> list[str]:
+    """Jobs holding a slot right now. O(active), not O(history)."""
+    with locked():
+        entries = _current()
+        _write(entries)
+        return list(entries)
+
+
+def count() -> int:
+    return len(active())