subtask-mcp 0.2.3__py3-none-any.whl

subtask/progress.py

@@ -0,0 +1,152 @@
+"""Turn job events into short progress lines while a tool call is running.
+
+`Reporter` is protocol-agnostic: it gets a `send(progress, message, total)`
+callable from the server. It never invents a percentage: `progress` is a
+counter of updates (MCP requires it to grow), the jobs-finished ratio is in
+the message, and elapsed time is wall time of this call (monotonic clock).
+"""
+
+from __future__ import annotations
+
+import os
+import time
+from collections.abc import Callable
+
+from . import events, jobs
+
+MIN_INTERVAL_S = float(os.environ.get("SUBTASK_PROGRESS_MIN_S", "2"))
+HEARTBEAT_S = float(os.environ.get("SUBTASK_PROGRESS_HEARTBEAT_S", "10"))
+NO_DETAIL = "worker running; internal activity not available"
+LABELS = {
+    "admission": "admitting",
+    "worktree": "preparing worktree",
+    "spawn": "starting worker",
+    "start": "worker started",
+    "tool": "",
+    "verify": "verifying",
+    "reply": "resuming",
+}
+
+
+def clock(seconds: float) -> str:
+    seconds = int(max(0, seconds))
+    return (
+        f"{seconds // 60:02d}:{seconds % 60:02d}"
+        if seconds < 3600
+        else f"{seconds // 3600}h{seconds % 3600 // 60:02d}"
+    )
+
+
+class Reporter:
+    """Coalesces events of the given jobs into throttled notifications."""
+
+    def __init__(
+        self,
+        send: Callable[[float, str, float | None], None],
+        ids: list[str] | None = None,
+        label: str = "Subtask",
+        now: Callable[[], float] = time.monotonic,
+        min_interval: float = MIN_INTERVAL_S,
+        heartbeat: float = HEARTBEAT_S,
+    ) -> None:
+        self.send, self.label, self.now = send, label, now
+        self.min_interval, self.heartbeat = min_interval, heartbeat
+        self.t0 = now()
+        self.count = 0
+        self.last_sent = -1e9
+        self.last_text = ""
+        self.ids: list[str] = []
+        self.offsets: dict[str, int] = {}
+        self.activity: dict[str, str] = {}
+        self.states: dict[str, str] = {}
+        self.changed: dict[str, float] = {}  # monotonic time of each job's last real change
+        self.detailed: dict[str, bool] = {}  # True once the engine reported its own activity
+        self.sent_ok = 0
+        self.send_errors = 0
+        for job_id in ids or []:
+            self.add(job_id)
+
+    def add(self, job_id: str) -> None:
+        if job_id not in self.offsets:
+            self.ids.append(job_id)
+            # Start from the current end: only what happens during this call is news.
+            _, self.offsets[job_id] = events.read_since(job_id, 0, limit=10**9)
+            last = events.last(job_id)
+            self.activity[job_id] = _describe(last)
+            self.detailed[job_id] = last.get("source") == "adapter"
+            self.changed[job_id] = self.now()
+
+    def phase(self, text: str, force: bool = False) -> None:
+        """A step of this call itself (admission, worktree...), not of a job."""
+        self._maybe_send(text, significant=True, force=force)
+
+    def poll(self) -> None:
+        significant = False
+        for job_id in self.ids:
+            new, self.offsets[job_id] = events.read_since(job_id, self.offsets[job_id])
+            for event in new:
+                text = _describe(event)
+                if event.get("source") == "adapter":
+                    self.detailed[job_id] = True
+                if text and text != self.activity.get(job_id):
+                    self.activity[job_id] = text
+                    self.changed[job_id] = self.now()
+                    significant = True
+            state = jobs.status(job_id).get("state", "unknown")
+            if state != self.states.get(job_id):
+                self.states[job_id] = state
+                self.changed[job_id] = self.now()
+                significant = True
+        self._maybe_send(self.summary(), significant)
+
+    def summary(self) -> str:
+        if not self.ids:
+            return ""
+        ended = [j for j in self.ids if self.states.get(j) in jobs.FINAL]
+        running = [j for j in self.ids if j not in ended]
+        if len(self.ids) == 1:
+            job = self.ids[0]
+            state = self.states.get(job, "?")
+            if state in jobs.FINAL:
+                return f"{job} {state} — {self.activity.get(job) or state}"
+            return f"{job} — {self._what(job)}"
+        head = f"{len(ended)}/{len(self.ids)} ended"
+        if running:
+            job = max(running, key=lambda j: self.changed.get(j, 0.0))  # the latest real change
+            return f"{head} — {job} {self._what(job)}"
+        failed = sum(1 for j in ended if self.states.get(j) != "done")
+        return f"{head} — {len(ended) - failed} done, {failed} not done"
+
+    def _what(self, job: str) -> str:
+        """The job's latest activity; says so plainly when the engine exposes none."""
+        quiet = self.now() - self.changed.get(job, self.t0) > 5
+        if self.states.get(job) == "running" and not self.detailed.get(job) and quiet:
+            return NO_DETAIL
+        return self.activity.get(job) or NO_DETAIL
+
+    def _maybe_send(self, text: str, significant: bool, force: bool = False) -> None:
+        if not text:
+            return
+        t = self.now()
+        due_change = significant and text != self.last_text and t - self.last_sent >= self.min_interval
+        due_beat = t - self.last_sent >= self.heartbeat
+        if not (force or due_change or due_beat):
+            return
+        self.count += 1
+        self.last_sent, self.last_text = t, text
+        message = f"{self.label} · {clock(t - self.t0)} · {text}"
+        try:
+            self.send(float(self.count), message, None)
+            self.sent_ok += 1
+        except Exception:  # noqa: BLE001 - a broken client never stops the work
+            self.send_errors += 1
+
+
+def _describe(event: dict) -> str:
+    if not event:
+        return ""
+    phase, msg = str(event.get("phase") or ""), str(event.get("msg") or "")
+    if phase == "tool":
+        return msg
+    label = LABELS.get(phase, phase) or ""
+    return f"{label}: {msg}" if msg and label else msg or label

