foundry-implementation-actor 0.1.0__py3-none-any.whl

foundry_implementation_actor/correlation.py

@@ -0,0 +1,193 @@
+"""Correlation ids — the one place this actor decides what identifies a unit of work.
+
+WHY THIS EXISTS. Before it, exactly one call site (the engine's own `_invoke_claude`) passed
+`extra={"task_id": ...}`, so the session transcript was the only thing in Loki that could be
+drilled to a task. Everything else this actor logs — the framework's own `do_POST door=…` access
+line, every git/buildctl step, every failure — arrived with no identity at all, which is exactly
+when you most want one. This module makes carrying the ids the default rather than a thing each
+call site has to remember.
+
+TWO IDS, AND WHERE EACH COMES FROM.
+
+  * `correlation_id` — THE TRACE ID, not a second identifier invented here. One orchestration
+    call is one trace: the ORCHESTRATING actor's own `_call_door` injects W3C `traceparent`, and
+    `HttpMailbox.do_POST` extracts it into the SERVER span it opens around `Actor.receive()` — so
+    every actor in the pipeline, across every retry attempt, is already inside one trace before a
+    line of this module runs. Reading `trace.get_current_span()` and formatting its
+    trace id is therefore not "generating a correlation id", it is *naming the one that already
+    crossed the wire*. It also means a `correlation_id` in Loki pastes straight into Tempo.
+    A locally-minted uuid is the fallback for the no-SDK / no-active-span case only.
+  * `task_id` — `TASK-NNN`, off the caller's own payload. Spans retries and every peer, where the
+    trace id spans one orchestration run; neither subsumes the other, so both are carried.
+
+A CALL THAT NEVER REACHES A HANDLER still gets a `correlation_id`. `Actor.receive()` refuses an
+undeclared door or a schema-violating payload before any handler runs, and the binding answers an
+unknown path or an unparseable body without ever calling `receive()` — so nothing of ours binds
+for any of them. `CorrelationFilter` therefore falls back to the active span's trace id, which
+since ADR-PASH-0005 (`papeete-actor-synchronous-messaging-http` 0.4.0) is open across every one of
+those paths. That fallback is the whole reason the binding needed changing: a consumer can stamp
+its own records, never the ones written on its behalf before its code ran.
+
+WHY A HANDLER FILTER, NOT `extra=` AT EVERY CALL SITE. A `logging.Filter` on the ROOT LOGGER would
+only see records logged directly to it — a record from any named logger reaches the root's
+HANDLERS without ever being filtered by the root logger itself. So `install()` attaches to the
+handlers, where every record does pass, including ones from code this repo does not own
+(`papeete_actor_synchronous_messaging_http.mailbox`'s access log, most importantly). Nothing has
+to opt in, which is the whole point: correlation ids everywhere means everywhere, not everywhere
+someone remembered.
+
+WHY `bind()` NEVER RESETS. `HttpMailbox` serves on a `ThreadingHTTPServer` — one fresh thread per
+request, never pooled — and a `ContextVar` set inside a thread is invisible to every other thread
+and dies with it. So request scope is thread scope here, for free, and NOT resetting is what lets
+the ids reach the lines emitted *after* the handler returns: `do_POST`'s own access log sits in a
+`finally` outside the span, and would otherwise be the one line in the whole request with no
+identity. A second `bind()` in the same thread overwrites, which is what an attempt counter wants.
+"""
+from __future__ import annotations
+
+import contextvars
+import json
+import logging
+import time
+import uuid
+from contextlib import contextmanager
+
+try:                                       # the same guard papeete-actor-synchronous-messaging-
+    from opentelemetry import trace        # http's own _tracing.py keeps: the API is a no-op
+except ImportError:                        # without an SDK, and absent entirely in a bare test
+    trace = None                           # environment. Neither is an error here.
+
+_FIELDS: contextvars.ContextVar[dict] = contextvars.ContextVar("papeete_correlation", default={})
+
+STEP_LOGGER = "pipeline"
+
+
+def _trace_id() -> str | None:
+    """The active span's trace id, or None — no SDK, no span, or an invalid context."""
+    if trace is None:
+        return None
+    context = trace.get_current_span().get_span_context()
+    return format(context.trace_id, "032x") if context.is_valid else None
+
+
+def correlation_id() -> str:
+    """The active trace id, or a fresh uuid when there is no SDK/span to read one from."""
+    return _trace_id() or uuid.uuid4().hex
+
+
+def current() -> dict:
+    return dict(_FIELDS.get())
+
+
+def bind(**fields) -> None:
+    """Add ids to THIS THREAD's correlation context, for the rest of the thread's life.
+
+    Deliberately not a context manager — see this module's own docstring for why the binding
+    outliving the handler is the point, not an oversight."""
+    _FIELDS.set({**_FIELDS.get(), **{k: v for k, v in fields.items() if v is not None}})
+
+
+class CorrelationFilter(logging.Filter):
+    """Stamps every record passing a handler with the current context's ids.
+
+    Never overwrites: a call site that passed its own `extra={"task_id": ...}` keeps it, so this
+    is additive to existing behaviour rather than a replacement for it. The stamped attributes
+    are ordinary record attributes, which is precisely what OTel's own `LoggingHandler` turns
+    into OTLP log attributes — and Loki, in turn, into structured metadata a `| task_id = "…"`
+    matcher filters on with no parser in front of it."""
+
+    def filter(self, record: logging.LogRecord) -> bool:
+        for key, value in _FIELDS.get().items():
+            if not hasattr(record, key):
+                setattr(record, key, value)
+        if not hasattr(record, "correlation_id"):
+            # NOTHING BOUND — which is precisely the shape of a call the framework turned away
+            # before any handler of ours could run: an undeclared door, a payload the card's own
+            # `request_schema` rejects, a body that is not JSON. Since ADR-PASH-0005 the HTTP
+            # binding holds its SERVER span open across all of those, parented on the caller's
+            # own `traceparent`, so the active trace id here is the very value `bind()` would
+            # have used. Falling back to it files those records under the run that caused them
+            # instead of under nothing at all. `task_id` genuinely cannot be recovered this way
+            # and is left absent: a payload the schema rejected may not carry one.
+            fallback = _trace_id()
+            if fallback:
+                record.correlation_id = fallback
+        return True
+
+
+# The ids Loki gets as structured metadata are invisible in `kubectl logs`, which is still the
+# first place anyone looks when the telemetry backend itself is what's under suspicion.
+CONSOLE_IDS = ("correlation_id", "task_id", "attempt")
+
+
+class ConsoleFormatter(logging.Formatter):
+    """Appends whichever correlation ids a record actually carries.
+
+    A plain `%(task_id)s` in the format string would instead raise `Formatting field not found`
+    for every record emitted outside a request — the startup line, anything on a thread that never
+    bound — which is exactly how a logging change takes a process down. Nothing is defaulted onto
+    the record either: an id that isn't there stays absent, so the OTLP side never carries a
+    placeholder value the dashboard would then have to filter back out."""
+
+    def format(self, record: logging.LogRecord) -> str:
+        line = super().format(record)
+        ids = " ".join(
+            f"{key}={getattr(record, key)}" for key in CONSOLE_IDS if hasattr(record, key)
+        )
+        return f"{line} [{ids}]" if ids else line
+
+
+def install() -> None:
+    """Attach the filter to every handler on the root logger.
+
+    Call AFTER `papeete_observability.configure()` and after any console handler is added — this
+    walks the handlers that exist at the moment it runs."""
+    correlation_filter = CorrelationFilter()
+    for handler in logging.getLogger().handlers:
+        handler.addFilter(correlation_filter)
+
+
+# ── the step vocabulary ───────────────────────────────────────────────────────────────────────
+#
+# One JSON object per step, so the dashboard reads them with the same `| json` it already uses for
+# the session transcript, and tells the two apart by `event`. `phase` is start / ok / failed —
+# a start line with no matching ok is a step that was still running when the pod went away, which
+# a duration-only record could never show.
+
+def _emit(level: int, record: dict) -> None:
+    # `level` goes INTO the JSON body as well as onto the record. Severity does reach Loki through
+    # OTLP, but exactly which field it lands in is the ingester's business, not something a
+    # dashboard query should be pinned to; a `level` the emitter wrote itself is one `| json` away
+    # in every backend, which is what the product dashboard's own failure panel filters on.
+    body = {"level": logging.getLevelName(level).lower(), **record}
+    logging.getLogger(STEP_LOGGER).log(level, json.dumps(body, default=str, ensure_ascii=False))
+
+
+def event(name: str, *, level: int = logging.INFO, **fields) -> None:
+    """A point in the pipeline with no duration — a verdict, a published ref, a PR url.
+
+    `level` is keyword-only — a best-effort step that failed without stopping the run
+    (`logging.WARNING`) still reads as one `event` to the dashboard's `| json`, and lands in the
+    body as `level` (see `_emit`), so `**fields` must not carry a key of that name."""
+    _emit(level, {"event": "event", "step": name, **fields})
+
+
+@contextmanager
+def stage(name: str, **fields):
+    """A step with a beginning and an end, logged as both — and as `failed` with the exception's
+    own text if it raises, before the exception continues on its way untouched."""
+    started = time.monotonic()
+    _emit(logging.INFO, {"event": "step", "step": name, "phase": "start", **fields})
+    try:
+        yield
+    except BaseException as e:                                    # noqa: BLE001 — re-raised below
+        _emit(logging.ERROR, {
+            "event": "step", "step": name, "phase": "failed",
+            "duration_ms": round((time.monotonic() - started) * 1000),
+            "error": f"{type(e).__name__}: {e}", **fields,
+        })
+        raise
+    _emit(logging.INFO, {
+        "event": "step", "step": name, "phase": "ok",
+        "duration_ms": round((time.monotonic() - started) * 1000), **fields,
+    })

