handcode 0.3.0rc1__py3-none-any.whl

agentctl/runtime/doctor.py

@@ -0,0 +1,335 @@
+r"""Preflight: what is ready, what is missing, what will stop you.
+
+Built because a run burned fifteen tool calls and produced nothing, and the
+only signal was a `RateLimitError` traceback thirty lines deep ending in
+*"please file a bug report at github.com/OpenHands"* — which is not where the
+problem was.
+
+Everything here is free and offline except the provider probe, which reads your
+own account status and costs no model request.
+
+## What this check fetches, and what it doesn't
+
+This module's own OpenRouter check calls `/api/v1/auth/key`, which reports
+dollar usage and free-tier status but not the remaining daily count. That was
+recorded here as unknowable by any free endpoint -- checked again on
+2026-09-21 and found false. The sibling endpoint `/api/v1/key` exposes it
+directly, at the same cost (zero) and with the same auth
+(`probe.py::openrouter_quota`, `free_model_daily_requests:
+{used, limit, remaining}`, confirmed live across six accounts). This check
+still does not call it -- that number belongs in `agentctl dash`, not in a
+preflight -- but it no longer claims the number cannot be known.
+"""
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+# Derived, never duplicated. `doctor` and `proxy` each kept their own provider
+# list until one registry replaced both -- two lists drift, and drift here
+# means a key you added is checked by one command and ignored by another. The
+# same defect as `docs/0029` §4.
+def _provider_rows() -> list[tuple[str, str, str]]:
+    from agentctl.control.providers import PROVIDERS as _P
+    return [(p.key, p.name,
+             "free tier available" if p.free_tier else "paid") for p in _P]
+
+
+PROVIDERS = _provider_rows()
+
+OK, WARN, BAD = "ok", "!!", "XX"
+
+
+# ── Groq's turn-2 ceiling (`docs/0038` §4.1, `research/phase-10-2` V3-V5, I1) ──
+# Three separately-dated facts. The conclusion below is COMPUTED from them,
+# never written down as a bare number, so updating one fact updates the
+# conclusion instead of leaving a stale headline behind.
+#
+# VERIFIED, in this repo, reproducible offline with no network and no key --
+# `tests/test_doctor_groq_prefix.py` re-measures both live and fails if
+# either has drifted from the constant pinned here:
+_FIXED_PREFIX_TOKENS = 3_593         # 3,208 system prompt + 385 tool schemas
+_PREFIX_MEASURED = "2026-09-20, openhands-sdk 1.45.0"
+#
+# _FIXED_PREFIX_TOKENS is environment-dependent by about two tokens: 3,593
+# measured on Windows, 3,591 on Linux CI, same commit and same encoding. The
+# cause is not identified -- neither the system prompt nor the tool schemas
+# contain an OS string or a path. It does not move the conclusion (311 tokens
+# of headroom versus 313, both far below one turn), and
+# tests/test_doctor_groq_prefix.py asserts the conclusion rather than the
+# constant for exactly that reason.
+#
+_RUNNER_MAX_OUTPUT_TOKENS = 4_096    # mirrors runtime/runner.py:221 -- not
+                                      # importable, no constant exists there;
+                                      # the same test pins this one too.
+#
+# INFERRED, external to this repo, and NOT re-checked by the test suite --
+# dated so it is visibly different in kind from the two facts above. Source
+# tier T3 (issue trackers + one article): Groq's own rate-limits page frames
+# TPM as a budget but does not state the prompt+max_tokens mechanism in so
+# many words. This can go stale or turn out wrong without this repo noticing.
+_GROQ_TPM_CEILING = 8_000
+_GROQ_TPM_SOURCE = "console.groq.com/docs/rate-limits, checked 2026-09-20"
+
+
+def _groq_headroom(accts: list) -> tuple[str, str, str] | None:
+    """How much of Groq's TPM ceiling is left for conversation, and whether
+    Groq is all the user has.
+
+    Returns None when no Groq account is configured — nothing to warn about.
+    Status is WARN, never BAD: turn 1 does work, and the failure mode is
+    INFERRED, not observed from this repo (`docs/0038` §4.1, confirmed by an
+    independent re-check at §9.3, not yet confirmed by an actual `agentctl
+    run` against Groq). BAD means "this will not work"; this means "it likely
+    won't work past turn 1," a different claim.
+    """
+    groq = [a for a in accts if a.provider.name == "groq"]
+    if not groq:
+        return None
+
+    n_groq = len(groq) * len(groq[0].provider.models)
+    # Deployments in the POOL, not credentials held. Counting every
+    # account folds in providers that cannot serve -- six Cerebras
+    # keys that 402 on every completion, one paid Anthropic key that
+    # is never called -- and hides them inside the reassuring
+    # remainder ("the other N carry no such limit"). That is the
+    # accounts-held-vs-deployments-served conflation `docs/0038` 9.4
+    # was written to diagnose, reappearing one file over (`docs/0039`).
+    n_total = sum(len(a.provider.models) for a in accts
+                  if a.provider.free_tier)
+    headroom = _GROQ_TPM_CEILING - _RUNNER_MAX_OUTPUT_TOKENS - _FIXED_PREFIX_TOKENS
+
+    only = (" Groq is the only provider you have configured — there is no "
+            "other deployment in your pool that carries a real conversation."
+            if len(groq) == len(accts) else "")
+
+    detail = (
+        f"{n_groq} of {n_total} configured deployment(s) are Groq.{only} "
+        f"Groq's published free-tier limit ({_GROQ_TPM_CEILING:,} tok/min, "
+        f"metered on prompt+max_tokens — {_GROQ_TPM_SOURCE}, INFERRED "
+        f"mechanism, not this repo's own test) leaves ~{headroom} tokens of "
+        f"conversation after this repo's measured {_FIXED_PREFIX_TOKENS:,}-"
+        f"tok system prompt + tool schemas ({_PREFIX_MEASURED}) and "
+        f"runner.py's max_output_tokens={_RUNNER_MAX_OUTPUT_TOKENS} — turn 2 "
+        f"of most real tasks will 413. The other {n_total - n_groq} "
+        f"deployment(s) carry no documented version of this limit, which is "
+        f"not the same as a clean bill of health — providers.py deliberately "
+        f"records no rate limits for anyone. Unconfirmed by a live call from "
+        f"this repo — falsify: agentctl run --model "
+        f"groq/openai/gpt-oss-120b <a trivial task>, watch turn 2."
+    )
+    return (WARN, "groq headroom", detail)
+
+
+def _model() -> list[tuple[str, str, str]]:
+    """Which model `agentctl run` will use with no flags, and why that one."""
+    try:
+        from agentctl.runtime.config import resolve
+        s = resolve("model", None)
+    except SystemExit as e:                             # a broken config.toml
+        return [(BAD, "model", str(e).splitlines()[0])]
+    except Exception as e:                              # noqa: BLE001
+        return [(WARN, "model", f"could not resolve: {e}")]
+    if s.value is None:
+        return [(WARN, "model", "none -- run `agentctl init`")]
+    return [(OK, "model", f"{s.value}  ({s.source})")]
+
+
+def check_all(workspace: str | Path | None = None,
+              probe_network: bool = True) -> list[tuple[str, str, str]]:
+    """[(status, subject, detail)] — never raises, always reports."""
+    out: list[tuple[str, str, str]] = []
+    out += _packages()
+    out += _providers(probe_network)
+    out += _model()
+    out += _tooling()
+    out += _policy()
+    if workspace:
+        out += _workspace(Path(workspace))
+    return out
+
+
+# ── checks ─────────────────────────────────────────────────────────────
+def _packages() -> list[tuple[str, str, str]]:
+    from importlib.metadata import version
+
+    # Versions are reported, never judged. `mcp >= 2` used to be BAD here
+    # (docs/0021 §7: litellm[proxy] once downgraded it and broke the SDK), and
+    # it outlived its premise: SDK 1.50.1 resolves to mcp 1.30 and imports
+    # cleanly, so a fresh install from the README was told to stop by a rule
+    # the next two rows contradicted (docs/0044 N5). The import rows below
+    # test what actually breaks, on whatever versions pip chose.
+    rows = []
+    for pkg in ("openhands-sdk", "litellm", "mcp", "fastmcp", "pyyaml"):
+        try:
+            rows.append((OK, pkg, version(pkg)))
+        except Exception:                               # noqa: BLE001
+            rows.append((BAD, pkg, "not installed"))
+
+    try:
+        from fastmcp import Client                      # noqa: F401
+        rows.append((OK, "fastmcp client", "importable"))
+    except Exception as e:                              # noqa: BLE001
+        # `import fastmcp` alone succeeds even when this is broken (docs/0028).
+        rows.append((BAD, "fastmcp client", f"{type(e).__name__}: {e}"))
+
+    try:
+        from openhands.sdk.event.base import Event      # noqa: F401
+        rows.append((OK, "openhands sdk", "imports cleanly"))
+    except Exception as e:                              # noqa: BLE001
+        rows.append((BAD, "openhands sdk", f"{type(e).__name__}: {e}"))
+    return rows
+
+
+def _keys_file() -> list[tuple[str, str, str]]:
+    """Is the keys file exposed to git? The guard nobody thinks to run.
+
+    `keys.py` documents this as one of three guards, and it was not actually
+    wired anywhere until the docstring was checked against the code.
+    """
+    from agentctl.control.keys import check_not_tracked, resolve
+
+    p = resolve()
+    if p is None:
+        return [(WARN, "keys file",
+                 "none found — run: agentctl init")]
+    if (warn := check_not_tracked(p)):
+        return [(BAD, "keys file", warn)]
+    return [(OK, "keys file", f"{p} (not exposed to git)")]
+
+
+def _providers(probe: bool) -> list[tuple[str, str, str]]:
+    from agentctl.control.providers import all_accounts
+
+    rows = _keys_file()
+    accts = all_accounts()
+    for a in accts:
+        rows.append((OK, a.label,
+                     f"{a.env} set "
+                     f"({'free tier' if a.provider.free_tier else 'paid'})"))
+
+    if not accts:
+        rows.append((BAD, "providers", "no API key in the environment"))
+        return rows
+
+    providers = {a.provider.name for a in accts}
+    if len(accts) == 1:
+        # One account cannot fail over. The advice is a second PROVIDER: a
+        # second key at the same one is unverified as a second quota and
+        # unchecked against terms of service (docs/0042 §4.C, 0044 N9).
+        rows.append((WARN, "failover",
+                     f"only {accts[0].label} — fine to start with; a daily "
+                     f"cap on it stops work until it resets. A key at a "
+                     f"second provider survives that (`agentctl keys`)."))
+    elif len(providers) == 1:
+        rows.append((WARN, "failover",
+                     f"{len(accts)} accounts, all at "
+                     f"{next(iter(providers))} — survives a cap, not the "
+                     f"provider going down."))
+
+    # Offline, no network — runs regardless of `probe`.
+    if (row := _groq_headroom(accts)) is not None:
+        rows.append(row)
+
+    if probe and os.environ.get("OPENROUTER_API_KEY"):
+        rows.append(_openrouter())
+    return rows
+
+
+def _openrouter() -> tuple[str, str, str]:
+    """Read our own account. No model request, so it costs nothing."""
+    import urllib.request
+
+    key = os.environ["OPENROUTER_API_KEY"]
+    try:
+        req = urllib.request.Request(
+            "https://openrouter.ai/api/v1/auth/key",
+            headers={"Authorization": f"Bearer {key}"})
+        with urllib.request.urlopen(req, timeout=15) as fh:
+            d = json.loads(fh.read())["data"]
+    except Exception as e:                              # noqa: BLE001
+        return (WARN, "openrouter", f"could not reach: {type(e).__name__}")
+
+    if d.get("is_free_tier"):
+        return (WARN, "openrouter quota",
+                "FREE TIER: 50 model requests/day, account-wide across every "
+                "`:free` model. This check reports free-tier status only; "
+                "the live remaining count is exposed separately by "
+                "`probe.py::openrouter_quota` (GET /api/v1/key) for callers "
+                "that want it.")
+    return (OK, "openrouter quota",
+            f"paid key, ${float(d.get('usage') or 0):.4f} used")
+
+
+def _tooling() -> list[tuple[str, str, str]]:
+    rows = []
+    git = shutil.which("git")
+    rows.append((OK, "git", git) if git else
+                (BAD, "git", "not on PATH — the git probe and chaos suite need it"))
+    rows.append((OK, "python", sys.version.split()[0]))
+    if sys.version_info < (3, 12):
+        rows[-1] = (BAD, "python", f"{sys.version.split()[0]} — needs >= 3.12")
+    return rows
+
+
+def _policy() -> list[tuple[str, str, str]]:
+    from agentctl.kernel.policy import DEFAULT_POLICY, Policy
+
+    if not DEFAULT_POLICY.exists():
+        return [(WARN, "policy", "not compiled — run: agentctl policy "
+                                 "agentctl/control/policy/data/policy.yaml")]
+    try:
+        p = Policy.load()
+    except Exception as e:                              # noqa: BLE001
+        return [(BAD, "policy", f"compiled artifact unreadable: {e}")]
+    caps = ", ".join(f"{s} ${p.limit(s):.2f}" for s in ("per_task", "daily")
+                     if p.limit(s) is not None)
+    return [(OK, "policy", f"{caps or 'no caps'} | "
+                           f"destructive: {p.effect_rule('DESTRUCTIVE') or '-'}")]
+
+
+def _workspace(ws: Path) -> list[tuple[str, str, str]]:
+    rows = []
+    if not ws.exists():
+        return [(WARN, "workspace", f"{ws} does not exist yet")]
+    try:
+        probe = ws / ".agentctl_write_probe"
+        probe.write_text("x", encoding="utf-8")
+        probe.unlink()
+        rows.append((OK, "workspace", f"{ws} (writable)"))
+    except Exception as e:                              # noqa: BLE001
+        rows.append((BAD, "workspace", f"{ws} not writable: {e}"))
+
+    if (ws / ".git").exists():
+        dirty = subprocess.run(["git", "status", "--porcelain"], cwd=str(ws),
+                               capture_output=True, text=True).stdout.strip()
+        rows.append((WARN, "uncommitted", f"{len(dirty.splitlines())} changed "
+                     f"file(s) — the agent edits real files; commit first")
+                    if dirty else (OK, "git tree", "clean"))
+    else:
+        rows.append((WARN, "git", f"{ws} is not a git repo — no way to undo "
+                                  f"what the agent writes"))
+
+    led = ws / ".agentctl" / "ledger.db"
+    if led.exists():
+        rows.append((OK, "ledger", f"{led}  (agentctl --ledger <path> status)"))
+    return rows
+
+
+def report(rows: list[tuple[str, str, str]]) -> int:
+    """Print, and return an exit code. Any BAD is a failure."""
+    width = max((len(s) for _, s, _ in rows), default=10)
+    for status, subject, detail in rows:
+        print(f"  {status:<4} {subject:<{width}}  {detail}")
+    bad = [r for r in rows if r[0] == BAD]
+    warn = [r for r in rows if r[0] == WARN]
+    print()
+    if bad:
+        print(f"  {len(bad)} blocking problem(s). Fix these before running.")
+        return 1
+    print(f"  ready{f' — {len(warn)} warning(s) worth reading' if warn else ''}")
+    return 0