subtask/redact.py

@@ -0,0 +1,61 @@
+"""Remove secrets from text before it is saved or shown.
+
+Not a guarantee: a pattern list cannot recognise every secret. It is one layer
+next to a minimal environment and the isolated runner, never a replacement.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Iterable
+
+MASK = "[REDACTED]"
+
+PATTERNS: list[tuple[str, re.Pattern[str]]] = [
+    (
+        "private-key",
+        re.compile(r"-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z ]*PRIVATE KEY-----"),
+    ),
+    ("anthropic", re.compile(r"sk-ant-[A-Za-z0-9_-]{8,}")),
+    ("openai", re.compile(r"\bsk-(?:proj-|svcacct-|admin-)?[A-Za-z0-9_-]{20,}")),
+    ("github", re.compile(r"\b(?:gh[pousr]_[A-Za-z0-9]{30,}|github_pat_[A-Za-z0-9_]{30,})")),
+    ("gitlab", re.compile(r"\bglpat-[A-Za-z0-9_-]{20,}")),
+    ("aws-key-id", re.compile(r"\b(?:AKIA|ASIA)[A-Z0-9]{16}\b")),
+    ("google", re.compile(r"\bAIza[0-9A-Za-z_-]{35}\b")),
+    ("slack", re.compile(r"\bxox[abprs]-[A-Za-z0-9-]{10,}")),
+    ("stripe", re.compile(r"\b(?:sk|rk)_(?:live|test)_[A-Za-z0-9]{16,}")),
+    ("huggingface", re.compile(r"\bhf_[A-Za-z0-9]{30,}")),
+    ("jwt", re.compile(r"\beyJ[A-Za-z0-9_-]{8,}\.eyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}")),
+    ("url-credentials", re.compile(r"(?<=://)[^/\s:@]+:[^/\s@]{3,}(?=@)")),
+    (
+        "assignment",
+        re.compile(
+            r"(?i)\b([A-Z0-9_]*(?:API_?KEY|SECRET|TOKEN|PASSWORD|PASSWD|CREDENTIAL)[A-Z0-9_]*)"
+            r"(\s*[=:]\s*[\"']?)([^\s\"'`]{8,})"
+        ),
+    ),
+]
+
+_known: set[str] = set()
+
+
+def remember(values: Iterable[str]) -> None:
+    """Exact secret values subtask itself loaded: always masked, whatever their shape."""
+    for value in values:
+        if value and len(value) >= 8:
+            _known.add(value)
+
+
+def redact(text: str) -> str:
+    if not text:
+        return text
+    for value in sorted(_known, key=len, reverse=True):
+        text = text.replace(value, MASK)
+    for name, pattern in PATTERNS:
+        if name == "assignment":
+            text = pattern.sub(lambda m: m.group(1) + m.group(2) + MASK, text)
+        elif name == "anthropic":
+            text = pattern.sub("sk-ant-" + MASK, text)
+        else:
+            text = pattern.sub(MASK, text)
+    return text

subtask/roi.py

@@ -0,0 +1,84 @@
+"""Delegation ROI from local telemetry: separate ratios with units, never one magic number.
+
+What the server can see: worker time, charged/observed cost, outcomes,
+verification, parent round trips, and the size of what the parent read
+(summary) versus what it would have read (full result). It cannot see the
+parent's own context or what the parent would have spent doing the task
+itself: that baseline needs the benchmark harness (bench/e2e.py).
+Token figures here are estimates (bytes / ratio) and are labelled so.
+"""
+
+from __future__ import annotations
+
+import statistics
+from collections import defaultdict
+
+from . import telemetry
+
+RATIOS = (3.0, 4.0, 5.0)  # bytes per token, for the sensitivity line
+
+
+def _median(values: list[float]) -> float | None:
+    return round(statistics.median(values), 1) if values else None
+
+
+def compute(rows: list[dict] | None = None) -> dict:
+    rows = telemetry.rows(months=12) if rows is None else rows
+    groups: dict[tuple[str, str], list[dict]] = defaultdict(list)
+    for row in rows:
+        groups[(row.get("engine") or "?", row.get("kind") or "?")].append(row)
+    out = {}
+    for (engine, kind), items in sorted(groups.items()):
+        jobs = {r.get("job") for r in items}
+        starts = [r for r in items if r.get("attempt_kind") == "start"]
+        verified = [r for r in items if r.get("verified") is True]
+        verified_jobs = {r.get("job") for r in verified}
+        done_unverified = {
+            r.get("job") for r in items if r.get("outcome") == "done" and r.get("verified") is None
+        }
+        first_ok = [r for r in starts if r.get("verified") is True]
+        usd = [float(r["cost_charged"]) for r in items if isinstance(r.get("cost_charged"), (int, float))]
+        paid = any(r.get("cost_reserved") for r in items)
+        saved = [max(0, (r.get("result_bytes") or 0) - (r.get("summary_bytes") or 0)) for r in items]
+        out[f"{engine}/{kind}"] = {
+            "jobs": len(jobs),
+            "attempts": len(items),
+            "replies": sum(1 for r in items if r.get("attempt_kind") == "reply"),
+            "accepted_verified": len(verified_jobs),
+            "done_unverified": len(done_unverified - verified_jobs),
+            "first_attempt_verified_rate": round(len(first_ok) / len(starts), 3) if starts else None,
+            "usd_total_incl_failures": round(sum(usd), 4) if paid else None,
+            "usd_per_accepted": round(sum(usd) / len(verified_jobs), 4) if paid and verified_jobs else None,
+            "billing": "usd" if paid else "subscription/quota (not dollars)",
+            "median_run_s": _median([float(r["run_s"]) for r in items if r.get("run_s") is not None]),
+            "median_queue_s": _median([float(r["queue_s"]) for r in items if r.get("queue_s") is not None]),
+            "context_saved_tokens_est": {f"bytes/{k:g}": int(sum(saved) / k) for k in RATIOS},
+            "summary_tokens_est_bytes/4": int(sum(r.get("summary_bytes") or 0 for r in items) / 4),
+        }
+    return out
+
+
+def report(rows: list[dict] | None = None) -> str:
+    data = compute(rows)
+    if not data:
+        return "no telemetry yet"
+    lines = [
+        (
+            "engine/kind: jobs · verified · done-unverified · 1st-try verified · $ (incl. failures) · $/verified · "
+            "median run · context saved (tokens, est. bytes/4 [3..5])"
+        ),
+    ]
+    for key, d in data.items():
+        saved = d["context_saved_tokens_est"]
+        usd = "-" if d["usd_total_incl_failures"] is None else f"{d['usd_total_incl_failures']}$"
+        per = "-" if d["usd_per_accepted"] is None else f"{d['usd_per_accepted']}$"
+        rate = "-" if d["first_attempt_verified_rate"] is None else f"{d['first_attempt_verified_rate']:.0%}"
+        lines.append(
+            f"{key}: {d['jobs']} · {d['accepted_verified']} · {d['done_unverified']} · {rate} · {usd} · {per} · "
+            f"{d['median_run_s']}s · {saved['bytes/4']} [{saved['bytes/5']}..{saved['bytes/3']}]"
+        )
+    lines.append(
+        "Notes: unverified 'done' is not counted as accepted; subscription engines have no dollar cost here; "
+        "the parent-side baseline (doing it yourself) is measured only by bench/e2e.py."
+    )
+    return "\n".join(lines)

subtask/router.py

@@ -0,0 +1,202 @@
+"""Pick an engine: filter what is admissible, then rank by an explicit utility.
+
+    u = w_success * P(success | engine, kind)          probability 0..1
+      - w_cost    * expected_cost_usd / budget_usd      0..1 (paid engines only)
+      - w_latency * expected_minutes / 60               hours
+      - w_scarcity * (1 - free/100)                     0..1; unknown free -> prior, flagged
+
+P(success) is a prior from the kind's ranking unless the local history has at
+least `min_samples` verified outcomes for that engine and kind. The weights
+are configuration, not a proven optimum: `routing.json` in the config dir.
+`legacy` mode keeps the original heuristic (free% - 5*rank) as a baseline.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+
+from . import capacity, config, ledger, policy, telemetry
+from .engines import registry
+from .engines.base import field, record
+
+# Which engines fit which kind of task, best first. Plain `opencode` is manual-only.
+KINDS = {
+    "read": ["haiku-api", "dsh", "kimi", "opencode-go", "sonnet-api"],
+    "code": ["sonnet-api", "opencode-go", "dsh", "codex", "kimi"],
+    "review": ["sonnet-api", "codex", "kimi"],
+    "hard": ["opus-api", "codex", "sonnet-api"],
+}
+DEFAULTS = {
+    "mode": "utility",
+    "w_success": 100.0,
+    "w_cost": 20.0,
+    "w_latency": 10.0,
+    "w_scarcity": 100.0,
+    "unknown_free_prior": 50.0,
+    "min_free": 10.0,
+    "min_samples": 10,
+    "prior_success_top": 0.8,
+    "prior_success_step": 0.05,
+    "prior_minutes": 10.0,
+    "prior_cost_share": 0.5,
+}
+
+
+def _median(values: list[float]) -> float:
+    ordered = sorted(values)
+    mid = len(ordered) // 2
+    return ordered[mid] if len(ordered) % 2 else (ordered[mid - 1] + ordered[mid]) / 2
+
+
+def settings() -> dict:
+    path = Path(os.environ.get("SUBTASK_ROUTING", config.ENV_FILE.parent / "routing.json"))
+    try:
+        data = json.loads(path.read_text())
+    except (OSError, json.JSONDecodeError):
+        data = {}
+    return {**DEFAULTS, **{k: v for k, v in data.items() if k in DEFAULTS}}
+
+
+@record
+class Option:
+    engine: str
+    admissible: bool
+    why: list[str] = field(default_factory=list)
+    level: str | None = None
+    terms: dict = field(default_factory=dict)
+    utility: float | None = None
+
+
+def _history(kind: str) -> dict[str, list[dict]]:
+    by_engine: dict[str, list[dict]] = {}
+    for row in telemetry.rows():
+        if row.get("kind") == kind and row.get("attempt_kind") == "start":
+            by_engine.setdefault(row.get("engine", "?"), []).append(row)
+    return by_engine
+
+
+def _installed(adapter) -> bool:
+    return adapter.available()
+
+
+def rank(kind: str, max_usd: float | None, wanted: dict) -> list[Option]:
+    cfg = settings()
+    candidates = KINDS.get(kind, KINDS["code"])
+    snap = capacity.snapshot()
+    budget = max_usd or config.DEFAULT_MAX_USD
+    left = config.MONTHLY_CAP_USD - ledger.committed()
+    history = _history(kind) if cfg["mode"] == "utility" else {}
+    options: list[Option] = []
+    for rank_i, name in enumerate(candidates):
+        adapter = registry.get(name)
+        option = Option(name, True)
+        options.append(option)
+        if adapter is None:
+            option.admissible, option.why = False, ["not registered"]
+            continue
+        level, reason = policy.effective(adapter, wanted)
+        option.level = level
+        if level is None:
+            option.admissible = False
+            option.why.append(reason)
+        if not _installed(adapter):
+            option.admissible = False
+            option.why.append(f"{adapter.binary or getattr(adapter, 'module', adapter.name)} not installed")
+        if adapter.capabilities.paid and left < budget:
+            option.admissible = False
+            option.why.append(f"monthly cap: {left:.2f}$ left < {budget:.2f}$ budget")
+        reading = snap.get(name) or {}
+        free = reading.get("value")
+        if free is not None and free < cfg["min_free"]:
+            option.admissible = False
+            option.why.append(f"free {free:.0f}% < {cfg['min_free']:.0f}% ({reading.get('note', '')})")
+        if not option.admissible:
+            continue
+        assumed = free is None
+        free_used = cfg["unknown_free_prior"] if assumed else free
+        if cfg["mode"] == "legacy":
+            option.utility = free_used - rank_i * 5
+            option.terms = {"free": free_used, "free_assumed": assumed, "rank": rank_i}
+            continue
+        rows = history.get(name, [])
+        verified = [r for r in rows if r.get("verified") is not None]
+        if len(verified) >= cfg["min_samples"]:
+            wins = sum(1 for r in verified if r["verified"])
+            p_success, p_src = (wins + 1) / (len(verified) + 2), f"learned n={len(verified)}"
+        else:
+            p_success = max(0.05, cfg["prior_success_top"] - cfg["prior_success_step"] * rank_i)
+            p_src = f"prior (rank {rank_i}, n={len(verified)} < {cfg['min_samples']})"
+        minutes = [r["run_s"] / 60 for r in rows if isinstance(r.get("run_s"), (int, float))]
+        exp_min = _median(minutes) if len(minutes) >= 3 else cfg["prior_minutes"]
+        costs = [r["cost_charged"] for r in rows if isinstance(r.get("cost_charged"), (int, float))]
+        if adapter.capabilities.paid:
+            exp_cost = _median(costs) if len(costs) >= 3 else cfg["prior_cost_share"] * budget
+        else:
+            exp_cost = 0.0  # subscription or unknown: its scarcity is the quota term, not dollars
+        scarcity = 1 - free_used / 100
+        option.terms = {
+            "p_success": round(p_success, 3), "p_source": p_src,
+            "exp_cost_usd": round(exp_cost, 3), "exp_minutes": round(exp_min, 1),
+            "free_pct": round(free_used, 1), "free_assumed": assumed,
+            "free_source": reading.get("source"), "free_confidence": reading.get("confidence"),
+        }  # fmt: skip
+        option.utility = round(
+            cfg["w_success"] * p_success
+            - cfg["w_cost"] * min(1.0, exp_cost / budget)
+            - cfg["w_latency"] * exp_min / 60
+            - cfg["w_scarcity"] * scarcity,
+            2,
+        )
+    return sorted(options, key=lambda o: (o.admissible, o.utility or -1e9), reverse=True)
+
+
+def pick(
+    kind: str = "code", max_usd: float | None = None, wanted: dict | None = None
+) -> tuple[str, str, list[Option]]:
+    """(engine, one-line reason, full ranking). engine '' when nothing is admissible."""
+    wanted = wanted or policy.demand()
+    options = rank(kind, max_usd, wanted)
+    best = next((o for o in options if o.admissible), None)
+    if best is None:
+        why = "; ".join(f"{o.engine}: {', '.join(o.why)}" for o in options)
+        return "", f"no engine can take a {kind} task ({why})"[:400], options
+    t = best.terms
+    if "p_success" in t:
+        reason = (
+            f"{kind} → {best.engine} (u={best.utility}: P={t['p_success']} {t['p_source']}, "
+            f"free {t['free_pct']:.0f}%{' assumed' if t['free_assumed'] else ''}, ~{t['exp_cost_usd']}$, "
+            f"~{t['exp_minutes']}m, level {best.level})"
+        )
+    else:
+        reason = (
+            f"{kind} → {best.engine} (legacy: free {t['free']:.0f}%, rank {t['rank']}, level {best.level})"
+        )
+    return best.engine, reason, options
+
+
+def explain(kind: str, max_usd: float | None = None, wanted: dict | None = None) -> str:
+    _, reason, options = pick(kind, max_usd, wanted)
+    lines = [reason]
+    for o in options:
+        mark = "✓" if o.admissible else "✗"
+        lines.append(f"{mark} {o.engine:12} u={o.utility} {o.terms or ''} {'; '.join(o.why)}"[:220])
+    return "\n".join(lines)
+
+
+def calibrate() -> str:
+    """Success counts per engine and kind from verified outcomes; which cells are learned."""
+    cfg = settings()
+    table: dict[tuple[str, str], list[bool]] = {}
+    for row in telemetry.rows(months=12):
+        if row.get("verified") is not None and row.get("attempt_kind") == "start":
+            table.setdefault((row.get("engine", "?"), row.get("kind", "?")), []).append(bool(row["verified"]))
+    if not table:
+        return "no verified outcomes yet: routing uses priors (start jobs with verify= to collect them)"
+    lines = []
+    for (engine, kind), wins in sorted(table.items()):
+        n = len(wins)
+        state = "learned" if n >= cfg["min_samples"] else f"prior (needs {cfg['min_samples']})"
+        lines.append(f"{engine:12} {kind:7} n={n:3} success={sum(wins) / n:.0%} → {state}")
+    return "\n".join(lines)

