handcode 0.3.0rc1__py3-none-any.whl

agentctl/runtime/runner.py

@@ -0,0 +1,787 @@
+"""Run a real agent on a real workspace, behind the gate.
+
+This is the thing to use. Everything in `experiments/` is a test harness; this
+does actual work.
+
+    agentctl run "add type hints to utils.py" --workspace ./myproject
+
+What it wires up:
+
+    real tools          bash, read, write -- classified by the capability matrix
+    the gate            Seams B and C, so a crash cannot duplicate an effect
+    a real model        via OpenRouter, or any OpenAI-compatible base URL
+    the ledgers         effect ledger + Seam A telemetry for `agentctl cost`
+
+**Two different safety properties, and they are not the same thing:**
+
+* The **gate** stops an effect happening *twice*. That is replay safety.
+* `--confirm-destructive` stops a dangerous effect happening *at all* without
+  a human saying yes. That is authorization.
+
+A first-time `rm -rf` is not a replay, so the gate admits it. If you point this
+at a repository you care about, keep the confirmation on — it is the default.
+
+The confirmation asks on two independent grounds: the effect is `DESTRUCTIVE`,
+or it writes somewhere outside the workspace. The second is not a lesser form
+of the first — `echo x > ~/.bashrc` is an ordinary idempotent write that simply
+is not the agent's business (`docs/0027`).
+"""
+from __future__ import annotations
+
+import os
+import sys
+import time
+import uuid
+from pathlib import Path
+
+DEFAULT_MODEL = "openrouter/nvidia/nemotron-3-super-120b-a12b:free"
+
+#: What `<workspace>/.agentctl/.gitignore` says. The directory holds the ledger
+#: and every conversation -- task text, file contents, command output -- and
+#: sat untracked in the user's repository, one `git add -A` from a commit
+#: (`docs/0044` N11). `*` ignores all of it, this file included, so it never
+#: appears in `git status`. `agents/` stays visible: subagent definitions are
+#: written by the user and may belong in the repository.
+STATE_GITIGNORE = ("# Written by agentctl: runtime state, never source.\n"
+                   "*\n!agents/\n!agents/**\n")
+
+
+SHOW_SYSTEM_PROMPT_ENV = "AGENTCTL_SHOW_SYSTEM_PROMPT"
+
+
+def _visualizer():
+    """The SDK's own visualizer, minus the system prompt.
+
+    The default prints the whole system prompt and tool schemas before the
+    first turn: a 38-second run produced 687 lines, most of them text the user
+    did not write and cannot act on (`docs/0044` N10). It is replaced by one
+    line saying it was hidden and how to see it -- never silently dropped.
+    """
+    from openhands.sdk.conversation.visualizer import DefaultConversationVisualizer
+    from openhands.sdk.event import SystemPromptEvent
+
+    class _Quiet(DefaultConversationVisualizer):
+        def on_event(self, event):
+            if (isinstance(event, SystemPromptEvent)
+                    and not os.environ.get(SHOW_SYSTEM_PROMPT_ENV)):
+                print(f"  (system prompt hidden; set {SHOW_SYSTEM_PROMPT_ENV}=1 "
+                      f"to show it)\n")
+                return
+            super().on_event(event)
+
+    return _Quiet()
+
+
+def state_dir(ws: Path) -> Path:
+    """`<ws>/.agentctl`, created with its own `.gitignore`.
+
+    An existing `.gitignore` is left alone: if someone wrote one, it is theirs.
+    """
+    d = ws / ".agentctl"
+    d.mkdir(parents=True, exist_ok=True)
+    ignore = d / ".gitignore"
+    if not ignore.exists():
+        ignore.write_text(STATE_GITIGNORE, encoding="utf-8")
+    return d
+
+
+def _build_agent(llm, tools):
+    """Construct the Agent with `tool_concurrency_limit` pinned to 1.
+
+    `agentctl/runtime/tools.py` implements `declared_resources()` on none of
+    its three tools, so the SDK's `ParallelToolExecutor` falls back to a
+    per-*tool-name* mutex (`declared=False` -> lock key `f"tool:{name}"`).
+    That lets `bash` -- which can `git commit` -- run concurrently with
+    `write_file` the moment the limit rises above 1, racing a ledger and a
+    git probe that both assume a single writer, and racing them *silently*:
+    every ledger write happens on the agent thread, so there is no exception
+    to notice (`docs/0038` §4.3).
+
+    Pinned explicitly here rather than relying on the SDK's own default
+    (currently 1, but not ours to depend on), and checked immediately after
+    construction so a future SDK upgrade, or an edit that drops the kwarg,
+    fails loudly instead of letting tools race unnoticed. This is the only
+    place in `agentctl/` allowed to construct an `Agent` -- see
+    `tests/test_tool_concurrency_pin.py`.
+    """
+    from openhands.sdk import Agent, Tool
+
+    agent = Agent(llm=llm, tools=[Tool(name=n) for n in tools],
+                  tool_concurrency_limit=1, include_default_tools=[])
+    if agent.tool_concurrency_limit != 1:
+        raise RuntimeError(
+            "tool_concurrency_limit did not pin to 1. agentctl's tools do "
+            "not implement declared_resources(), so running them "
+            "concurrently can silently corrupt the effect ledger and the "
+            "git probe (docs/0038 §4.3). Refusing to start rather than run "
+            "unsafely.")
+    return agent
+
+
+def _key_for(model: str) -> tuple[str | None, str | None]:
+    """Find a key for this model without ever printing it."""
+    for prefix, env in (("openrouter/", "OPENROUTER_API_KEY"),
+                        ("anthropic/", "ANTHROPIC_API_KEY"),
+                        ("openai/", "OPENAI_API_KEY"),
+                        ("gemini/", "GEMINI_API_KEY"),
+                        ("mistral/", "MISTRAL_API_KEY")):
+        if model.startswith(prefix):
+            return os.environ.get(env), env
+    for env in ("OPENROUTER_API_KEY", "OPENAI_API_KEY", "ANTHROPIC_API_KEY"):
+        if os.environ.get(env):
+            return os.environ[env], env
+    return None, None
+
+
+def _env_var_for(model: str) -> str:
+    """The environment variable this model's provider actually reads."""
+    for prefix, env in (("openrouter/", "OPENROUTER_API_KEY"),
+                        ("anthropic/", "ANTHROPIC_API_KEY"),
+                        ("openai/", "OPENAI_API_KEY"),
+                        ("gemini/", "GEMINI_API_KEY"),
+                        ("mistral/", "MISTRAL_API_KEY"),
+                        ("cerebras/", "CEREBRAS_API_KEY"),
+                        ("groq/", "GROQ_API_KEY")):
+        if model.startswith(prefix):
+            return env
+    return "the API key variable for your provider"
+
+
+def run(
+    task: str,
+    workspace: str | Path = ".",
+    *,
+    model: str = DEFAULT_MODEL,
+    base_url: str | None = None,
+    ledger: str | Path | None = None,
+    confirm_destructive: bool = True,
+    max_iterations: int = 30,
+    max_budget_usd: float | None = None,
+    resume: str | None = None,
+    record: str | Path | None = None,
+    replay: str | Path | None = None,
+    policy: str | Path | None = None,
+    cost_ledger: str | Path | None = None,
+    verbose: bool = True,
+    takeover: bool = False,
+    accept: str | None = None,
+) -> dict:
+    """Run one agent task. Returns a summary dict.
+
+    `record` writes every completion to a cassette; `replay` serves them back
+    from disk with no API key, no network and no sampling (M6, `docs/0029`).
+
+    `accept` is a command agentctl runs itself once the agent has finished --
+    the test suite, usually. Its exit code is the run's outcome; without it
+    the outcome is "not checked", never an implied success (`docs/0048`).
+    """
+    from agentctl.adapters.openhands import protect
+    from agentctl.runtime import tools as rt
+    from openhands.sdk import LLM, Conversation
+
+    from agentctl.runtime import report as rp
+
+    ws = Path(workspace).resolve()
+    ws.mkdir(parents=True, exist_ok=True)
+    start = rp.snapshot(ws)
+    state = state_dir(ws)
+    ledger_path = Path(ledger) if ledger else state / "ledger.db"
+
+    os.environ[rt.WORKSPACE_ENV] = str(ws)
+    os.environ.setdefault("AGENTCTL_TELEMETRY",
+                          str(state / "hook_telemetry.json"))
+    # Do NOT register the plain tools here: protect() registers gated versions
+    # under the same names, and doing both only produces duplicate warnings.
+
+    # Replay stands in for the provider entirely: the cassette decides the
+    # model, so a `--model` flag cannot silently invalidate every fingerprint.
+    replay_server = None
+    if replay is not None:
+        from agentctl.control.replay import Cassette, ReplayServer
+
+        cassette = Cassette.load(replay)
+        if not cassette.turns:
+            raise SystemExit(f"cassette {replay} has no turns")
+        first = cassette.turns[0]
+        model = first.provider_model or first.model or model
+        replay_server = ReplayServer(cassette).start()
+        base_url = replay_server.base_url
+        if verbose:
+            print(f"  replay        {replay} ({len(cassette)} turns)")
+
+    api_key, key_env = _key_for(model)
+    if replay_server is not None:
+        api_key, key_env = "replay-no-key-needed", None
+    elif base_url and not api_key:
+        # Pointing at a proxy: the credentials live in the proxy, not here.
+        # litellm still requires *something* in the field and errors with
+        # "Missing credentials ... set OPENAI_API_KEY" if it is None -- which
+        # sends you looking for a key you deliberately do not have. The
+        # `agentctl proxy` instructions promised no client key was needed and
+        # this is what makes that true (`docs/0036`).
+        api_key, key_env = "proxy-holds-the-credentials", None
+    if not api_key and not base_url:
+        raise SystemExit(
+            f"No API key found for {model}.\n"
+            # Name the variable THIS model needs. Telling someone to set
+            # OPENROUTER_API_KEY for an anthropic/ model is advice that
+            # cannot work.
+            f"  Set {_env_var_for(model)} in your environment.\n"
+            f"  It is read from the environment and never logged.\n"
+            f"  Check what you have:  agentctl doctor")
+
+    recorder = None
+    if record is not None:
+        from agentctl.adapters.litellm.recorder import attach
+
+        recorder = attach(record, configured_model=model)
+        if verbose:
+            print(f"  recording     {record}")
+
+    pol = _load_policy(policy)
+    if pol:
+        _enforce_before_spending(pol, model, cost_ledger, max_budget_usd,
+                                 replay is not None, verbose)
+        if max_budget_usd is None:
+            max_budget_usd = pol.limit("per_task")
+        # `docs/0002` §5: never silently spend. A policy that names DESTRUCTIVE
+        # as requiring approval turns the confirmation on regardless of flags.
+        if pol.requires_approval("DESTRUCTIVE"):
+            confirm_destructive = True
+
+    cid = uuid.UUID(resume) if resume else uuid.uuid4()
+
+    decisions: list[dict] = []
+
+    def on_decision(call, decision):
+        decisions.append({"tool": call.tool_name,
+                          "verdict": decision.verdict.value,
+                          "class": (decision.effect_class.value
+                                    if decision.effect_class else None),
+                          "reason": decision.reason})
+        if verbose and decision.verdict.value != "EXECUTE":
+            # The user's words, not the gate's (`docs/0044` F10).
+            word = {"SUBSTITUTE": "reused", "BLOCK": "paused",
+                    "ESCALATE": "paused"}.get(decision.verdict.value,
+                                              decision.verdict.value)
+            print(f"  [agentctl] {word} {call.tool_name}: "
+                  f"{decision.reason}", file=sys.stderr)
+
+    # One driver per conversation (`docs/0042` I-02). This used to be
+    # `takeover=bool(resume)`: every resume stole the lease, including from a
+    # run still working in another terminal. Now a dead holder is taken over
+    # without asking, and a live one is refused unless `--takeover`.
+    from agentctl.kernel.ledger.store import LeaseHeld
+    from agentctl.runtime.lease import claim, holder_id
+
+    steal = False
+    if resume:
+        c = claim(ledger_path, str(cid), force=takeover)
+        steal = c.takeover
+        if c.note and verbose:
+            print(f"  lease         {c.note}")
+    try:
+        guard = protect(
+            ledger=ledger_path,
+            conversation_id=str(cid),
+            tools=rt.TOOLS,
+            repo_root=ws,
+            holder=holder_id(),
+            takeover=steal,
+            on_decision=on_decision,
+        )
+    except LeaseHeld as e:
+        # Taken between the check and the acquire. The same refusal.
+        raise SystemExit(f"{e}\n  If that run is gone:  add --takeover") from None
+
+    if confirm_destructive:
+        _install_confirmation(guard, verbose, workspace=ws)
+
+    llm = LLM(model=model, api_key=api_key, base_url=base_url,
+              service_id="agentctl-run", temperature=0.0,
+              num_retries=2, max_output_tokens=4096)
+    agent = _build_agent(llm, rt.TOOLS)
+
+    conv = Conversation(
+        agent=agent, workspace=str(ws),
+        persistence_dir=str(state / "conversations"),
+        conversation_id=cid, delete_on_close=False,
+        max_iteration_per_run=max_iterations,
+        visualizer=_visualizer(),
+        callbacks=[guard.seam_b])
+
+    # `Conversation(...)` is a strict factory and rejects this, but the
+    # LocalConversation it returns honours the attribute (`docs/0015` §4).
+    if max_budget_usd is not None:
+        try:
+            conv.max_budget_per_run = max_budget_usd
+        except Exception:                               # noqa: BLE001
+            print("  [agentctl] budget cap unsupported by this SDK build",
+                  file=sys.stderr)
+
+    guard.attach(conv)
+
+    if verbose:
+        print(f"  workspace     {ws}")
+        print(f"  model         {model}"
+              + (f"  (key from {key_env})" if key_env else ""))
+        print(f"  conversation  {cid}")
+        print(f"  ledger        {ledger_path}")
+        print(f"  destructive   {'CONFIRM' if confirm_destructive else 'ALLOWED'}")
+        print()
+
+    from agentctl.runtime import runs
+    run_id = runs.start(str(cid), ws, ledger_path, model, base_url,
+                        task or None)
+
+    used_before = rp.Usage.of(conv)
+    stop = _PauseOnInterrupt(conv, verbose)
+    try:
+        if not resume:
+            conv.send_message(task)
+        elif (told := _tell_decisions(guard.store, str(cid))):
+            # What the user decided while the run was paused (`docs/0049`).
+            conv.send_message(told)
+        with stop:
+            conv.run()
+    except KeyboardInterrupt:
+        # The second Ctrl-C: stop now, not after the step. The ledger is
+        # fenced and fsynced, so whatever was in flight is reconciled on resume.
+        guard.close()
+        runs.end(run_id, "interrupted", detail="stopped with a second Ctrl-C")
+        raise SystemExit(f"\n  stopped. Nothing is lost: agentctl resume "
+                         f"{str(cid)[:8]}") from None
+    except Exception as e:                              # noqa: BLE001
+        # Give the lease back first: this run is over either way, and a held
+        # lease would make the very next `--resume` wait or ask.
+        guard.close()
+        # A provider refusing to serve is not a bug in the agent framework, and
+        # the SDK's own error ends with "please file a bug report at
+        # github.com/OpenHands" -- which sends you to the wrong place. Say what
+        # actually happened (`docs/0031`).
+        detail = _explain_provider_error(e)
+        if detail and _is_rate_limit(e):
+            runs.end(run_id, "rate_limited", detail=detail)
+            raise RateLimited(detail, str(cid), _reset_at(e)) from None
+        runs.end(run_id, "error", detail=detail or f"{type(e).__name__}: {e}")
+        if detail:
+            raise SystemExit(detail) from None
+        raise
+    finally:
+        # A cassette is only useful if it survives the run that produced it,
+        # including a run that died -- which is the interesting case here.
+        if recorder is not None:
+            from agentctl.adapters.litellm.recorder import detach
+            detach(recorder)
+
+    blocked = guard.blocked()
+    guard.close()
+
+    checked = None
+    if accept:
+        if verbose:
+            print(f"\n  checking      {accept}")
+        checked = rp.accept(accept, ws)
+
+    from agentctl.runtime.subagent import _final_text
+    said = _final_text(conv)
+    report = rp.Report(
+        outcome=("PASS" if checked["passed"] else "FAIL") if checked else "not checked",
+        accept=checked, changes=rp.changes(ws, start),
+        agent_said=None if said.startswith("[subagent") else said,
+        usage=rp.Usage.of(conv) - used_before, model=model,
+        seconds=time.time() - start.at, decisions=decisions,
+        blocked=[b.tool_call_id for b in blocked], ledger=str(ledger_path),
+        conversation_id=str(cid), workspace=str(ws),
+        awaiting=[(b.tool_call_id, (b.error or "").split("): ", 1)[-1])
+                  for b in blocked if (b.error or "").startswith(AWAITING)],
+        paused=stop.paused)
+    runs.end(run_id,
+             "interrupted" if stop.paused else
+             ("done" if report.ok else
+              ("failed" if report.outcome == "FAIL" else "needs_you")),
+             outcome=report.outcome, requests=report.usage.requests)
+
+    out = {"conversation_id": str(cid), "workspace": str(ws),
+           "ledger": str(ledger_path), "decisions": decisions,
+           "blocked": [b.tool_call_id for b in blocked], "report": report}
+
+    if recorder is not None:
+        out["recorded"] = {"cassette": str(record),
+                           "turns": len(recorder.cassette),
+                           "errors": recorder.errors}
+    if replay_server is not None:
+        from agentctl.control.replay import summarise
+        out["replay"] = summarise(replay_server.cassette)
+        replay_server.stop()
+
+    return out
+
+
+#: Marks a BLOCKED record as waiting on a human's approval, rather than on a
+#: human's judgement of whether an ambiguous effect landed. Different questions,
+#: different commands: `approve`/`deny` versus `resolve --landed/--retry`.
+AWAITING = "AWAITING APPROVAL"
+
+
+def _command_summary(call) -> str:
+    args = call.args or {}
+    text = args.get("command") or args.get("path") or str(args)
+    return f"{call.tool_name}: {str(text)[:200]}"
+
+
+def _install_confirmation(guard, verbose: bool, workspace: Path | None = None,
+                          interactive: bool | None = None) -> None:
+    """Ask before an effect that is dangerous, or that lands outside the workspace.
+
+    The gate is about replay safety, so a first-time `rm -rf` passes it. This is
+    the separate authorization question, asked here rather than buried in the
+    gate so the two stay distinguishable (`docs/0025` §4).
+
+    Two independent reasons to ask, and they are not the same question:
+
+        DESTRUCTIVE          the effect is dangerous wherever it happens
+        escapes the root     the effect is ordinary, but not the agent's
+                             business -- `echo x > ~/.bashrc` classifies
+                             IDEMPOTENT_WRITE and is correct to (`docs/0027`)
+
+    Escalating the *class* for the second case would have been the easy fix and
+    the wrong one: the ledger would then treat a replayable write as
+    unrecoverable, and a safe resume would start failing closed.
+
+    **With nobody at a terminal** (`docs/0042` I-06, `docs/0044` F7) it used to
+    call `input()`: unattended it hung, detached it read EOF and refused,
+    silently. Now the action is QUEUED -- recorded BLOCKED awaiting approval,
+    and the agent is told so and not to repeat it -- and `agentctl approve` /
+    `deny` answers it later. A decision already recorded is honoured without
+    asking again, which is what lets an approved action run on resume.
+    """
+    from agentctl.kernel.ledger.models import EffectClass, GateDecision, Verdict
+    from agentctl.kernel.paths import environment_installs, escaping_writes
+
+    inner = guard.gate.guard
+    store, gate = guard.gate.store, guard.gate
+    ask = sys.stdin.isatty() if interactive is None else interactive
+
+    def _not_run(call, why: str) -> None:
+        # A refused action provably did not run. Leaving its INTENT record
+        # behind made a later identical call look like a crash to reconcile.
+        try:
+            if (rec := store.lookup(call.tool_call_id)) is not None and                     rec.state.value == "INTENT":
+                store.fail(call.tool_call_id, why)
+        except Exception:                               # noqa: BLE001
+            pass
+
+    def _queue(call, cls, why: str) -> GateDecision:
+        try:
+            if store.lookup(call.tool_call_id) is None:
+                store.write_intent(call, cls, gate.fence)
+            store.block(call.tool_call_id,
+                        f"{AWAITING} ({why}): {_command_summary(call)}")
+        except Exception:                               # noqa: BLE001
+            pass
+        if verbose:
+            print(f"  [agentctl] queued for your approval: {_command_summary(call)}",
+                  file=sys.stderr)
+        return GateDecision(
+            Verdict.BLOCK, cls,
+            reason=(f"This action needs the user's approval ({why}) and has been "
+                    f"queued for them; it did not run. Do NOT repeat it. Carry "
+                    f"on with anything that does not depend on it, then finish "
+                    f"and say it is waiting for approval."))
+
+    def guard_with_confirmation(call):
+        decision = inner(call)
+        if decision.verdict is not Verdict.EXECUTE:
+            return decision
+
+        reasons: list[str] = []
+        if decision.effect_class is EffectClass.DESTRUCTIVE:
+            reasons.append("DESTRUCTIVE")
+        if outside := escaping_writes(call, workspace):
+            reasons.append("writes outside the workspace: "
+                           + ", ".join(outside[:4]))
+        # Software installed into YOUR environment (`docs/0052`). Not asked
+        # inside the image: there it lands in the container and dies with it,
+        # which is the containment the image exists to provide.
+        if not os.environ.get("HANDCODE_CONTAINER") and \
+                (installs := environment_installs(call, workspace)):
+            reasons.append("installs into your environment: " + installs[0][:80])
+        if not reasons:
+            return decision
+        why = " | ".join(reasons)
+
+        prior = store.approval(call.conversation_id, call.intent_hash())
+        if prior == "approve":
+            store.use_approval(call.conversation_id, call.intent_hash())
+            if verbose:
+                print(f"  [agentctl] approved earlier by you: "
+                      f"{_command_summary(call)}", file=sys.stderr)
+            return decision
+        if prior == "deny":
+            _not_run(call, "denied by the operator")
+            return GateDecision(Verdict.BLOCK, decision.effect_class,
+                                reason="The user denied this action. Do not run "
+                                       "it, and do not try to achieve the same "
+                                       "effect another way.")
+        if not ask:
+            return _queue(call, decision.effect_class, why)
+
+        print(f"\n  !! {why}", file=sys.stderr)
+        print(f"     {call.tool_name} {str(call.args)[:200]}", file=sys.stderr)
+        try:
+            answer = input("     allow? [y/N] ").strip().lower()
+        except EOFError:
+            # A terminal that closed mid-question: queue it, as for no terminal.
+            return _queue(call, decision.effect_class, why)
+        if answer != "y":
+            _not_run(call, "refused by the operator")
+            return GateDecision(Verdict.BLOCK, decision.effect_class,
+                                reason="refused by the operator")
+        return decision
+
+    guard.gate.guard = guard_with_confirmation
+
+
+class RateLimited(SystemExit):
+    """The provider refused for quota. Carries what a wait-and-resume needs:
+    the conversation, and the reset time when the provider said one."""
+
+    def __init__(self, text: str, conversation_id: str, reset_at: float | None):
+        super().__init__(text)
+        self.text, self.conversation_id, self.reset_at = text, conversation_id, reset_at
+
+
+def _is_rate_limit(e: Exception) -> bool:
+    low = str(e).lower()
+    return ("rate limit" in low or "429" in str(e) or "ratelimiterror" in low
+            or "quota" in low)
+
+
+def _reset_at(e: Exception) -> float | None:
+    """The provider's reset time, epoch seconds, when its error carried one."""
+    import re
+    if m := re.search(r'"X-RateLimit-Reset":"(\d{10,13})"', str(e)):
+        ts = int(m.group(1))
+        return ts / 1000 if ts > 10_000_000_000 else float(ts)
+    return None
+
+
+class _PauseOnInterrupt:
+    """Ctrl-C pauses the conversation after its current step; a second one
+    stops at once (`docs/0043` Phase 4).
+
+    `pause()` takes effect between steps, and is callable from a signal
+    handler: the conversation's lock is re-entrant (`docs/0042` §8.2). The
+    paused conversation is persisted, so `agentctl resume` continues it.
+    Only installed on the main thread -- signals cannot be anywhere else.
+    """
+
+    def __init__(self, conv, verbose: bool):
+        self.conv, self.verbose, self.paused, self._old = conv, verbose, False, {}
+
+    def _handle(self, signum, frame):
+        if self.paused:
+            raise KeyboardInterrupt
+        self.paused = True
+        if self.verbose:
+            print("\n  [agentctl] pausing after the current step "
+                  "(Ctrl-C again to stop now)", file=sys.stderr)
+        try:
+            self.conv.pause()
+        except Exception:                               # noqa: BLE001
+            raise KeyboardInterrupt from None
+
+    def __enter__(self):
+        import signal
+        import threading
+        if threading.current_thread() is not threading.main_thread():
+            return self
+        for name in ("SIGINT", "SIGBREAK"):
+            if (sig := getattr(signal, name, None)) is not None:
+                self._old[sig] = signal.signal(sig, self._handle)
+        return self
+
+    def __exit__(self, *exc):
+        import signal
+        for sig, old in self._old.items():
+            signal.signal(sig, old)
+        return False
+
+
+def _tell_decisions(store, conversation_id: str) -> str | None:
+    """The message a resumed agent gets about approvals decided meanwhile."""
+    try:
+        rows = store.untold(conversation_id)
+    except Exception:                                   # noqa: BLE001
+        return None
+    if not rows:
+        return None
+    lines = ["While this run was paused, the user decided on actions that "
+             "needed approval:"]
+    for r in rows:
+        what = r.get("summary") or "an action"
+        if r["decision"] == "approve":
+            lines.append(f"- APPROVED: {what}. You may run it now if it is "
+                         f"still needed.")
+        else:
+            lines.append(f"- DENIED: {what}. Do not run it, and do not try to "
+                         f"achieve the same effect another way.")
+    lines.append("Continue the task.")
+    store.told(conversation_id)
+    return "\n".join(lines)
+
+
+# ── policy enforcement (M7, docs/0030) ─────────────────────────────────
+def _load_policy(policy):
+    """Load a compiled policy, or compile a .yaml on the spot.
+
+    Accepting the source form is a convenience with a sharp edge: compiling
+    here means a malformed policy is discovered at run time, which is exactly
+    what `docs/0012` §5.2 wants to avoid. So it is compiled BEFORE anything
+    else happens, and a failure stops the run before a single effect.
+    """
+    from pathlib import Path as _P
+
+    from agentctl.kernel.policy import Policy
+
+    if policy is None:
+        return Policy.empty()
+    p = _P(policy)
+    if p.suffix in (".yaml", ".yml"):
+        from agentctl.control.policy import PolicyError, compile_policy
+        try:
+            return Policy(compile_policy(p))
+        except PolicyError as e:
+            raise SystemExit(f"policy {p} does not compile:\n{e}")
+    return Policy.load(p)
+
+
+def _daily_spend(cost_ledger) -> tuple[float, float] | None:
+    """(spent, coverage) for the last 24h, or None if nothing is recorded.
+
+    Read HERE, in the runtime, and handed to the kernel as a number. The kernel
+    may not import the cost ledger (`docs/0008` R2) and should not: a budget
+    guard that queried a database in-band would fail closed whenever the
+    control plane was down, turning a cost feature into an outage.
+    """
+    from pathlib import Path as _P
+
+    p = _P(cost_ledger) if cost_ledger else _P("cost.db")
+    if not p.exists():
+        return None
+    try:
+        from agentctl.control.cost import CostLedger
+        with CostLedger(p) as c:
+            t = c.totals(since=time.time() - 86400)
+        return (t.cost_usd, t.coverage) if t.calls else None
+    except Exception:                                   # noqa: BLE001
+        return None
+
+
+def _enforce_before_spending(pol, model, cost_ledger, max_budget_usd,
+                             replaying: bool, verbose: bool) -> None:
+    """Refuse the run outright if policy already says no.
+
+    Before the ledger, before the agent, before a single token: a budget check
+    that happens after the work is an audit, not a cap.
+    """
+    if verbose:
+        print(f"  policy        {len(pol.pool(pol.default_pool or ''))} "
+              f"deployment(s) in {pol.default_pool!r}"
+              f"  per-task ${pol.limit('per_task') or 0:.2f}")
+
+    # Replay spends nothing, so a budget cannot bind and a stale ledger must
+    # not stop an offline run.
+    if replaying:
+        return
+
+    spend = _daily_spend(cost_ledger)
+    if spend is not None:
+        spent, coverage = spend
+        v = pol.check_budget(spent, "daily", coverage)
+        if not v.allowed:
+            raise SystemExit(
+                f"refusing to start: {v.reason}\n"
+                f"  raise budget.daily_usd, or wait for the window to roll.")
+        if not v.trustworthy and verbose:
+            print(f"  ! budget      {v.describe()}", file=sys.stderr)
+
+    # Escalation: using something outside the default pool is spending money
+    # the policy did not pre-authorise (`docs/0002` §5).
+    default = pol.default_pool
+    if default and model not in pol.pool(default):
+        esc = pol.escalation or {}
+        target = esc.get("pool")
+        in_escalation_pool = target and model in pol.pool(target)
+        if esc.get("require_confirmation", True):
+            where = f"the {target!r} pool" if in_escalation_pool else "no pool"
+            print(f"\n  !! {model} is not in the default pool {default!r} "
+                  f"({where})", file=sys.stderr)
+            try:
+                answer = input("     spend on it? [y/N] ").strip().lower()
+            except EOFError:
+                answer = "n"
+            if answer != "y":
+                raise SystemExit("refused: policy requires confirmation "
+                                 "before leaving the default pool")
+
+
+def _explain_provider_error(exc: Exception) -> str | None:
+    """Turn a provider refusal into something actionable, or None.
+
+    Returns None for anything not recognised -- guessing at an unfamiliar
+    error would hide it, and an unhandled traceback is better than a confident
+    wrong explanation.
+    """
+    import re
+
+    text = str(exc)
+    low = text.lower()
+
+    if "rate limit" in low or "429" in text or "ratelimiterror" in low:
+        when = ""
+        if m := re.search(r'"X-RateLimit-Reset":"(\d{10,13})"', text):
+            from datetime import datetime
+            ts = int(m.group(1))
+            ts = ts / 1000 if ts > 10_000_000_000 else ts
+            r = datetime.fromtimestamp(ts).astimezone()
+            when = f"\n  resets       {r:%Y-%m-%d %H:%M} local"
+        remaining = ""
+        if m := re.search(r'"X-RateLimit-Remaining":"(\d+)"', text):
+            remaining = f"\n  remaining    {m.group(1)}"
+        per_day = ("\n  note         the free-model cap is account-wide across "
+                   "every `:free`\n               model, so switching model "
+                   "does not help"
+                   if "free-models-per-day" in low else "")
+        return (f"the provider is rate limiting you. This is not an agent "
+                f"error.{remaining}{when}{per_day}\n"
+                f"  options      wait for the reset (run with --wait 30m to "
+                f"wait automatically),\n               or route through the "
+                f"pool so another provider serves:  --pool")
+
+    if "insufficient" in low and "credit" in low:
+        return ("the provider says the account is out of credit. Nothing was "
+                "spent on this run.")
+
+    if "no auth credentials" in low or "invalid api key" in low or "401" in text:
+        return ("the provider rejected the API key. Check the environment "
+                "variable for your model's provider; the value is read from "
+                "the environment and never logged.")
+
+    if ("400 bad request" in low or "badrequesterror" in low
+            or "not a valid model" in low):
+        return ("the provider rejected the request — usually an unknown or "
+                "unavailable model id.\n"
+                "  check        the id at openrouter.ai/models; it needs the "
+                "provider prefix,\n"
+                "               e.g. openrouter/vendor/model:free\n"
+                "  known-good   agentctl proxy   (lists the ids it builds a "
+                "pool from)")
+
+    if "overloaded" in low or "503" in text or "502" in text:
+        return ("the provider is overloaded and refused the request. Free-tier "
+                "endpoints do this under load.\n"
+                "  options      agentctl resume, or route through the pool so a "
+                "failure fails over:  --pool")
+    return None