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

foundry_testing_actor/engine.py

@@ -0,0 +1,889 @@
+"""`ClaudeCodeTesterEngine` — judgement by a headless Claude Code session against fresh clones.
+
+TESTING AUTHORS A HARNESS; IT DOES NOT EXECUTE IT. No session this engine starts brings up docker
+or docker compose, hits a live endpoint, or renders a pass/fail verdict. At `test-task` it writes
+and extends black-box pytest source; at `propose-acceptance` it writes nothing at all. Standing up
+infrastructure and rendering the verdict belongs to the orchestrating actor alone, against a real
+ephemeral deployment, running the test image `handler.py` publishes.
+
+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.
+
+TWO CLONES, AND WHAT EACH DOOR MAY SEE OF THE SECOND. The testing repo is this actor's own, and
+every session runs inside a private clone of it. The implementation repo is read, never written,
+and the two doors read it for opposite reasons:
+
+  * `propose-acceptance` clones its DEFAULT BRANCH and shows it to the session — the capability as
+    it stands BEFORE the increment. It never checks out `impl/<task_id>`: a tester whose
+    assertions are derived from what was built can only ever confirm the build (ADR-FIA-0004's
+    "before or after", ADR-FTA-0002).
+  * `test-task` checks out `impl/<task_id>` and does NOT show it to the session. It is there so
+    `papeete_version.compute` can recompute, over identical inputs, the image refs the
+    implementation actor published — no tag is ever handed to this actor, and none has to be.
+
+NO KNOWLEDGE TOOL IS NAMED HERE. The hand-written actor this replaces shelled out to two knowledge
+tools by name, with the registry they resolved through as a module constant. Both are `ground_in`
+entries in a use's sidecar now, run by `grounding.py` like any other argv (ADR-FTA-0001).
+
+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`).
+
+WHAT THIS ENGINE DOES NOT DO. It never commits, pushes, builds, 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 at `test-task`
+it deliberately does NOT clean up its clones: the handler still needs the testing clone to commit
+and push, and is the one that removes both, on every path including containment failure.
+"""
+from __future__ import annotations
+
+import json
+import logging
+import os
+import re
+import shutil
+import subprocess
+import tempfile
+import threading
+from pathlib import Path
+
+from papeete_actor_synchronous_messaging.engine import EngineError
+from papeete_version.version import compute as compute_version
+from papeete_version.version import normalize_name
+
+from . import correlation, grounding
+from .config import CapabilityConfig, Component
+
+DEFAULT_CLONE_TIMEOUT_S = 120
+DEFAULT_SESSION_TIMEOUT_S = 1800
+DEFAULT_MAX_TURNS = 60
+
+# The propose door reads and answers; it never writes. Its budget is smaller than the test door's
+# on every axis, and its tool list is the enforcement — a door that CANNOT write beats one asked
+# not to. The same numbers as the implementation actor's assess door, deliberately: the two halves
+# of one round should cost the same order of money (ADR-FIA-0004, ADR-FTA-0002).
+DEFAULT_PROPOSE_TIMEOUT_S = 600
+DEFAULT_PROPOSE_MAX_TURNS = 15
+
+TEST_TOOLS = "Bash,Read,Edit,Write,Glob,Grep"
+PROPOSE_TOOLS = "Read,Glob,Grep"
+
+# The door ids this engine answers. They are the card's, not this module's invention — `judge()`
+# is handed the id it must dispatch on (see `_door_from_prompt`).
+TEST_DOOR = "test-task"
+PROPOSE_DOOR = "propose-acceptance"
+
+# The branch conventions both peers already follow, so nothing has to be looked up to know them.
+IMPLEMENTATION_BRANCH = "impl/{task_id}"
+TEST_BRANCH = "test/{task_id}"
+
+# The name the implementation repo's default-branch clone is shown to the propose session under.
+# A directory ADDED to the session beside its working directory, not a path inside the testing
+# clone: a nested repository there would be one `git add` away from the tests this actor commits.
+_CODE_CLONE_LABEL = "the implementation repository, default branch"
+
+
+# ── 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
+
+
+# ```json … ``` or a bare ``` … ``` block. Non-greedy, DOTALL: one match per fence, in order.
+_FENCE = re.compile(r"```(?:json)?\s*\n(.*?)```", re.DOTALL)
+
+
+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
+
+
+def _door_from_prompt(prompt: str) -> str:
+    """Recover the door id from `Actor.judge()`'s own fixed prompt format — its second line.
+
+    ONE ENGINE, TWO DOORS. The `Engine` port is a single `judge()`, and both this actor's doors
+    name the same engine key, so an instance registered under `claude-code` is asked to judge
+    both. `Actor.judge()` already puts the door id on line 2 of the prompt it builds, so the
+    dispatch needs nothing from the framework that is not already being handed over.
+    """
+    lines = prompt.split("\n", 2)
+    if len(lines) < 2 or not lines[1].startswith("door: "):
+        raise EngineError(f"prompt does not follow Actor.judge()'s fixed format: {prompt!r}")
+    return lines[1][len("door: "):].strip()
+
+
+def _extract_json(text: str) -> dict:
+    """The single JSON object a judged answer ends with.
+
+    A session's final `result` is prose that HAPPENS to contain the answer, not the answer — it
+    reliably wraps it in a fence and unreliably says something either side of it. So: try every
+    fenced block, last first (the last one is the conclusion; an earlier one is usually the
+    session quoting what it was asked for), then the whole text for the case where it complied
+    exactly. Anything else is an `EngineError` — a door that cannot say what it decided has not
+    decided anything, and guessing on its behalf would be worse than failing.
+    """
+    for block in reversed(_FENCE.findall(text)):
+        try:
+            parsed = json.loads(block)
+        except json.JSONDecodeError:
+            continue
+        if isinstance(parsed, dict):
+            return parsed
+    try:
+        parsed = json.loads(text.strip())
+    except json.JSONDecodeError:
+        parsed = None
+    if isinstance(parsed, dict):
+        return parsed
+    raise EngineError(
+        "the session produced no JSON object to read its judgement from; its answer ended: "
+        f"{text[-2000:]!r}"
+    )
+
+
+def _as_list(value) -> list:
+    """A session's idea of "a list of questions", as a list.
+
+    Absent or null is none; a lone string or object is one. Coerced rather than trusted: a session
+    reliably means the list and unreliably types it, and `Actor.receive()` would refuse the whole
+    proposal over one question that arrived bare.
+    """
+    if value is None:
+        return []
+    if isinstance(value, list):
+        return value
+    return [value]
+
+
+def _proposal(judged: dict) -> dict:
+    """The reply `acceptance-proposed-result` can carry, and nothing else.
+
+    PROJECTED, NOT PASSED THROUGH. A door naming ONE completion message gets an open schema from
+    the framework (ADR-PAS-0009), so a session's helpful `"notes"` key beside its answer would not
+    be refused — it would travel to the orchestrating actor looking like part of a contract three
+    packages share, which is worse. And the day this door names a second outcome, the framework
+    closes the schema and that same key refuses the whole proposal. Only the two fields the message
+    references survive; everything else a session said is in the transcript.
+
+    WHAT IS CHECKED, AND WHY IT IS NOT MORE. `expectations` must be a list of objects, each with an
+    `id` and a `statement`, a `handle` key, and ids unique within the proposal — because a later
+    verdict names an expectation by its id, and the orchestrating actor attaches the implementer's
+    commitments by it too. Two expectations sharing one id cannot both be named. What a handle
+    CONTAINS is not checked: its shape depends on what is being addressed, and the card types the
+    surface as a list precisely so that stays prose.
+    """
+    if "expectations" not in judged:
+        raise EngineError(
+            "the proposal named no `expectations` — the one thing the caller has to be able to "
+            f"send on; it answered: {judged!r}"
+        )
+    expectations = judged["expectations"]
+    if not isinstance(expectations, list):
+        raise EngineError(f"`expectations` is not a list: {expectations!r}")
+    seen: set[str] = set()
+    for index, expectation in enumerate(expectations):
+        if not isinstance(expectation, dict):
+            raise EngineError(f"expectations[{index}] is not an object: {expectation!r}")
+        missing = [key for key in ("id", "statement") if not expectation.get(key)]
+        if missing or "handle" not in expectation:
+            raise EngineError(
+                f"expectations[{index}] carries no {', '.join(missing or ['handle'])} — every "
+                f"expectation is an id, a statement and a handle: {expectation!r}"
+            )
+        identifier = str(expectation["id"])
+        if identifier in seen:
+            raise EngineError(
+                f"expectation id '{identifier}' is proposed twice — a verdict names an "
+                f"expectation by its id, so an id two expectations share names neither"
+            )
+        seen.add(identifier)
+    return {"expectations": expectations, "open_questions": _as_list(judged.get("open_questions"))}
+
+
+class ClaudeCodeTesterEngine:
+    """Judgement by shelling out to the `claude` CLI, against fresh private clones."""
+
+    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,
+                 propose_timeout: int = DEFAULT_PROPOSE_TIMEOUT_S,
+                 propose_max_turns: int = DEFAULT_PROPOSE_MAX_TURNS):
+        self.config = config
+        # The engine's `name` is what the card's doors name, 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(
+                "ClaudeCodeTesterEngine needs GITHUB_TOKEN in the environment — a fine-grained "
+                f"PAT with contents:write on {config.source_repo}, read-only contents on "
+                f"{config.implementation_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
+        # Constructor kwargs, not sidecar fields: how long this actor's own doors may think is
+        # operational tuning, not something a capability declares about itself.
+        self.propose_timeout = propose_timeout
+        self.propose_max_turns = propose_max_turns
+        self._configure_git_credentials()
+
+    # ── the one Engine method ──────────────────────────────────────────────────────────────
+
+    def judge(self, *, system: str, prompt: str, schema: dict | None = None) -> dict:
+        """The one `Engine` method, serving both of this actor's doors.
+
+        The port is a single `judge()`, and both doors name the same engine key, so the dispatch
+        is on the door id `Actor.judge()` already puts on line 2 of the prompt. The two paths are
+        deliberately asymmetric: `test-task` hands its clones off live to the handler, which
+        commits, pushes, publishes and then removes them; `propose-acceptance` owns its clones
+        from end to end and writes nothing anywhere.
+        """
+        door = _door_from_prompt(prompt)
+        if door == PROPOSE_DOOR:
+            return self._propose(_payload_from_prompt(prompt), schema)
+        if door == TEST_DOOR:
+            return self._test(system, _payload_from_prompt(prompt))
+        raise EngineError(
+            f"this engine answers {TEST_DOOR} and {PROPOSE_DOOR}, not '{door}' — a door naming "
+            f"this engine must be one it knows how to judge"
+        )
+
+    # ── test-task: the door that authors ───────────────────────────────────────────────────
+
+    def _test(self, system: str, payload: dict) -> dict:
+        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)
+
+        # Both resolved before a single clone: an undeclared component and an unset registry are
+        # facts about the request and the environment, and neither needs a network to find out.
+        components = self._components(payload["components"])
+        registry = _image_registry()
+
+        test_clone = Path(tempfile.mkdtemp(prefix=self.config.clone_prefix(task_id)))
+        code_clone = Path(tempfile.mkdtemp(prefix=self.config.code_clone_prefix(task_id)))
+        branch = TEST_BRANCH.format(task_id=task_id)
+        try:
+            with correlation.stage("clone-tests", repo=self.config.source_repo):
+                self._clone(test_clone, self.config.source_repo)
+            with correlation.stage("clone-code", repo=self.config.implementation_repo):
+                self._clone(code_clone, self.config.implementation_repo)
+            # The implementation actor committed, and computed its published tags, on
+            # impl/<task_id> — never on the default branch, because no pull request is opened
+            # until orchestration has a passing verdict. Checked out HERE ONLY, to recompute those
+            # tags; this clone is never shown to the session below.
+            self._git(code_clone, ["checkout", IMPLEMENTATION_BRANCH.format(task_id=task_id)])
+            self._git(test_clone, ["checkout", "-b", branch])
+
+            images = [self._resolve_image(code_clone, component.name, task_id, registry)
+                      for component in components]
+            correlation.event("images-under-test", components=[c.name for c in components],
+                              images=images)
+
+            self._ground(test_clone)
+
+            situational_prompt = self._situational_prompt(payload, components, images)
+            with correlation.stage("claude-session", branch=branch,
+                                   max_turns=self.max_turns, timeout_s=self.session_timeout):
+                summary = self._invoke_claude(test_clone, system, situational_prompt)
+        except BaseException:
+            # Every failure path removes both clones. Success does not: they are handed off live,
+            # and `handler.py` is what removes them once it has committed, pushed and published —
+            # or refused for containment.
+            _rmtree(test_clone)
+            _rmtree(code_clone)
+            raise
+
+        return {
+            "testable": True,
+            "clone_dir": str(test_clone),
+            "code_clone_dir": str(code_clone),
+            "branch": branch,
+            "summary": summary,
+        }
+
+    def _components(self, names: list) -> list[Component]:
+        """The declared components a `test-task` payload names, in the order it names them.
+
+        REFUSED, NOT FILTERED. The hand-written actor this replaces silently dropped a name it had
+        no tests root for, and answered for the rest — which reads, downstream, exactly like a
+        component whose tests were written. A caller naming a component this use does not declare
+        is told so before any session time is spent.
+        """
+        resolved, unknown = [], []
+        for name in names:
+            component = self.config.component(str(name))
+            (resolved if component else unknown).append(component or name)
+        if unknown:
+            declared = ", ".join(c.name for c in self.config.components)
+            raise EngineError(
+                f"no declared component named {', '.join(map(str, unknown))} — this use writes "
+                f"tests for {declared}"
+            )
+        if not resolved:
+            raise EngineError("the payload names no component to write tests for")
+        return resolved
+
+    def _resolve_image(self, code_clone: Path, component: str, task_id: str,
+                       registry: str) -> str:
+        """Recompute the ref the implementation actor published, over identical inputs.
+
+        Including `normalize_name(task_id)`, which that actor's own publisher passes. These two
+        must agree exactly: a divergence does not raise, it silently names an image that was never
+        built. The folder is `<component>/` in the implementation clone — see the schema's
+        `components` doc for why a component's name is also where its implementation lives.
+        """
+        try:
+            version = compute_version(
+                folder=code_clone / component,
+                name=self.config.image_name(component),
+                label="feature",
+                feature_name=normalize_name(task_id),
+            )
+        except ValueError as e:
+            raise EngineError(f"could not resolve {component}'s published image: {e}") from e
+        return self.config.image_ref(registry, component, version)
+
+    # ── propose-acceptance: the door that only answers ─────────────────────────────────────
+
+    def _propose(self, payload: dict, schema: dict | None) -> dict:
+        """Propose what this actor will assert, black-box, before anything is built. Write nothing.
+
+        THE CLONES ARE OWNED HERE, END TO END. `_test` hands its clones off live because the
+        handler still has to commit and push. This door has no handler and produces no artifact,
+        so the `finally` is unconditional — success removes both clones exactly as failure does.
+
+        NO BRANCH IS CHECKED OUT, IN EITHER CLONE. There is nothing to put on one in the testing
+        repo, and in the implementation repo there must not be: `impl/<task_id>` may already exist
+        from an earlier attempt, and a proposal read off it would be a report of the build dressed
+        as a proposal. The default branch is the state the increment is being proposed against.
+        """
+        task_id = payload["task_id"]
+        correlation.bind(correlation_id=correlation.correlation_id(), task_id=task_id)
+
+        test_clone = Path(tempfile.mkdtemp(prefix=self.config.clone_prefix(task_id)))
+        code_clone = Path(tempfile.mkdtemp(prefix=self.config.code_clone_prefix(task_id)))
+        try:
+            with correlation.stage("clone-tests", repo=self.config.source_repo):
+                self._clone(test_clone, self.config.source_repo)
+            with correlation.stage("clone-code", repo=self.config.implementation_repo):
+                self._clone(code_clone, self.config.implementation_repo)
+            self._ground(test_clone)
+
+            with correlation.stage("propose-session", max_turns=self.propose_max_turns,
+                                   timeout_s=self.propose_timeout):
+                answer = self._invoke_claude(
+                    test_clone, self._propose_system(),
+                    self._proposal_prompt(payload, schema, code_clone),
+                    allowed_tools=PROPOSE_TOOLS, max_turns=self.propose_max_turns,
+                    timeout=self.propose_timeout, add_dirs=(code_clone,),
+                )
+        finally:
+            _rmtree(test_clone)
+            _rmtree(code_clone)
+
+        proposal = _proposal(_extract_json(answer))
+        correlation.event("acceptance-proposed",
+                          expectations=[e["id"] for e in proposal["expectations"]],
+                          open_questions=len(proposal["open_questions"]))
+        return proposal
+
+    def _propose_system(self) -> str:
+        """The system prompt for the propose door.
+
+        NOT `Actor.judge()`'s own. That one is built from the whole card and ends with "Reply with
+        a single JSON object capturing your judgement" — which is right, and is passed through
+        unmodified for `test-task`. But it is handed to this engine as `system` on both doors, and
+        this door needs the session to spend its turns READING rather than answering from the
+        card's prose alone.
+        """
+        return (
+            "You are proposing, not testing. Read the task, the capability context you have been "
+            "given, the existing test suite and the implementation as it stands today, then say "
+            "precisely what you will assert black-box once the increment is built — and what the "
+            "task leaves undetermined. Do not write, edit or create any file; you have no tools "
+            "to do so."
+        )
+
+    def _ground(self, clone_dir: Path) -> None:
+        """Fetch every `ground_in` source into the clone and render its `CLAUDE.md`.
+
+        Grounding is a PRECONDITION, not a request — see grounding.py. It runs before either
+        door's prompt is built, and a failure here stops the request before any session time is
+        spent, which is the cheapest place for it to stop. Both doors ground identically: what
+        will be asserted needs the same standing context as writing the assertion.
+        """
+        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)
+
+    # ── 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, repo: str) -> None:
+        # Full clone, not --depth 1: `papeete_version.compute()`'s own `semver_base()` does `git
+        # describe --tags --match <name>/v*` against a clone — this actor's own, to version its
+        # test image, and the implementation's, to recompute the image under test — 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.
+        url = f"https://x-access-token:{self.github_token}@github.com/{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 {repo}: {_redact(e.stderr, self.github_token)}"
+            ) from e
+        except subprocess.TimeoutExpired as e:
+            raise EngineError(f"cloning {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, components: list[Component],
+                            images: list[str]) -> str:
+        """The task, and nothing else.
+
+        NOTE WHAT IS ABSENT: any instruction to go and read the capability's context, and any
+        path to it. The hand-written actor named two JSON files in a sibling tempdir and asked 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.
+
+        THE `<COMPONENT>_URL` CONVENTION STAYS, AS A DEFAULT. It is the one addressing agreement
+        this actor and the orchestrating actor have always shared. An agreed acceptance surface
+        can now state a handle's own variable, and where it does, the surface is the more specific
+        statement and wins.
+        """
+        config = self.config
+        task_id = payload["task_id"]
+        roots = ", ".join(c.tests for c in components)
+        image_lines = "\n".join(f"  - {c.name}: {image}" for c, image in zip(components, images))
+        existing = "\n".join(f"  - {c.tests}" for c in components)
+
+        sections = [
+            f"# Author/extend black-box tests for {task_id} of {config.capability}: "
+            f"{payload['title']}\n\n"
+            f"You are working inside your own private clone (branch already checked out). Write "
+            f"ONLY under {roots} — nothing else in this clone is yours to change. Do not "
+            f"`git add`, `git commit`, or `git push` — that is handled outside this session.\n\n"
+            f"This is a PERSISTENT, accumulated test suite, not a fresh one for this task alone "
+            f"— read what is already there first and extend or adjust it for {task_id}'s own "
+            f"Definition of Done, rather than re-deriving the whole black-box surface from "
+            f"scratch:\n{existing}\n\n"
+            f"The published image(s) this suite targets (already built elsewhere — you do NOT "
+            f"bring these up yourself, and you have NOT been given their source):\n{image_lines}"
+            f"\n\n"
+            f"Each test reads its target component's base URL from an environment variable named "
+            f"<COMPONENT>_URL (uppercase, e.g. BACKEND_URL for a component named backend), unless "
+            f"the agreed acceptance surface below names another one in an expectation's handle. "
+            f"The orchestrating actor sets it to the running deployment's real address when it "
+            f"runs the published test image; you never set or resolve it yourself.\n\n"
+            f"You must NOT bring up docker or docker compose, hit a live endpoint, or otherwise "
+            f"run these tests against running infrastructure — this session only authors pytest "
+            f"source. Ground the exact request/response shapes, status codes and event contracts "
+            f"you assert in this capability's standing context and the existing suite's own "
+            f"conventions, not by probing a live container. `pytest --collect-only` (no network "
+            f"calls) is fine as a syntax/import check; running the suite is not — that verdict "
+            f"belongs to the orchestrating actor alone, against a real ephemeral deployment."
+        ]
+        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("acceptance_surface"):
+            # Agreed in the round before any of this was built: proposed at this actor's own
+            # propose-acceptance door, and accepted (with commitments) by the implementer. The ids
+            # are what a later verdict names, which is why every test has to carry one.
+            sections.append(
+                "## Agreed acceptance surface\n"
+                "This was agreed with the implementer before anything was built. Each expectation "
+                "below must be asserted by its `id`, addressing it exactly via its `handle` — "
+                "including any value committed to there. Where it is more specific than the "
+                "definition of done, it wins. Name the expectation id in each test that asserts "
+                "it (in the test's name or its docstring), so a failing verdict points at an "
+                "agreed expectation rather than at a line of output.\n\n"
+                + json.dumps(payload["acceptance_surface"], indent=2, ensure_ascii=False)
+            )
+        if payload.get("remediation_context"):
+            sections.append(
+                "## Remediation — the prior attempt's failing criteria\n"
+                "A criterion failing could mean the test itself was wrong (bad expectation, "
+                "wrong endpoint, wrong shape) or that the implementation was wrong. Review each "
+                "one: fix the test here if the fault is in it; if the test looks correct against "
+                "this capability's standing context and the agreed acceptance surface, leave it "
+                "as-is (the implementation side should fix it instead) and say so in your "
+                "summary.\n"
+                f"{payload['remediation_context']}"
+            )
+        return "\n\n".join(sections)
+
+    # ── the proposal prompt ─────────────────────────────────────────────────────────────────
+
+    def _proposal_prompt(self, payload: dict, schema: dict | None, code_clone: Path) -> str:
+        """What the propose door asks. Nothing about writing, because it cannot.
+
+        PROPOSE VALUES, DO NOT WAIT FOR THEM. The failure this round exists for is a test tree
+        carrying fixture ids "discovered black-box against the running container", against a task
+        that never named them (ADR-FIA-0004). Where a test will need a concrete value the task
+        leaves unnamed, the session proposes one here, and the implementer commits to it or
+        objects at its own assess door. A value a tester proposes before the build is a promise
+        someone must keep; the same value read off the build is a report.
+
+        QUESTIONS ARE NOT FAILURES. What neither the task nor the standing context determines —
+        and what no proposed value can responsibly settle, because it is a question of what the
+        behaviour SHOULD be — goes in `open_questions`, never into an invented statement. Any open
+        question stops the round and reaches a human, which is the point of asking it.
+
+        THE ANSWER'S SHAPE IS DERIVED, NOT INVENTED HERE. `Actor.judge()` computes it from the
+        door's own `completion_schema` and hands it over as `schema`; rendering that is how the
+        prompt and the card cannot come to disagree. When it is absent — an engine driven directly,
+        in a test or a probe — the fallback below says the same thing in words.
+        """
+        config = self.config
+        task_id = payload["task_id"]
+        names = [str(name) for name in payload.get("components") or []]
+        component_lines = []
+        for name in names:
+            declared = config.component(name)
+            component_lines.append(
+                f"  - {name}: its tests live under {declared.tests}" if declared else
+                f"  - {name}: (this use declares no tests root for it — say so in open_questions "
+                f"if the task needs it asserted)")
+
+        sections = [
+            f"# What will you assert for {task_id} of {config.capability}: {payload['title']}?\n\n"
+            f"NOTHING HAS BEEN BUILT YET. The implementer has not started. Before it does, you "
+            f"propose the acceptance surface: exactly what you will assert, black-box, about this "
+            f"increment once it exists. The implementer then answers whether it can deliver each "
+            f"expectation, commits to the values a test will address, or objects.\n\n"
+            f"You are READING ONLY. Do not write, edit or create any file — you have no tools to "
+            f"do so, and there is no branch and no commit at this door.\n\n"
+            f"What you can read:\n"
+            f"  - your working directory: this actor's own testing repository, with the existing "
+            f"accumulated suite under {', '.join(config.writes_only_under)}\n"
+            f"  - {code_clone}: {_CODE_CLONE_LABEL} — the capability as it stands BEFORE this "
+            f"increment. Use it to align with what already exists; never treat it as the "
+            f"increment itself\n"
+            f"  - this capability's standing context, already loaded for this session\n\n"
+            f"Propose each expectation as an object with:\n"
+            f"  - `id`: short and stable (`E1`, or kebab-case), unique within this proposal — a "
+            f"later verdict names it\n"
+            f"  - `statement`: what must hold, observable from outside the component\n"
+            f"  - `handle`: exactly how a black-box test reaches it — the component, the endpoint "
+            f"(method and path), the event routing key, the environment variable carrying its "
+            f"base URL (<COMPONENT>_URL unless you need another)\n"
+            f"  - `component` (optional): which of the components below it belongs to\n\n"
+            f"Where a test needs a concrete value the task does not name — a fixture's id, a "
+            f"seeded record, a path parameter, a routing key — PROPOSE A CONCRETE VALUE in the "
+            f"handle. The implementer will accept it and commit to it, or object. Do not leave it "
+            f"for the implementation to choose and for a test to discover afterwards.\n\n"
+            f"Anything the task and the standing context do not determine, and that no proposed "
+            f"value can settle because it is a question of what the behaviour should BE, goes in "
+            f"`open_questions` — never into an invented statement. An open question is not a "
+            f"failure: it stops this round and reaches a human, which is exactly what it is for."
+        ]
+        sections.append(
+            "## Components this round concerns\n"
+            + ("\n".join(component_lines) if component_lines else "  (none named)")
+        )
+        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"])
+        )
+        sections.append(
+            "## Your answer\n"
+            "End with a single fenced ```json block and nothing after it, holding one object"
+            + (f" conforming to:\n\n```json\n{json.dumps(schema, indent=2)}\n```"
+               if schema else
+               " with `expectations` (a list of objects, each with `id`, `statement` and "
+               "`handle`) and `open_questions` (a list of strings, or of objects with `about` and "
+               "`question`; empty when the task determines everything).")
+        )
+        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, *,
+                       allowed_tools: str = TEST_TOOLS,
+                       max_turns: int | None = None,
+                       timeout: int | None = None,
+                       add_dirs: tuple[Path, ...] = ()) -> 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.
+        """
+        max_turns = self.max_turns if max_turns is None else max_turns
+        timeout = self.session_timeout if timeout is None else timeout
+        cmd = [self.claude_bin, "--print", "--output-format", "stream-json", "--verbose"]
+        for directory in add_dirs:
+            # BEFORE another option, never last. `--add-dir` takes a variadic list, and a
+            # variadic option followed by the positional prompt would swallow the prompt as a
+            # second directory. `--append-system-prompt` right after it closes the list.
+            cmd += ["--add-dir", str(directory)]
+        cmd += [
+            "--append-system-prompt", system,
+            "--permission-mode", "acceptEdits",
+            # The propose door passes a list with no Write, Edit or Bash in it. That is the
+            # enforcement, not the prompt's own "you are reading only" — the same discipline as
+            # handler.py's containment check standing behind the test door's write boundary.
+            "--allowedTools", allowed_tools,
+            "--max-turns", str(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(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()` at the top of each door 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 {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 _image_registry() -> str:
+    registry = os.environ.get("IMAGE_REGISTRY")
+    if not registry:
+        raise EngineError(
+            "no IMAGE_REGISTRY set — cannot name the image the implementation actor published, "
+            "nor the test image this door would publish"
+        )
+    return registry.rstrip("/")
+
+
+def _rmtree(path: Path) -> None:
+    shutil.rmtree(path, ignore_errors=True)