subtask/runners.py

@@ -0,0 +1,99 @@
+"""How the engine process is launched: directly, or inside a bubblewrap sandbox.
+
+The isolated runner is a real boundary for the filesystem: the engine sees a
+read-only system, its worktree and git dir, and a private HOME that only holds
+the engine's own state directories. It does not hide the engine's own
+credentials from the engine (it needs them), and model traffic keeps the network.
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+from pathlib import Path
+
+SYSTEM_RO = ["/usr", "/bin", "/sbin", "/lib", "/lib64", "/lib32", "/etc", "/opt", "/nix", "/snap"]
+BASE_ENV = ("PATH", "LANG", "LC_ALL", "TERM", "TZ", "SSL_CERT_FILE", "SSL_CERT_DIR", "NODE_EXTRA_CA_CERTS")
+
+# Per engine family: state directories under HOME the engine needs (read-write).
+STATE_DIRS = {
+    "codex": [".codex"],
+    "kimi": [".kimi-code", ".kimi", ".config/kimi", ".local/share/kimi", ".cache/kimi"],
+    "opencode": [".local/share/opencode", ".config/opencode", ".cache/opencode", ".local/state/opencode"],
+    "api": [".claude", ".claude.json"],
+}
+
+
+def minimal_env(extra: dict[str, str] | None = None) -> dict[str, str]:
+    env = {k: os.environ[k] for k in BASE_ENV if k in os.environ}
+    env["HOME"] = str(Path.home())
+    env.setdefault("PATH", "/usr/local/bin:/usr/bin:/bin")
+    env.update(extra or {})
+    return env
+
+
+def bwrap_available() -> bool:
+    """bwrap installed AND able to create its namespaces here (some hosts forbid user namespaces)."""
+    exe = shutil.which("bwrap")
+    if not exe:
+        return False
+    import subprocess
+
+    try:
+        done = subprocess.run(
+            [exe, "--ro-bind", "/", "/", "--unshare-pid", "--", "true"],
+            capture_output=True, timeout=10, check=False,
+        )  # fmt: skip
+    except (OSError, subprocess.TimeoutExpired):
+        return False
+    return done.returncode == 0
+
+
+def direct(argv: list[str], env: dict[str, str]) -> tuple[list[str], dict[str, str]]:
+    return argv, env
+
+
+def isolated(spec: dict, family: str):
+    """A wrap() for RunContext that runs argv under bwrap, or raises if bwrap is missing."""
+    bwrap = shutil.which("bwrap")
+    if not bwrap or not bwrap_available():
+        raise RuntimeError("policy isolated needs a working bubblewrap (bwrap); refusing to run unisolated")
+    home = Path.home()
+
+    def wrap(argv: list[str], env: dict[str, str]) -> tuple[list[str], dict[str, str]]:
+        args = [
+            bwrap,
+            "--die-with-parent",
+            "--new-session",
+            "--unshare-pid",
+            "--unshare-ipc",
+            "--unshare-uts",
+        ]
+        for path in SYSTEM_RO:
+            if os.path.exists(path):
+                args += ["--ro-bind", path, path]
+        args += ["--proc", "/proc", "--dev", "/dev", "--tmpfs", "/tmp", "--tmpfs", str(home)]
+        exe = shutil.which(argv[0], path=env.get("PATH"))
+        if exe:
+            for candidate in {Path(exe).parent, Path(exe).resolve().parent}:
+                if not any(str(candidate).startswith(p + "/") or str(candidate) == p for p in SYSTEM_RO):
+                    # the engine binary lives outside the system dirs (e.g. ~/.local/bin): read-only
+                    args += ["--ro-bind-try", str(candidate), str(candidate)]
+            real = Path(exe).resolve()
+            if home in real.parents:
+                parts = real.relative_to(home).parts
+                depth = 3 if parts[0] == ".local" else 1  # ~/.local/share/<tool>, or ~/.<tool>
+                if len(parts) > depth:
+                    root = home.joinpath(*parts[:depth])
+                    args += ["--ro-bind-try", str(root), str(root)]
+        for rel in STATE_DIRS.get(family, []):
+            target = home / rel
+            if target.exists():
+                args += ["--bind", str(target), str(target)]
+        for key in ("cwd", "git_dir"):
+            if spec.get(key):
+                args += ["--bind", spec[key], spec[key]]
+        args += ["--chdir", spec["cwd"], "--setenv", "HOME", str(home), "--"]
+        return args + argv, env
+
+    return wrap