agentctl/runtime/init.py

@@ -0,0 +1,148 @@
+"""`agentctl init`: from one key to a working default, in one command.
+
+`docs/0043` Phase 2. Phase 0 (`docs/0044`) took a new user nine commands and
+two false "it will not work" verdicts to reach a first task. This is the
+middle of the three commands the plan promises:
+
+    pip install ...            (once)
+    agentctl init              this
+    agentctl run "<task>"      in any git repository
+
+What it does, in order, and nothing else:
+
+1. **Find a key.** One already in the environment or a keys file is used. With
+   none, it asks which provider and reads the key without echoing it, into
+   `~/.agentctl/keys.env` -- outside every repository, ignored first.
+2. **Prove it.** One completion, through the same check as `keys --check`,
+   which tries each registry model past a dead one (`docs/0044` N6). The
+   model that ANSWERED is the one recorded: a default chosen by a completion,
+   not by a list.
+3. **Record it** in `~/.agentctl/config.toml`, which `run` reads.
+
+A paid provider is not called unless asked (`docs/0002` §5: never silently
+spend), and then it costs one four-token completion.
+"""
+from __future__ import annotations
+
+import getpass
+import os
+import sys
+
+from agentctl.runtime import config
+
+
+def _ask(prompt: str) -> str:
+    try:
+        return input(prompt).strip()
+    except EOFError:
+        return ""
+
+
+def _choose(interactive: bool):
+    """A provider the user picks, free tiers first. None if they do not."""
+    from agentctl.control.providers import PROVIDERS
+
+    order = sorted(PROVIDERS, key=lambda p: (not p.free_tier, PROVIDERS.index(p)))
+    print("  No provider key found. Pick one to start with -- one is enough:\n")
+    for i, p in enumerate(order, 1):
+        print(f"    {i}. {p.name:<11} {'free tier' if p.free_tier else 'PAID'}"
+              f"   {p.console}")
+    print()
+    if not interactive:
+        return None
+    answer = _ask(f"  provider [1-{len(order)}, default 1]: ") or "1"
+    try:
+        return order[int(answer) - 1]
+    except (ValueError, IndexError):
+        from agentctl.control.providers import BY_NAME
+        return BY_NAME.get(answer.lower())
+
+
+def _store_key(p, value: str) -> None:
+    from agentctl.control.keys import HOME_PATH, set_value
+
+    path = set_value(HOME_PATH, p.key, value)
+    os.environ[p.key] = value
+    print(f"  saved         {p.key} -> {path}  (never printed, outside any repo)")
+
+
+def run_init(provider: str | None = None, model: str | None = None,
+             verify: bool = True, key_stdin: bool = False,
+             check_paid: bool = False, interactive: bool | None = None) -> int:
+    from agentctl.control.providers import BY_NAME, configured
+
+    if interactive is None:
+        interactive = sys.stdin.isatty()
+    print("agentctl init\n")
+
+    # ── 1. a key ────────────────────────────────────────────────────────
+    if provider:
+        p = BY_NAME.get(provider.lower())
+        if p is None:
+            print(f"  no provider called {provider!r}. Known: "
+                  f"{', '.join(BY_NAME)}")
+            return 2
+    else:
+        have = configured()
+        p = have[0] if have else _choose(interactive and not key_stdin)
+
+    if p is None:
+        print("  Non-interactive, and no key in the environment. Either:")
+        print("    export OPENROUTER_API_KEY=...        then  agentctl init")
+        print("    agentctl init --provider openrouter --key-stdin < keyfile")
+        return 2
+
+    if not p.configured:
+        print(f"  {p.name}: create a key at {p.console}")
+        for step in p.steps:
+            print(f"    - {step}")
+        if key_stdin:
+            value = sys.stdin.readline().strip()
+        elif interactive:
+            value = getpass.getpass(f"  paste your {p.key} (not shown): ").strip()
+        else:
+            value = ""
+        if not value:
+            print(f"\n  no key given. Set {p.key} and run `agentctl init` again.")
+            return 2
+        _store_key(p, value)
+    else:
+        print(f"  key           {p.key} (already set)")
+
+    # ── 2. prove it ────────────────────────────────────────────────────
+    chosen, how = model or p.default_model, "registry default, not checked"
+    if model:
+        how = "given with --model"
+    elif not verify:
+        how = "registry default; --no-verify, so not checked"
+    elif not p.free_tier and not check_paid:
+        how = ("registry default; not checked -- a paid provider is called "
+               "only with --check-paid (one 4-token completion)")
+    else:
+        from agentctl.control.probe import LIMITED, LIVE, check_inference
+
+        print(f"  checking      one completion against {p.name} ...")
+        r = check_inference(p.name, allow_paid=check_paid)
+        if r is not None and r.status == LIVE and r.model:
+            chosen, how = f"{p.prefix}{r.model}", "answered a completion just now"
+        elif r is not None and r.status == LIMITED:
+            how = ("the key works but is rate limited right now; registry "
+                   "default recorded, unchecked")
+        else:
+            print(f"  !! {p.name} cannot serve a request: "
+                  f"{r.detail if r else 'no model to check'}")
+            print(f"     the key is saved; nothing else was changed. Check it at "
+                  f"{p.console}, then run `agentctl init` again.")
+            return 1
+
+    # ── 3. record it ───────────────────────────────────────────────────
+    cfg = config.load()
+    cfg["model"] = chosen
+    path = config.write(cfg, note=f"model: {how}")
+    print(f"  model         {chosen}")
+    print(f"                ({how})")
+    print(f"  config        {path}")
+    print()
+    print("  Ready. In any git repository:")
+    print('    agentctl run "describe what this repository does"')
+    return 0

