okstra 0.186.7 → 0.187.0

package/runtime/python/okstra_ctl/domain/worker_stream.py

@@ -12,9 +12,10 @@ to be worth a default here — ``content_block_events``, whose events are keyed
 provider, and an adapter that speaks something else says so in its own file.
 
 Screen output folds what the log keeps in full — a tool call becomes one line, a
-tool result becomes an outcome and a size. Thinking is dropped at normalisation,
-which is safe only because worker liveness is measured from stream arrival
-rather than from log writes (see the spec's 7.2).
+tool result becomes an outcome, a size, and the first few rows of what came
+back. Thinking is dropped at normalisation, which is safe only because worker
+liveness is measured from stream arrival rather than from log writes (see the
+spec's 7.2).
 
 Three projections of the same stream: ``format_live`` for the pane,
 ``format_log`` for the archive, and ``final_text`` for the caller that must
@@ -31,6 +32,14 @@ from typing import Any, Callable, Mapping
 # previous one off the top of a short pane.
 _MAX_SUMMARY = 120
 
+# 화면이 받는 도구 결과 본문의 줄 수. 0 줄이던 동안 pane 에 남는 것은 성패와
+# 바이트 수뿐이었다. 어떤 어댑터가 본문 대신 도구 이름표를 넘겨 모든 호출이
+# 한 자릿수 바이트로 보이던 run 을, 화면만 보고는 아무도 판별하지 못했다.
+# 결과 하나가 pane 을 다 차지하면 직전 호출이 위로 밀려 나가므로 앞부분만
+# 보여주고, 나머지는 로그가 갖는다.
+_LIVE_BODY_ROWS = 4
+_BODY_INDENT = "    "
+
 
 @dataclass(frozen=True)
 class Text:
@@ -58,11 +67,20 @@ class ToolResult:
     ``failed`` is None when the stream closed the tool step without reporting an
     outcome at all. Reading that absence as success would put a confident "ok"
     next to a command that failed.
+
+    ``body_describes_result`` marks a tool that reported *about* its result
+    instead of returning it — a file read that answers ``54 lines, 4293 bytes``
+    rather than the 4293 bytes. Without the mark the two are the same shape and
+    the size reads as the payload, so a 4293-byte read is archived as
+    ``← done (20 bytes)`` and a reader concludes the read came back nearly
+    empty. The provider that emits such a report says so; this layer only
+    renders it differently.
     """
 
     body: str
     size_bytes: int
     failed: bool | None = None
+    body_describes_result: bool = False
 
 
 @dataclass(frozen=True)
@@ -112,17 +130,6 @@ def host_event_row(
     return row
 
 
-def no_events(event: Mapping[str, Any]) -> tuple[StreamEvent, ...]:
-    """The normaliser for a CLI that emits no events at all.
-
-    A text CLI's output is already what a person reads, so the runner forwards
-    it whole and never calls this. It exists so ``ExecCommand`` can default to
-    a truthful "there is nothing here to normalise" instead of to some
-    provider's schema.
-    """
-    return ()
-
-
 def content_block_events(event: Mapping[str, Any]) -> tuple[StreamEvent, ...]:
     """Normalise the stream shape keyed on ``type`` with ``message.content``.
 
@@ -157,7 +164,7 @@ def content_block_events(event: Mapping[str, Any]) -> tuple[StreamEvent, ...]:
 
 
 def format_live(event: StreamEvent) -> list[str]:
-    return _rows(event, limit=_MAX_SUMMARY, include_body=False)
+    return _rows(event, limit=_MAX_SUMMARY, body_rows=_LIVE_BODY_ROWS)
 
 
 def format_log(event: StreamEvent) -> list[str]:
@@ -167,7 +174,7 @@ def format_log(event: StreamEvent) -> list[str]:
     the fact, by a person reconstructing why a worker failed and by
     ``okstra log-report``.
     """
-    return _rows(event, limit=None, include_body=True)
+    return _rows(event, limit=None, body_rows=None)
 
 
 def final_text(event: StreamEvent) -> str | None:
@@ -175,17 +182,24 @@ def final_text(event: StreamEvent) -> str | None:
     return event.text if isinstance(event, Result) else None
 
 
-def _rows(event: StreamEvent, *, limit: int | None, include_body: bool) -> list[str]:
+def _rows(event: StreamEvent, *, limit: int | None, body_rows: int | None) -> list[str]:
     if isinstance(event, Text):
         return _body_rows(event.body)
     if isinstance(event, ToolCall):
         head = f"→ {event.name}: {event.detail}" if event.detail else f"→ {event.name}"
         return [_truncate(head, limit)]
     if isinstance(event, ToolResult):
-        rows = [f"  ← {_outcome(event.failed)} ({event.size_bytes} bytes)"]
-        if include_body:
-            rows.extend(_body_rows(event.body))
-        return rows
+        if event.body_describes_result:
+            # 크기를 싣지 않는다. 이 이벤트가 가진 숫자는 보고 문자열의 길이일
+            # 뿐이고(보고조차 없으면 0), 그것을 payload 자리에 놓는 것이 오독의
+            # 출처였다.
+            report = " ".join(event.body.split())
+            tail = (
+                f"the tool reported: {report}" if report else "the tool reported nothing"
+            )
+            return [_truncate(f"  ← {_outcome(event.failed)} — no body returned; {tail}", limit)]
+        head = f"  ← {_outcome(event.failed)} ({event.size_bytes} bytes)"
+        return [head, *_result_body(event.body, limit=limit, keep=body_rows)]
     if isinstance(event, Denial):
         return [_truncate(f"!! PERMISSION DENIED — {event.tool}: {event.reason}", limit)]
     # A Result is printed by the runner at the point the run ends, not woven
@@ -193,6 +207,23 @@ def _rows(event: StreamEvent, *, limit: int | None, include_body: bool) -> list[
     return []
 
 
+def _result_body(body: str, *, limit: int | None, keep: int | None) -> list[str]:
+    """결과 본문을 몇 줄 보여줄지 정한다.
+
+    `keep is None` 이 기록의 몫이다 — 전부 남긴다. 화면은 앞 몇 줄만 받고,
+    생략한 줄 수를 밝힌다. 밝히지 않으면 짧은 출력과 잘린 출력이 같은 모양이
+    되어, 읽는 사람이 로그를 열 이유를 알 수 없다.
+    """
+    rows = _body_rows(body)
+    if keep is None:
+        return rows
+    shown = [_truncate(_BODY_INDENT + row, limit) for row in rows[:keep]]
+    dropped = len(rows) - keep
+    if dropped > 0:
+        shown.append(f"{_BODY_INDENT}… +{dropped} more line(s) — full body in the log")
+    return shown
+
+
 def _outcome(failed: bool | None) -> str:
     if failed is None:
         return "done"

package/runtime/python/okstra_ctl/domain/write_policy.py

@@ -0,0 +1,219 @@
+"""쓰기 정책 값 타입 · 직렬화 · 검증.
+
+`..write_policy`(623줄) 안에 있던 값 코어를 도메인으로 내렸다. 그 모듈은
+git 을 실행하고 run manifest 를 읽는 응용 로직인데, `domain/worker_exec.py` 가
+`WritePolicy` / `WriteEnforcement` 타입 하나 때문에 그 응용 모듈을 최상위
+import 하고 있었다 — 도메인이 응용을 부르는 역전이고, 그 탓에
+`write_policy → path_hints` 가 함수 본문 지연 import 로 밀려나 있었다.
+
+값과 그 값의 정합성(직렬화·다이제스트·payload 검증)까지가 여기다.
+정책을 **만들거나**(build_*) **유도하는**(derive_*) 일은 응용에 남는다.
+`..write_policy` 가 이 이름들을 재노출하므로 기존 호출부는 바뀌지 않는다.
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass
+from pathlib import Path, PurePosixPath
+from typing import Any, Literal
+
+
+BoundaryPrecision = Literal["exact-path", "directory-boundary", "none"]
+
+_PRECISION_RANK = {"none": 0, "directory-boundary": 1, "exact-path": 2}
+
+_POLICY_KEYS = {
+    "artifactPolicy",
+    "sourcePolicy",
+    "gitPolicy",
+    "auxiliaryPolicy",
+}
+
+_ENFORCEMENT_KEYS = {
+    "boundaryPrecision",
+    "mutationAudit",
+    "attribution",
+    "auditedRoots",
+    "observationCoverage",
+    "unobservedWriteSurfaces",
+}
+
+class WritePolicyError(ValueError):
+    """Raised when a write policy cannot be made canonical or trustworthy."""
+
+@dataclass(frozen=True)
+class WritePolicy:
+    artifact_policy: Mapping[str, Any]
+    source_policy: Mapping[str, Any]
+    git_policy: Mapping[str, Any]
+    auxiliary_policy: Mapping[str, Any]
+    maximum_boundary_precision: BoundaryPrecision = "none"
+
+    def to_payload(self) -> dict[str, Any]:
+        return {
+            "artifactPolicy": dict(self.artifact_policy),
+            "sourcePolicy": dict(self.source_policy),
+            "gitPolicy": dict(self.git_policy),
+            "auxiliaryPolicy": dict(self.auxiliary_policy),
+        }
+
+    @property
+    def digest(self) -> str:
+        return write_policy_digest(self.to_payload())
+
+    @property
+    def source_mode(self) -> str:
+        return str(self.source_policy["mode"])
+
+@dataclass(frozen=True)
+class WriteEnforcement:
+    boundary_precision: BoundaryPrecision
+    mutation_audit: Literal["none", "batch"]
+    attribution: Literal["call", "batch-unattributed"]
+    audited_roots: tuple[Path, ...]
+    observation_coverage: Literal["complete", "scoped", "partial"]
+    unobserved_write_surfaces: tuple[str, ...]
+
+    def to_payload(self) -> dict[str, Any]:
+        return {
+            "boundaryPrecision": self.boundary_precision,
+            "mutationAudit": self.mutation_audit,
+            "attribution": self.attribution,
+            "auditedRoots": [str(path) for path in self.audited_roots],
+            "observationCoverage": self.observation_coverage,
+            "unobservedWriteSurfaces": list(self.unobserved_write_surfaces),
+        }
+
+def write_policy_from_payload(payload: Mapping[str, Any]) -> WritePolicy:
+    validate_write_policy_payload(payload)
+    return WritePolicy(
+        artifact_policy=dict(payload["artifactPolicy"]),
+        source_policy=dict(payload["sourcePolicy"]),
+        git_policy=dict(payload["gitPolicy"]),
+        auxiliary_policy=dict(payload["auxiliaryPolicy"]),
+    )
+
+def write_enforcement_from_payload(
+    payload: Mapping[str, Any],
+) -> WriteEnforcement:
+    validate_write_enforcement_payload(payload)
+    return WriteEnforcement(
+        boundary_precision=payload["boundaryPrecision"],
+        mutation_audit=payload["mutationAudit"],
+        attribution=payload["attribution"],
+        audited_roots=tuple(Path(value) for value in payload["auditedRoots"]),
+        observation_coverage=payload["observationCoverage"],
+        unobserved_write_surfaces=tuple(payload["unobservedWriteSurfaces"]),
+    )
+
+def write_policy_digest(payload: Mapping[str, Any]) -> str:
+    validate_write_policy_payload(payload)
+    encoded = json.dumps(
+        payload,
+        sort_keys=True,
+        separators=(",", ":"),
+        ensure_ascii=False,
+    ).encode("utf-8")
+    return "sha256:" + hashlib.sha256(encoded).hexdigest()
+
+def validate_write_policy_payload(payload: Mapping[str, Any]) -> None:
+    if set(payload) != _POLICY_KEYS:
+        raise WritePolicyError("writePolicy must contain four canonical policy sections")
+    artifact = _mapping(payload.get("artifactPolicy"), "artifactPolicy")
+    source = _mapping(payload.get("sourcePolicy"), "sourcePolicy")
+    git = _mapping(payload.get("gitPolicy"), "gitPolicy")
+    auxiliary = _mapping(payload.get("auxiliaryPolicy"), "auxiliaryPolicy")
+    if set(artifact) != {"allowedRoot", "allowedPaths"}:
+        raise WritePolicyError("artifactPolicy is incomplete")
+    _absolute_text(artifact.get("allowedRoot"), "artifactPolicy.allowedRoot")
+    _relative_paths(artifact.get("allowedPaths", ()))
+    if source.get("mode") not in {"source-readonly", "project-mutation"}:
+        raise WritePolicyError("sourcePolicy mode is invalid")
+    if set(source) != {"mode", "allowedRoot", "plannedPaths", "protectedPaths"}:
+        raise WritePolicyError("sourcePolicy is incomplete")
+    _absolute_text(source.get("allowedRoot"), "sourcePolicy.allowedRoot")
+    _relative_paths(source.get("plannedPaths", ()))
+    _relative_paths(source.get("protectedPaths", ()))
+    if git.get("mode") not in {"disabled", "fast-forward-descendant-chain"}:
+        raise WritePolicyError("gitPolicy mode is invalid")
+    if git.get("mode") == "disabled" and set(git) != {"mode"}:
+        raise WritePolicyError("disabled gitPolicy must not grant Git paths")
+    required_git = {
+        "mode", "worktreeGitDir", "gitCommonDir", "expectedBaseCommit",
+        "allowedBranchRef", "commitMode",
+    }
+    if git.get("mode") != "disabled" and set(git) != required_git:
+        raise WritePolicyError("project mutation gitPolicy is incomplete")
+    if set(auxiliary) != {"scratchRoots", "generatedPaths", "externalRoots"}:
+        raise WritePolicyError("auxiliaryPolicy is incomplete")
+    _relative_paths(auxiliary.get("generatedPaths", ()))
+    for key in ("scratchRoots", "externalRoots"):
+        for value in _text_sequence(auxiliary.get(key), f"auxiliaryPolicy.{key}"):
+            _absolute_text(value, f"auxiliaryPolicy.{key}")
+
+def validate_write_enforcement_payload(payload: Mapping[str, Any]) -> None:
+    if set(payload) != _ENFORCEMENT_KEYS:
+        raise WritePolicyError("writeEnforcement is incomplete")
+    boundary = payload.get("boundaryPrecision")
+    mutation_audit = payload.get("mutationAudit")
+    attribution = payload.get("attribution")
+    coverage = payload.get("observationCoverage")
+    if boundary not in _PRECISION_RANK:
+        raise WritePolicyError("writeEnforcement boundaryPrecision is invalid")
+    if mutation_audit not in {"none", "batch"}:
+        raise WritePolicyError("writeEnforcement mutationAudit is invalid")
+    if attribution not in {"call", "batch-unattributed"}:
+        raise WritePolicyError("writeEnforcement attribution is invalid")
+    if coverage not in {"complete", "scoped", "partial"}:
+        raise WritePolicyError("writeEnforcement observationCoverage is invalid")
+    if (boundary, mutation_audit, attribution) == ("exact-path", "none", "call"):
+        if coverage != "complete":
+            raise WritePolicyError("exact enforcement must have complete coverage")
+    elif (boundary, mutation_audit, attribution) == (
+        "none",
+        "none",
+        "batch-unattributed",
+    ):
+        if coverage != "partial":
+            raise WritePolicyError("host-session enforcement must be partial")
+    elif mutation_audit != "batch" or attribution != "batch-unattributed":
+        raise WritePolicyError("non-exact enforcement must use batch attribution")
+    elif boundary == "exact-path" or coverage == "complete":
+        raise WritePolicyError("batch enforcement cannot claim exact coverage")
+    for root in _text_sequence(payload.get("auditedRoots"), "auditedRoots"):
+        _absolute_text(root, "auditedRoots")
+    _text_sequence(payload.get("unobservedWriteSurfaces"), "unobservedWriteSurfaces")
+
+def _relative_paths(value: object) -> tuple[str, ...]:
+    paths: list[str] = []
+    for raw in _text_sequence(value, "relative paths"):
+        candidate = PurePosixPath(raw)
+        if candidate.is_absolute() or not candidate.parts or ".." in candidate.parts:
+            raise WritePolicyError("policy paths must be normalized relative paths")
+        normalized = candidate.as_posix()
+        if normalized in {"", "."} or normalized != raw:
+            raise WritePolicyError("policy paths must be normalized relative paths")
+        paths.append(normalized)
+    if len(set(paths)) != len(paths):
+        raise WritePolicyError("policy paths must be unique")
+    return tuple(paths)
+
+def _mapping(value: object, label: str) -> Mapping[str, Any]:
+    if not isinstance(value, Mapping):
+        raise WritePolicyError(f"{label} must be an object")
+    return value
+
+def _text_sequence(value: object, label: str) -> tuple[str, ...]:
+    if not isinstance(value, Sequence) or isinstance(value, (str, bytes)):
+        raise WritePolicyError(f"{label} must be an array")
+    rows = tuple(value)
+    if any(not isinstance(row, str) or not row for row in rows):
+        raise WritePolicyError(f"{label} must contain non-empty strings")
+    return rows
+
+def _absolute_text(value: object, label: str) -> str:
+    if not isinstance(value, str) or not value or not Path(value).is_absolute():
+        raise WritePolicyError(f"{label} must be an absolute path")
+    return value

package/runtime/python/okstra_ctl/entrypoints/hosts.py

@@ -9,7 +9,7 @@ from contextlib import contextmanager
 from dataclasses import asdict
 from pathlib import Path
 
-from ..agent_invocation import (
+from ..agent.invocation import (
     AgentInvocationError,
     AgentModelAssignment,
     agent_model_assignment_from_payload,
@@ -113,7 +113,7 @@ def _build_parser() -> argparse.ArgumentParser:
     resolve.add_argument(
         "--capability",
         action="append",
-        choices=("claude-skill-handoff", "tmux"),
+        choices=("claude-skill-handoff",),
         default=[],
     )
     launch = commands.add_parser("launch-plan")
@@ -200,9 +200,16 @@ def _probe_payload(
     status = "unknown" if "unavailable" in statuses else (
         "ready" if readiness.ok else "blocked"
     )
+    # A check may report that this session cannot host the lead while the run
+    # itself is fine. The caller needs the mode it must actually launch in, not
+    # the mode it asked about, so the probe answers with the resolved one.
+    entry_mode = (
+        "spawn-process" if "lead-must-spawn" in statuses else args.entry_mode
+    )
     return {
         "runtime": adapter.descriptor.id,
         "status": status,
+        "entryMode": entry_mode,
         "checks": list(readiness.checks),
         "relayContract": adapter.descriptor.relay_contract,
     }

package/runtime/python/okstra_ctl/error_log_core.py

@@ -37,7 +37,7 @@ def parse_records(paths: list[Path]) -> tuple[list[dict], int]:
                 continue
             try:
                 rec = json.loads(line)
-            except Exception:
+            except (ValueError, TypeError):
                 skipped += 1
                 continue
             if isinstance(rec, dict):

package/runtime/python/okstra_ctl/error_report.py

@@ -210,8 +210,22 @@ def render_result_text(result: dict) -> str:
     return "".join(parts)
 
 
+_CLI_EPILOG = r"""Usage:
+  okstra error-report <task-root>
+  okstra error-report <task-key> --project-root <dir>
+  okstra error-report <task-key> --cwd <dir>
+
+Writes a timestamped markdown report under <task-root>/error-reports/ and
+prints a JSON summary (counts by errorType / source / phase / agent) to stdout.
+This is read-only against task state; it never mutates task artifacts.
+"""
+
+
 def main(argv: list[str] | None = None) -> int:
     parser = argparse.ArgumentParser(
+        prog="okstra error-report",
+        epilog=_CLI_EPILOG,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
         description="Aggregate okstra-run error logs into a task-level report."
     )
     parser.add_argument("target", help="task root path or task-key")

package/runtime/python/okstra_ctl/error_zip.py

@@ -19,7 +19,11 @@ from okstra_ctl.error_log_core import aggregate, parse_records
 from okstra_ctl.jsonl import read_jsonl
 from okstra_ctl.locks import central_lock
 from okstra_ctl.paths import okstra_home, resolve_under_root
-from okstra_ctl.json_boundary import load_owned_object, write_owned_object_atomic
+from okstra_ctl.json_boundary import (
+    JsonBoundaryError,
+    load_owned_object,
+    write_owned_object_atomic,
+)
 
 
 def run_dirs(home: Path) -> list[tuple[str, Path, dict]]:
@@ -282,7 +286,7 @@ def last_output_path(home: Path) -> str:
                 "lastOutputPath", ""
             )
         )
-    except Exception:
+    except JsonBoundaryError:
         return ""
 
 
@@ -335,8 +339,20 @@ def render_result_text(result: dict) -> str:
     return "".join(lines)
 
 
+_CLI_EPILOG = r"""Usage:
+  okstra error-zip --out <path>
+
+Walks the global run-index (~/.okstra/recent.jsonl + active.jsonl), collects
+every target project's runs/*/logs/errors-*.jsonl, anonymizes records, and
+writes a .zip (report.md + errors/anonymized.jsonl) to <path>. Read-only
+against every target's .okstra/. Prints a JSON summary to stdout.
+"""
+
+
 def main(argv: list[str] | None = None) -> int:
     parser = argparse.ArgumentParser(
+        epilog=_CLI_EPILOG,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
         prog="okstra error-zip",
         description="cross-project okstra 에러를 수집·익명화해 zip 으로 묶는다.",
     )

package/runtime/python/okstra_ctl/execution_identity.py

@@ -6,7 +6,7 @@ import json
 from collections.abc import Mapping
 from dataclasses import dataclass, field
 from pathlib import Path
-from typing import Any
+from typing import Any, Literal
 
 from .domain.provider import HostModelBinding, ServedModelAttestation
 from .domain.worker_exec import WorkerWriteCapability
@@ -116,9 +116,6 @@ class Invocation:
     dispatch_kind: str
     round: int
     input_digest: str
-    write_policy: Mapping[str, Any]
-    write_policy_digest: str
-    write_enforcement: Mapping[str, Any]
 
     def to_payload(self) -> dict[str, Any]:
         return {
@@ -131,14 +128,19 @@ class Invocation:
             "dispatchKind": self.dispatch_kind,
             "round": self.round,
             "inputDigest": self.input_digest,
-            "writePolicy": dict(self.write_policy),
-            "writePolicyDigest": self.write_policy_digest,
-            "writeEnforcement": dict(self.write_enforcement),
         }
 
 
 @dataclass(frozen=True)
 class Attempt:
+    """One dispatch of a logical invocation, with the write contract it ran under.
+
+    쓰기 계약이 invocation 이 아니라 여기 있는 이유: 계약의 artifactPolicy 는 그
+    시도가 실제로 쓰는 프롬프트 파생 파일(`...-attempt-2.log` 등)을 이름으로
+    담는다. attempt 마다 다른 값이므로 attempt-불변인 invocation 행에 두면 같은
+    invocationRef 의 2회차가 `invocationRef drift` 로 거절된다.
+    """
+
     invocation_ref: str
     attempt: int
     started_at: str
@@ -148,6 +150,9 @@ class Attempt:
     error_path: str | None
     change_summary: Mapping[str, Any]
     evidence_seal_ref: str | None
+    write_policy: Mapping[str, Any]
+    write_policy_digest: str
+    write_enforcement: Mapping[str, Any]
 
     def to_payload(self) -> dict[str, Any]:
         return {
@@ -160,6 +165,9 @@ class Attempt:
             "errorPath": self.error_path,
             "changeSummary": dict(self.change_summary),
             "evidenceSealRef": self.evidence_seal_ref,
+            "writePolicy": dict(self.write_policy),
+            "writePolicyDigest": self.write_policy_digest,
+            "writeEnforcement": dict(self.write_enforcement),
         }
 
 
@@ -528,3 +536,88 @@ def _required_index_text(
 def _optional_text(value: object) -> str | None:
     text = str(value or "").strip()
     return text or None
+
+
+# ---- 무거운 모듈에서 옮겨 온 값 타입 ------------------------------------
+# 아래 둘은 dispatch_state(2,092줄) 와 mutation_recovery 안에 있었다. 값 하나가
+# 필요한 모듈이 그 모듈 전체를 끌어오게 되어, 반대 방향은 함수 본문 지연
+# import 로 밀려나 순환이 됐다. 원래 소유 모듈이 이름을 재노출한다.
+
+def build_dispatch_id(invocation_id: str, attempt: int) -> str:
+    """The only place Python assembles a dispatch id.
+
+    Two generators drifted: this module pinned the attempt to 1 while
+    `dispatch_core` used the real one, so a re-dispatch took the first attempt's
+    id, team-state kept the same row twice, and `validate-run` failed that run
+    with `agent dispatch ID is duplicated`.
+
+    Prose mirrors of this shape live outside Python, where no guard reaches
+    them: `prompts/lead/convergence.md`, `prompts/lead/report-writer.md`,
+    `prompts/lead/plan-body-verification.md` and the five
+    `adapters/hosts/*/relay.md` each spell an `--dispatch-id` argument out for
+    the lead. They agree with this function only because
+    `record_verified_agent_dispatch` records the first attempt and no other;
+    changing that convention has to change them too.
+    """
+    return f"{invocation_id}:attempt-{attempt}"
+
+
+@dataclass(frozen=True)
+class MutationRecoveryDecision:
+    recovery_ref: str
+    source_invocation_ref: str
+    source_attempt_ref: str
+    source_evidence_seal_ref: str | None
+    original_baseline_digest: str
+    terminal_source_diff_digest: str
+    terminal_git_chain_digest: str
+    verifier_role_execution_ref: str | None
+    verifier_invocation_ref: str | None
+    recovered_evidence_refs: tuple[Mapping[str, Any], ...]
+    recovered_out_of_plan_edits: tuple[Mapping[str, Any], ...]
+    unmet_obligations: tuple[str, ...]
+    decision: Literal["carry-forward", "reject", "cleanup-confirmed"]
+    reason: str = ""
+
+    def to_payload(self) -> dict[str, Any]:
+        return {
+            "recoveryRef": self.recovery_ref,
+            "sourceInvocationRef": self.source_invocation_ref,
+            "sourceAttemptRef": self.source_attempt_ref,
+            "sourceEvidenceSealRef": self.source_evidence_seal_ref,
+            "originalBaselineDigest": self.original_baseline_digest,
+            "terminalSourceDiffDigest": self.terminal_source_diff_digest,
+            "terminalGitChainDigest": self.terminal_git_chain_digest,
+            "verifierRoleExecutionRef": self.verifier_role_execution_ref,
+            "verifierInvocationRef": self.verifier_invocation_ref,
+            "recoveredEvidenceRefs": [dict(row) for row in self.recovered_evidence_refs],
+            "recoveredOutOfPlanEdits": [
+                dict(row) for row in self.recovered_out_of_plan_edits
+            ],
+            "unmetObligations": list(self.unmet_obligations),
+            "decision": self.decision,
+            "reason": self.reason,
+        }
+
+    @classmethod
+    def from_payload(cls, payload: Mapping[str, Any]) -> "MutationRecoveryDecision":
+        return cls(
+            recovery_ref=str(payload["recoveryRef"]),
+            source_invocation_ref=str(payload["sourceInvocationRef"]),
+            source_attempt_ref=str(payload["sourceAttemptRef"]),
+            source_evidence_seal_ref=payload.get("sourceEvidenceSealRef"),
+            original_baseline_digest=str(payload.get("originalBaselineDigest") or ""),
+            terminal_source_diff_digest=str(
+                payload.get("terminalSourceDiffDigest") or ""
+            ),
+            terminal_git_chain_digest=str(payload.get("terminalGitChainDigest") or ""),
+            verifier_role_execution_ref=payload.get("verifierRoleExecutionRef"),
+            verifier_invocation_ref=payload.get("verifierInvocationRef"),
+            recovered_evidence_refs=tuple(payload.get("recoveredEvidenceRefs") or ()),
+            recovered_out_of_plan_edits=tuple(
+                payload.get("recoveredOutOfPlanEdits") or ()
+            ),
+            unmet_obligations=tuple(payload.get("unmetObligations") or ()),
+            decision=str(payload["decision"]),
+            reason=str(payload.get("reason") or ""),
+        )