foundry_implementation_actor/engine.py

@@ -0,0 +1,434 @@
+"""`ClaudeCodeEngine` — judgement by running a headless Claude Code session against a fresh clone.
+
+WHY A CUSTOM ENGINE, NOT `papeete_actor_synchronous_messaging.engine.resolve("claude")`. The
+built-in `ClaudeEngine` shells out to the raw `anthropic` Python SDK — `anthropic.Anthropic()`,
+resolving `ANTHROPIC_API_KEY`, then `ANTHROPIC_AUTH_TOKEN`, then an `ant auth login` profile.
+Every one of those is a metered API credential. Subscription OAuth tokens (`claude setup-token`
+→ `CLAUDE_CODE_OAUTH_TOKEN`) are scoped to the `claude` CLI / claude.ai specifically and are NOT
+among the credentials the raw SDK will resolve. So the only way to spend a subscription's own
+credit rather than a separate metered key is to shell out to the `claude` CLI itself, which is
+what this file does. It still satisfies the `Engine` port (`name` + `judge(system, prompt,
+schema=None) -> dict`) — the port makes no promise about how long or heavy a judgement is.
+
+**Do not set `ANTHROPIC_API_KEY` (or `ANTHROPIC_AUTH_TOKEN`) in a container running this engine.**
+In `claude -p` non-interactive mode an API key present in the environment is ALWAYS preferred over
+`CLAUDE_CODE_OAUTH_TOKEN`, silently routing every session through metered billing instead. There is
+no warning and no visible difference in the transcript; the only symptom is the bill.
+
+PAYLOAD-DRIVEN, NOT CARD-DRIVEN. The caller supplies everything a session needs to work — this
+engine never clones a repo merely to look up what a task IS. A missing required field is refused
+by the framework's own schema gate before any engine time is spent, so there is no eligibility
+check here either.
+
+CARRIES NO CAPABILITY LITERAL. Every identifier it needs comes from `CapabilityConfig`, which
+derives all of them from one capability id and one repo (see `config.py`). The system prompt is
+never invented here either: `Actor.judge()` builds it from the card's own `means:`/`completion:`
+prose and hands it in as `system`, which this engine passes straight through via
+`--append-system-prompt`, unmodified.
+
+WHAT THIS ENGINE DOES NOT DO. It never commits, pushes, or opens a pull request — that is
+`handler.py`'s job, and `handler.py`'s own containment check is the actual enforcement of the
+write boundary this engine's prompt only *asks* the session to respect. On success it
+deliberately does NOT clean up its own clone: the handler still needs it to commit and push, and
+is the one that removes it, on every path including containment failure.
+"""
+from __future__ import annotations
+
+import json
+import logging
+import os
+import shutil
+import subprocess
+import tempfile
+import threading
+from pathlib import Path
+
+from papeete_actor_synchronous_messaging.engine import EngineError
+
+from . import correlation, grounding
+from .config import CapabilityConfig
+
+DEFAULT_CLONE_TIMEOUT_S = 120
+DEFAULT_SESSION_TIMEOUT_S = 1800
+DEFAULT_MAX_TURNS = 60
+
+
+# ── stream-json projection: keeping every emitted log line inside Loki's max_line_size ────────
+#
+# WHY PROJECT RATHER THAN LOG THE RAW EVENT. `--output-format stream-json` emits one JSON object
+# per turn — the inner conversation this actor's audit trail is made of. Two of its fields are
+# unbounded: `tool_use.input` (for `Write`, the whole file body; for `Edit`, both sides of the
+# replacement) and `tool_result.content` (for `Read`/`Grep`/`Bash`, the whole output). Nothing
+# else is: a `text` block is a few hundred bytes. So clipping those two, and only those, keeps
+# the entire conversation readable while bounding every line — and what gets clipped is
+# recoverable from the branch `handler.py` pushes anyway.
+#
+# WHY IT MATTERS. Loki's `max_line_size` is 256KB with `max_line_size_truncate: false` — an
+# oversized line is REJECTED OUTRIGHT, not trimmed, so a single large `Read` would silently
+# delete exactly the turn worth reading while leaving the rest of the session intact. The budget
+# below is a quarter of that, which also sidesteps Loki parsing `KB` as 1000 rather than 1024.
+#
+# AND WHY NOT RECORD ATTRIBUTES. The OTel `LoggingHandler` maps the formatted message to the OTLP
+# body (the line Loki measures) and record attributes to log-record attributes, which land in Loki
+# structured metadata under their own separate caps (`max_structured_metadata_size: 64KB`,
+# `max_structured_metadata_entries_count: 128`). Payload cannot be smuggled out of the line limit
+# by moving it there — that channel is for correlation ids, which `correlation.py` stamps onto
+# every record this process emits without any call site here passing them.
+
+LINE_BUDGET = 64 * 1024   # bytes per emitted log line
+BLOB_HEAD = 2000          # bytes kept from the front of an unbounded value
+BLOB_TAIL = 2000          # ...and from the back: a Bash failure lives in the tail, not the head
+PROSE = 8000              # text/thinking/result — prose IS the audit trail, give it more room
+
+
+def _clip(value, head: int = BLOB_HEAD, tail: int = BLOB_TAIL) -> str:
+    """Head+tail slice of a value, budgeted in BYTES (not characters — the limit Loki enforces
+    is on the UTF-8 encoded line), with the true size recorded in the marker."""
+    if not isinstance(value, str):
+        value = json.dumps(value, default=str)
+    raw = value.encode("utf-8", "replace")
+    if len(raw) <= head + tail:
+        return value
+    return (raw[:head].decode("utf-8", "replace")
+            + f"\n…[clipped {len(raw) - head - tail} of {len(raw)} bytes]…\n"
+            + raw[-tail:].decode("utf-8", "replace"))
+
+
+def _project(event: dict) -> dict | None:
+    """One stream-json event -> a compact dict, or None to drop it entirely."""
+    kind = event.get("type")
+
+    if kind == "system" and event.get("subtype") == "init":
+        # The raw init event is ~2.2KB of tools/skills/slash_commands inventory. Four fields of
+        # it are worth keeping — `session_id` is the join key to the CLI's own full transcript,
+        # which it writes to $HOME/.claude/projects/<slug>/<session_id>.jsonl regardless of
+        # --output-format.
+        return {"event": "init", "session_id": event.get("session_id"),
+                "model": event.get("model"), "cwd": event.get("cwd")}
+
+    if kind == "result":
+        usage = event.get("usage") or {}
+        return {"event": "result", "session_id": event.get("session_id"),
+                "subtype": event.get("subtype"), "is_error": event.get("is_error"),
+                "num_turns": event.get("num_turns"), "duration_ms": event.get("duration_ms"),
+                "cost_usd": event.get("total_cost_usd"),
+                "input_tokens": usage.get("input_tokens"),
+                "output_tokens": usage.get("output_tokens"),
+                "result": _clip(event.get("result", ""), PROSE, PROSE)}
+
+    if kind not in ("assistant", "user"):
+        return None                       # rate_limit_event and friends carry no audit value
+
+    blocks = []
+    for block in (event.get("message") or {}).get("content", []):
+        if not isinstance(block, dict):
+            continue
+        btype = block.get("type")
+        if btype in ("text", "thinking"):
+            blocks.append({btype: _clip(block.get(btype, ""), PROSE, PROSE)})
+        elif btype == "tool_use":
+            blocks.append({"tool_use": block.get("name"), "id": block.get("id"),
+                           "input": {k: _clip(v) for k, v in (block.get("input") or {}).items()}})
+        elif btype == "tool_result":
+            # `content` is a str for a text result and a list of blocks otherwise — `_clip`
+            # json-dumps the latter rather than this guessing at its shape.
+            blocks.append({"tool_result": block.get("tool_use_id"),
+                           "is_error": block.get("is_error", False),
+                           "content": _clip(block.get("content", ""))})
+    return {"event": kind, "blocks": blocks} if blocks else None
+
+
+def _line(record: dict) -> str:
+    """Serialize, then hard-enforce the budget.
+
+    The per-field clipping in `_project` is what keeps lines small; this is what makes "no line
+    exceeds the budget" a property of the code rather than a hope — a `tool_use` carrying a
+    hundred just-under-threshold keys would otherwise slip through the sum."""
+    line = json.dumps(record, default=str, ensure_ascii=False)
+    if len(line.encode("utf-8")) > LINE_BUDGET:
+        half = LINE_BUDGET // 2 - 200
+        line = json.dumps({"event": record.get("event"), "over_budget": True,
+                           "clipped": _clip(line, half, half)}, ensure_ascii=False)
+    return line
+
+
+def _redact(text: str, secret: str | None) -> str:
+    return text.replace(secret, "***") if secret else text
+
+
+def _payload_from_prompt(prompt: str) -> dict:
+    """Recover the full payload dict from `Actor.judge()`'s own fixed prompt format
+    (`papeete_actor_synchronous_messaging.actor.Actor.judge`):
+
+        f"verb: {verb}\\ndoor: {offer.id}\\n{as_prompt_json(situation)}"
+
+    where `situation["payload"]` is exactly what the caller sent at this door.
+    """
+    lines = prompt.split("\n", 2)
+    if len(lines) < 3:
+        raise EngineError(f"prompt does not follow Actor.judge()'s fixed format: {prompt!r}")
+    try:
+        situation = json.loads(lines[2])
+        return situation["payload"]
+    except (json.JSONDecodeError, KeyError, TypeError) as e:
+        raise EngineError(f"could not recover payload from prompt: {e}") from e
+
+
+class ClaudeCodeEngine:
+    """Judgement by shelling out to the `claude` CLI, against a fresh private clone."""
+
+    def __init__(self, config: CapabilityConfig, *,
+                 github_token: str | None = None, claude_bin: str = "claude",
+                 clone_timeout: int = DEFAULT_CLONE_TIMEOUT_S,
+                 fetch_timeout: int = grounding.DEFAULT_FETCH_TIMEOUT_S,
+                 session_timeout: int = DEFAULT_SESSION_TIMEOUT_S,
+                 max_turns: int = DEFAULT_MAX_TURNS):
+        self.config = config
+        # The engine's `name` is what the card's door names, so it comes from the sidecar rather
+        # than being fixed here — the port requires the attribute, not a particular value.
+        self.name = config.engine
+
+        self.github_token = github_token or os.environ.get("GITHUB_TOKEN")
+        if not self.github_token:
+            raise RuntimeError(
+                "ClaudeCodeEngine needs GITHUB_TOKEN in the environment — a fine-grained PAT with "
+                f"contents:write on {config.source_repo}, plus read-only contents on "
+                f"{config.registry_repo} and whatever else this capability's `ground_in` fetches "
+                "resolve through."
+            )
+        self.claude_bin = claude_bin
+        self.clone_timeout = clone_timeout
+        self.fetch_timeout = fetch_timeout
+        self.session_timeout = session_timeout
+        self.max_turns = max_turns
+        self._configure_git_credentials()
+
+    # ── the one Engine method ──────────────────────────────────────────────────────────────
+
+    def judge(self, *, system: str, prompt: str, schema: dict | None = None) -> dict:
+        payload = _payload_from_prompt(prompt)
+        task_id = payload["task_id"]
+        # The FIRST thing this door does, before anything that could fail: from here to the end
+        # of this request's own thread, every record — this module's, handler.py's, and the HTTP
+        # binding's own access line — carries both ids. `correlation_id()` reads the trace id the
+        # orchestrating actor already propagated, so every actor in the pipeline agrees on it
+        # without any of them passing it (see correlation.py).
+        correlation.bind(correlation_id=correlation.correlation_id(), task_id=task_id)
+
+        clone_dir = Path(tempfile.mkdtemp(prefix=self.config.clone_prefix(task_id)))
+
+        try:
+            with correlation.stage("clone-code", repo=self.config.source_repo):
+                self._clone(clone_dir)
+
+            branch = f"impl/{task_id}"
+            self._git(clone_dir, ["checkout", "-b", branch])
+
+            # Grounding is a PRECONDITION, not a request — see grounding.py. It runs before the
+            # prompt is even built, and a failure here stops the request before any session time
+            # is spent, which is the cheapest place for it to stop.
+            for entry in self.config.ground_in:
+                with correlation.stage(f"ground-{entry.name}", into=entry.into, load=entry.load):
+                    envelope = grounding.fetch(self.config, entry, timeout=self.fetch_timeout)
+                    grounding.write_envelope(self.config, entry, clone_dir, envelope)
+            grounding.render_claude_md(self.config, clone_dir)
+
+            situational_prompt = self._situational_prompt(payload)
+            with correlation.stage("claude-session", branch=branch,
+                                   max_turns=self.max_turns, timeout_s=self.session_timeout):
+                summary = self._invoke_claude(clone_dir, system, situational_prompt)
+        except BaseException:
+            # Every failure path removes the clone. Success does not: the clone is handed off
+            # live, and `handler.py` is what removes it once it has committed and pushed — or
+            # refused for containment.
+            _rmtree(clone_dir)
+            raise
+
+        return {
+            "implemented": True,
+            "clone_dir": str(clone_dir),
+            "branch": branch,
+            "summary": summary,
+        }
+
+    # ── git ─────────────────────────────────────────────────────────────────────────────────
+
+    def _configure_git_credentials(self) -> None:
+        """Make GITHUB_TOKEN available to subprocesses that do their own git clones.
+
+        A `ground_in` tool typically delegates git auth entirely to git's own credential
+        resolution and never takes a token itself. A global URL rewrite is the one hook available
+        to make those clones use this token too, without patching the tool. Idempotent; safe to
+        call on every construction.
+        """
+        subprocess.run(
+            ["git", "config", "--global",
+             f"url.https://x-access-token:{self.github_token}@github.com/.insteadOf",
+             "https://github.com/"],
+            check=True, capture_output=True, text=True,
+        )
+
+    def _clone(self, dest: Path) -> None:
+        # Full clone, not --depth 1: `papeete_version.compute()`'s own `semver_base()` does `git
+        # describe --tags --match <name>/v*` against this clone, which needs the matching tag's
+        # commit reachable in local history — a shallow clone only has the tip commit, and breaks
+        # the moment the tag isn't that exact commit (verified live: it worked only by accident
+        # while the repo's origin/main was still a single commit).
+        url = f"https://x-access-token:{self.github_token}@github.com/{self.config.source_repo}.git"
+        try:
+            subprocess.run(
+                ["git", "clone", url, str(dest)],
+                check=True, capture_output=True, text=True, timeout=self.clone_timeout,
+            )
+        except subprocess.CalledProcessError as e:
+            raise EngineError(
+                f"could not clone {self.config.source_repo}: "
+                f"{_redact(e.stderr, self.github_token)}"
+            ) from e
+        except subprocess.TimeoutExpired as e:
+            raise EngineError(
+                f"cloning {self.config.source_repo} timed out after {self.clone_timeout}s"
+            ) from e
+
+    def _git(self, clone_dir: Path, args: list[str]) -> str:
+        try:
+            result = subprocess.run(
+                ["git", *args], cwd=clone_dir, check=True, capture_output=True, text=True,
+            )
+        except subprocess.CalledProcessError as e:
+            raise EngineError(
+                f"git {' '.join(args)} failed: {_redact(e.stderr, self.github_token)}"
+            ) from e
+        return result.stdout
+
+    # ── situational prompt, built from the caller's own payload ───────────────────────────
+
+    def _situational_prompt(self, payload: dict) -> str:
+        """The task, and nothing else.
+
+        NOTE WHAT IS ABSENT: any instruction to go and read the capability's context. That used
+        to be a paragraph here, naming two files in a sibling tempdir and asking the session to
+        read them "before you start". It is a precondition now — the generated `CLAUDE.md` is
+        loaded before turn one — so asking for it again would be asking for something already
+        done, in the one place a session is most likely to take the instruction literally and
+        spend a turn on it.
+        """
+        config = self.config
+        task_id = payload["task_id"]
+        boundary = ", ".join(config.writes_only_under)
+
+        sections = [
+            f"# Implement {task_id} for {config.capability}: {payload['title']}\n\n"
+            f"You are working inside your own private clone (branch already checked out). "
+            f"Write ONLY under {boundary} — nothing else in this clone is yours to change. "
+            f"Do not `git add`, `git commit`, or `git push` — that is handled outside this "
+            f"session. Iterate the test suite(s) of whichever component(s) you touch "
+            f"({', '.join(config.test_paths)}) until green before you finish.\n\n"
+            f"Scope this session to {task_id}'s own Definition of Done against the CURRENT state "
+            f"of {boundary} — extend what's already there for whichever component(s) this task "
+            f"touches, don't re-derive or re-verify the whole capability's surface from scratch."
+        ]
+        if payload.get("context"):
+            sections.append(f"## Context\n{payload['context']}")
+        sections.append(
+            "## Definition of done\n"
+            + "\n".join(f"- {item}" for item in payload["definition_of_done"])
+        )
+        if payload.get("remediation_context"):
+            sections.append(
+                "## Remediation — the prior attempt's failing test criteria\n"
+                f"{payload['remediation_context']}"
+            )
+        return "\n\n".join(sections)
+
+    # ── the judgement itself: a claude -p session against the checked-out clone ────────────
+
+    def _invoke_claude(self, clone_dir: Path, system: str, situational_prompt: str) -> str:
+        """Run the session, streaming every turn to the log as it happens.
+
+        `--output-format stream-json --verbose` rather than `--output-format json`: the latter
+        emits ONE object at the end, holding only the final assistant text, so the whole inner
+        conversation — what was read, what was run, what was decided — existed nowhere durable
+        once the pod went away. The projection above is what makes streaming it affordable.
+
+        `Popen` rather than `subprocess.run`: reading line by line is what lets each turn be
+        logged as it happens rather than after the session ends, and it stops a 30-minute
+        session's entire output being buffered in a pod capped at 2Gi.
+        """
+        cmd = [
+            self.claude_bin, "--print", "--output-format", "stream-json", "--verbose",
+            "--append-system-prompt", system,
+            "--permission-mode", "acceptEdits",
+            "--allowedTools", "Bash,Read,Edit,Write,Glob,Grep",
+            "--max-turns", str(self.max_turns),
+            situational_prompt,
+        ]
+        # stderr to a temp file, not a second pipe: nothing drains a second pipe while the
+        # stdout loop below runs, so a chatty stderr would fill its buffer and deadlock the
+        # session. Merging it into stdout is not an option either — it would corrupt the stream.
+        with tempfile.TemporaryFile("w+") as errfile:
+            try:
+                proc = subprocess.Popen(cmd, cwd=clone_dir, stdout=subprocess.PIPE,
+                                        stderr=errfile, text=True, bufsize=1)
+            except FileNotFoundError as e:
+                raise EngineError(
+                    f"'{self.claude_bin}' is not on PATH — install @anthropic-ai/claude-code"
+                ) from e
+
+            # A watchdog, not a deadline checked per line: a session that hangs having emitted
+            # nothing would never reach another loop iteration to be checked, and `Popen` has no
+            # equivalent of `subprocess.run(timeout=...)` while iterating its output.
+            timed_out = threading.Event()
+
+            def _expire() -> None:
+                timed_out.set()
+                proc.kill()
+
+            watchdog = threading.Timer(self.session_timeout, _expire)
+            watchdog.start()
+
+            final: dict | None = None
+            try:
+                for raw in proc.stdout:
+                    try:
+                        event = json.loads(raw)
+                    except json.JSONDecodeError:
+                        continue          # a non-JSON line is noise, never the session's result
+                    record = _project(event)
+                    if record is not None:
+                        # No %-args: `logging` only applies %-formatting when args are passed,
+                        # so a stray % in a file body cannot raise here. No `extra=` either —
+                        # `correlation.bind()` in `judge()` above already stamps task_id and
+                        # correlation_id onto every record emitted on this thread.
+                        logging.info(_line(record))
+                    if event.get("type") == "result":
+                        final = event
+                proc.wait()
+            finally:
+                watchdog.cancel()
+                if proc.poll() is None:
+                    proc.kill()
+                    proc.wait()
+                proc.stdout.close()
+
+            if timed_out.is_set():
+                raise EngineError(
+                    f"claude session for this task exceeded {self.session_timeout}s"
+                )
+            errfile.seek(0)
+            stderr = errfile.read()
+
+        if final is None:
+            raise EngineError(
+                f"claude (rc={proc.returncode}) produced no result event: {stderr[-2000:]}"
+            )
+        if final.get("is_error") or proc.returncode != 0:
+            raise EngineError(
+                f"claude session failed (subtype={final.get('subtype')}): "
+                f"{final.get('result', '')[:4000]}"
+            )
+        return final.get("result", "")
+
+
+def _rmtree(path: Path) -> None:
+    shutil.rmtree(path, ignore_errors=True)