agentctl/runtime/lease.py

@@ -0,0 +1,143 @@
+"""Who holds a conversation's lease, and whether they are still alive.
+
+`docs/0042` I-02. `--resume` used to pass `takeover=True` unconditionally, so a
+second terminal could steal the lease from a run that was still working, and
+two processes drove one conversation: one event history, two writers.
+
+The fix keeps "crash, then resume" frictionless and refuses the dangerous
+case. Holders are named `run@<host>:<pid>`, so a resume can ask whether the
+holder is alive:
+
+    holder dead (same host)      take over -- a crashed process cannot
+                                 release its own lease, and waiting out the
+                                 TTL helps nobody
+    holder alive, or unknowable  refuse and name it; `--takeover` overrides
+    lease expired or released    nothing to steal
+
+"Unknowable" counts as alive: a holder on another host, or a name not in this
+format. Taking over from a live process is the failure; waiting is only slow.
+"""
+from __future__ import annotations
+
+import os
+import socket
+import sys
+import time
+from dataclasses import dataclass
+from pathlib import Path
+
+PREFIX = "run@"
+
+
+def holder_id(pid: int | None = None) -> str:
+    """This process's lease holder name."""
+    return f"{PREFIX}{socket.gethostname()}:{pid or os.getpid()}"
+
+
+def _parse(holder: str) -> tuple[str, int] | None:
+    if not holder.startswith(PREFIX) or ":" not in holder:
+        return None
+    host, _, pid = holder[len(PREFIX):].rpartition(":")
+    try:
+        return host, int(pid)
+    except ValueError:
+        return None
+
+
+def pid_alive(pid: int) -> bool:
+    """Is a process with this pid running on this machine?
+
+    Never `os.kill(pid, 0)` on Windows: there, `os.kill` with any signal other
+    than the two console events calls TerminateProcess. A liveness check that
+    kills what it checks would be a remarkable way to fail.
+    """
+    if pid <= 0:
+        return False
+    if sys.platform == "win32":
+        import ctypes
+        from ctypes import wintypes
+
+        k32 = ctypes.WinDLL("kernel32", use_last_error=True)
+        k32.OpenProcess.restype = wintypes.HANDLE
+        k32.OpenProcess.argtypes = (wintypes.DWORD, wintypes.BOOL, wintypes.DWORD)
+        k32.GetExitCodeProcess.argtypes = (wintypes.HANDLE,
+                                           ctypes.POINTER(wintypes.DWORD))
+        k32.CloseHandle.argtypes = (wintypes.HANDLE,)
+        PROCESS_QUERY_LIMITED_INFORMATION, STILL_ACTIVE = 0x1000, 259
+        handle = k32.OpenProcess(PROCESS_QUERY_LIMITED_INFORMATION, False, pid)
+        if not handle:
+            # ERROR_ACCESS_DENIED means it exists and is someone else's.
+            return ctypes.get_last_error() == 5
+        try:
+            code = wintypes.DWORD()
+            if not k32.GetExitCodeProcess(handle, ctypes.byref(code)):
+                return True                     # cannot tell: assume alive
+            return code.value == STILL_ACTIVE
+        finally:
+            k32.CloseHandle(handle)
+    try:
+        os.kill(pid, 0)
+    except ProcessLookupError:
+        return False
+    except PermissionError:
+        return True                             # exists, not ours
+    return True
+
+
+def holder_alive(holder: str) -> bool | None:
+    """True / False when this machine can tell; None when it cannot."""
+    parsed = _parse(holder)
+    if parsed is None:
+        return None
+    host, pid = parsed
+    if host != socket.gethostname():
+        return None
+    return pid_alive(pid)
+
+
+@dataclass(frozen=True)
+class Claim:
+    """What a resume should do about the lease."""
+    takeover: bool
+    note: str = ""
+
+
+class StillRunning(SystemExit):
+    """The conversation's holder is alive. Refuse, and say who and how."""
+
+
+def claim(ledger: str | Path, conversation_id: str, *,
+          force: bool = False) -> Claim:
+    """Decide whether resuming `conversation_id` may take its lease.
+
+    Reads the lease and nothing else; `protect()` then acquires with the
+    answer. Between the two, another process could still take it -- in which
+    case `acquire` raises `LeaseHeld`, which is the same refusal.
+    """
+    from agentctl.kernel.ledger.store import LedgerStore
+
+    p = Path(ledger)
+    if not p.exists():
+        return Claim(False)
+    with LedgerStore(p, holder="claim") as s:
+        row = s.lease(conversation_id)
+    if row is None or row["expires_at"] <= time.time():
+        return Claim(False)
+
+    holder, left = row["holder"], row["expires_at"] - time.time()
+    alive = holder_alive(holder)
+    if alive is False:
+        return Claim(True, f"the run that held it ({holder}) is gone; "
+                           f"taking over")
+    if force:
+        return Claim(True, f"--takeover: stealing the lease from {holder}, "
+                           f"which {'is ALIVE' if alive else 'may be alive'}. "
+                           f"Its next write will be refused.")
+    raise StillRunning(
+        f"conversation {conversation_id} is being driven by {holder}"
+        f"{'' if alive else ' (cannot tell from here whether it is alive)'}; "
+        f"its lease has {left:.0f}s left and renews while it runs.\n"
+        f"  Two processes driving one conversation is the thing the ledger's\n"
+        f"  single-writer guarantee forbids (docs/0042 I-02).\n"
+        f"  If that run is still working: let it finish, or stop it first.\n"
+        f"  If it is gone:  add --takeover")