okstra 0.178.0 → 0.179.1

package/runtime/python/okstra_ctl/convergence_store.py

@@ -87,8 +87,19 @@ def reserve_dynamic_verifier(
     input_digest: str,
     invocation_ref: str | None = None,
     artifact_paths: tuple[Path, ...],
+    worktree: Path | None = None,
 ) -> tuple[RoleExecution, Invocation]:
-    """Reserve one provider-neutral verifier identity for a logical round."""
+    """Reserve one provider-neutral verifier identity for a logical round.
+
+    `worktree` 는 이 런의 워커가 실제로 서는 루트다. 디스패치가 정책을 다시
+    계산할 때 쓰는 값(`dispatch_core._canonical_write_contract` 이 job 의
+    worktree 를 넘긴다)과 같아야 한다. 여기서 None 으로 고정하면 예약된 정책의
+    `sourcePolicy.allowedRoot` 는 프로젝트 루트, 디스패치가 계산한 정책은 스테이지
+    워크트리가 되어 writePolicyDigest 가 갈리고, 같은 invocationRef 가
+    `invocationRef drift` 로 거부된다 — 워크트리를 쓰는 런(implementation stage)
+    에서만 나타나고 워크트리가 없는 런(implementation-planning)에서는 안 나타나
+    버전 문제로 보이기 쉽다.
+    """
     if round_number < 1:
         raise ExecutionManifestError("dynamic verifier round must be positive")
     manifest_path = Path(manifest_path).resolve()
@@ -128,7 +139,7 @@ def reserve_dynamic_verifier(
             policy, enforcement = build_invocation_write_contract(
                 role="verifier",
                 project_root=project_root,
-                worktree=None,
+                worktree=worktree,
                 artifact_paths=artifact_paths,
                 maximum_precision=capability.max_boundary_precision,
                 auxiliary_roots=verifier_extra_dirs("verifier"),

package/runtime/python/okstra_ctl/dispatch_core.py

@@ -2,6 +2,7 @@
 from __future__ import annotations
 
 import json
+import re
 import subprocess
 import time
 from dataclasses import dataclass, field, replace
@@ -110,6 +111,8 @@ from .worker_prompt_headers import (
 from .worker_artifact_paths import audit_sidecar_rel
 from .wrapper_status import (
     log_path_for_prompt,
+    mutation_snapshot_path_for_prompt,
+    prompt_derived_paths,
     read_wrapper_status,
     status_path_for_prompt,
 )
@@ -356,7 +359,9 @@ def build_dispatch_plan(
         default_provider_by_worker_id=dict(default_provider_by_worker_id or {}),
     )
     if jobs_file:
-        jobs = _jobs_from_file(project_root, workspace_root, jobs_file, manifest, options)
+        jobs = _jobs_from_file(
+            project_root, workspace_root, jobs_file, manifest, active_context, options
+        )
     else:
         jobs = _jobs_from_roster(
             project_root,
@@ -413,7 +418,10 @@ def dispatch_plan(plan: DispatchPlan, *, wait: bool = True) -> int:
         return 0
     round_artifact_paths = _round_artifact_paths(plan)
     handles = [
-        _spawn_job(plan, job, 1, batch_artifact_paths=round_artifact_paths)
+        _spawn_job(
+            plan, job, _next_attempt(plan, job),
+            batch_artifact_paths=round_artifact_paths,
+        )
         for job in plan.jobs
     ]
     _record_dispatch_facts(plan.team_state_path, _mode_from_handles(handles))
@@ -1289,6 +1297,7 @@ def _jobs_from_file(
     workspace_root: Path,
     jobs_file: Path | None,
     manifest: Mapping[str, Any],
+    active_context: Mapping[str, Any],
     options: _BuildOptions,
 ) -> list[WorkerJob]:
     if jobs_file is None:
@@ -1297,6 +1306,7 @@ def _jobs_from_file(
         project_root,
         jobs_file,
         manifest=manifest,
+        active_context=active_context,
         backend=options.default_backend,
         idle_timeout_seconds=options.idle_timeout_seconds,
         default_dispatch_kind=options.dispatch_kind,
@@ -1387,6 +1397,34 @@ def _spawn_cli_job_nonblocking(
     )
 
 
+def _next_attempt(plan: DispatchPlan, job: WorkerJob) -> int:
+    """이 invocation 이 다음에 청구할 attempt 번호.
+
+    attempt 를 1 로 고정하면 같은 워커를 두 번째로 디스패치할 수 없다. 원장은
+    단조 증가를 요구하므로(`execution_manifest._validate_next_attempt`) 두 번째
+    호출이 항상 `next attempt must be 2` 로 거부되고, 재시도 예산이 계약에는
+    있는데 그 경로에는 쓸 수단이 없는 상태가 된다. 예산은 프로세스가 아니라
+    invocation 에 붙어 있고, 그 잔액이 적힌 곳은 원장뿐이다.
+    """
+    if not job.has_execution_identity:
+        return job.attempt
+    manifest = read_execution_manifest(plan.manifest_path)
+    prior = [
+        row.attempt for row in manifest.attempts
+        if row.invocation_ref == job.invocation_ref
+    ]
+    if not prior:
+        return job.attempt
+    spent = max(prior)
+    if spent >= MAX_WORKER_ATTEMPTS:
+        raise DispatchError(
+            f"worker retry budget is spent: {job.invocation_ref} used "
+            f"{spent} of {MAX_WORKER_ATTEMPTS} attempts. Materialize a new "
+            "invocation to dispatch this worker again."
+        )
+    return spent + 1
+
+
 def _prepare_job_attempt(
     plan: DispatchPlan, job: WorkerJob, attempt: int
 ) -> WorkerJob:
@@ -1462,7 +1500,7 @@ def _mutation_snapshot(
 
 
 def _mutation_snapshot_path(job: WorkerJob) -> Path:
-    return job.prompt_path.with_suffix(job.prompt_path.suffix + ".mutation-audit.json")
+    return mutation_snapshot_path_for_prompt(job.prompt_path)
 
 
 def _record_execution_attempt(plan: DispatchPlan, job: WorkerJob) -> None:
@@ -1517,6 +1555,11 @@ def _canonical_write_contract(
         raise DispatchError("worker write policy has no runner write capability")
     artifacts = _worker_artifact_paths(plan, job)
     worktree = Path(job.worktree_path) if job.worktree_path else None
+    planned = (
+        planned_paths_from_run_manifest(plan.project_root, plan.manifest)
+        if execution.role == "implementer"
+        else ((), True)
+    )
     try:
         return build_invocation_write_contract(
             role=execution.role,
@@ -1524,11 +1567,8 @@ def _canonical_write_contract(
             worktree=worktree,
             artifact_paths=artifacts,
             maximum_precision=capability.max_boundary_precision,
-            planned_paths=(
-                planned_paths_from_run_manifest(plan.project_root, plan.manifest)
-                if execution.role == "implementer"
-                else ()
-            ),
+            planned_paths=planned[0],
+            planned_paths_declared=planned[1],
             auxiliary_roots=verifier_extra_dirs(execution.role),
             validated_auxiliary_roots=verifier_extra_dirs(execution.role),
         )
@@ -1545,14 +1585,12 @@ def _worker_artifact_paths(plan: DispatchPlan, job: WorkerJob) -> tuple[Path, ..
         job.worker_result_path,
         *job.completion_paths,
         Path(audit_sidecar_rel(str(job.worker_result_path))),
-        status_path_for_prompt(job.prompt_path),
-        log_path_for_prompt(job.prompt_path),
         # The prompt's three derived files are written together and belong in
         # one list. The audit snapshot used to be listed only for the job whose
         # snapshot it was, so a sibling's snapshot — written by okstra as that
         # sibling started — landed inside this worker's window as an
         # unauthorized artifact-root change.
-        _mutation_snapshot_path(job),
+        *prompt_derived_paths(job.prompt_path),
     }
     error_logs = active_context.get("errorLogs")
     if isinstance(error_logs, Mapping):
@@ -1619,7 +1657,7 @@ def _dispatch_round(dispatch_kind: str) -> int:
 
 
 def _dispatch_job_with_retry(plan: DispatchPlan, job: WorkerJob) -> int:
-    for attempt in range(1, MAX_WORKER_ATTEMPTS + 1):
+    for attempt in range(_next_attempt(plan, job), MAX_WORKER_ATTEMPTS + 1):
         handle = _spawn_job(plan, job, attempt)
         if handle.completed_process is None:
             return await_dispatches(plan, timeout_seconds=None)
@@ -1914,8 +1952,41 @@ def _audit_attempt(
     )
 
 
+def _declared_out_of_plan_paths(result_path: Path) -> tuple[str, ...]:
+    """워커가 자기 결과의 `Out-of-plan edits` 블록에 선언한 경로.
+
+    감사는 워커가 끝나는 시점에 돈다. 그때 디스크에 있는 것은 워커 결과
+    마크다운뿐이고, `implementation.outOfPlanEdits` 는 리드가 나중에 쓰는 최종
+    리포트의 필드다. JSON 형태만 읽었기 때문에 executor 의 선언이 한 번도 보이지
+    않았고, 계약대로 선언한 편집까지 미허가 변경으로 집계됐다. 블록의 형태는 이
+    판독기를 위해 `_implementation-executor.md` 가 고정한다 — `- ` 줄마다 첫 백틱
+    토큰이 경로다.
+    """
+    if not result_path.is_file() or result_path.suffix != ".md":
+        return ()
+    try:
+        text = result_path.read_text(encoding="utf-8")
+    except (OSError, UnicodeError):
+        return ()
+    paths: list[str] = []
+    inside = False
+    for line in text.splitlines():
+        stripped = line.strip()
+        if stripped.startswith("#"):
+            inside = stripped.lstrip("#").strip().lower() == "out-of-plan edits"
+            continue
+        if not inside or not stripped.startswith("- "):
+            continue
+        quoted = re.findall(r"`([^`\n]+)`", stripped)
+        if quoted and quoted[0].strip():
+            paths.append(quoted[0].strip())
+    return tuple(paths)
+
+
 def _out_of_plan_edit_paths(result_path: Path) -> tuple[str, ...]:
-    if not result_path.is_file() or result_path.suffix != ".json":
+    if result_path.suffix != ".json":
+        return _declared_out_of_plan_paths(result_path)
+    if not result_path.is_file():
         return ()
     try:
         payload = json.loads(result_path.read_text(encoding="utf-8"))
@@ -2917,7 +2988,7 @@ def _reject_stale_schema_excerpt(
     )
     if writer is None:
         return
-    expected = _string_value(manifest.get("expectedReportPath"))
+    expected = _string_value(manifest.get("expectedReportRecordPath"))
     if not expected:
         return
     excerpt_path = bundle_excerpt_path(_resolve_project_path(project_root, expected))

package/runtime/python/okstra_ctl/dispatch_state.py

@@ -46,10 +46,7 @@ from .execution_manifest import (
     record_invocation_attempt,
 )
 from .execution_mutation_audit import ExecutionMutationAudit, MutationSnapshot
-from .final_report_paths import (
-    final_report_data_path,
-    final_report_markdown_path,
-)
+from .final_report_paths import final_report_data_path
 from .worker_prompt_body import REPORT_WRITER_WORKER_ID
 from .worker_prompt_contract import (
     PromptRecord,
@@ -59,7 +56,11 @@ from .worker_prompt_contract import (
 from .worker_runner import LIVE, QUIET
 from .worker_request import verifier_extra_dirs
 from .worker_artifact_paths import audit_sidecar_rel
-from .wrapper_status import log_path_for_prompt, status_path_for_prompt
+from .wrapper_status import (
+    log_path_for_prompt,
+    prompt_derived_paths,
+    status_path_for_prompt,
+)
 from .write_policy import (
     build_invocation_write_contract,
     planned_paths_from_run_manifest,
@@ -812,6 +813,11 @@ def _agent_write_contract(
         maximum_precision = capability.max_boundary_precision
     else:
         raise DispatchError("agent write policy has no runner capability")
+    planned = (
+        planned_paths_from_run_manifest(project_root, authority)
+        if execution.role == "implementer"
+        else ((), True)
+    )
     try:
         return build_invocation_write_contract(
             role=execution.role,
@@ -819,11 +825,8 @@ def _agent_write_contract(
             worktree=worktree,
             artifact_paths=artifacts,
             maximum_precision=maximum_precision,
-            planned_paths=(
-                planned_paths_from_run_manifest(project_root, authority)
-                if execution.role == "implementer"
-                else ()
-            ),
+            planned_paths=planned[0],
+            planned_paths_declared=planned[1],
             auxiliary_roots=verifier_extra_dirs(execution.role),
             validated_auxiliary_roots=verifier_extra_dirs(execution.role),
         )
@@ -927,8 +930,7 @@ def _prompt_write_paths(
     artifacts = {
         _project_or_absolute(project_root, value) for value in artifact_values
     }
-    artifacts.add(status_path_for_prompt(prompt_path))
-    artifacts.add(log_path_for_prompt(prompt_path))
+    artifacts.update(prompt_derived_paths(prompt_path))
     worktree_value = values.get("Worktree")
     worktree = (
         _project_or_absolute(project_root, worktree_value)
@@ -1467,7 +1469,7 @@ def dispatch_result_path(
     if worker_id != REPORT_WRITER_WORKER_ID:
         return worker_result_path
     return final_report_data_path(
-        resolve_required_path(project_root, manifest, "expectedReportPath")
+        resolve_required_path(project_root, manifest, "expectedReportRecordPath")
     )
 
 
@@ -1479,17 +1481,16 @@ def dispatch_completion_paths(
 ) -> tuple[Path, ...]:
     """Every artifact that must exist before this worker counts as done.
 
-    The report writer's three are the data.json, its rendered Markdown sibling,
-    and the worker-result pointer (`prompts/lead/report-writer.md` §"Completion
-    detection"). Same reason as `dispatch_result_path`: both constructors need
-    the same answer.
+    The report writer's two are the report record and the worker-result
+    pointer. The full reading copy is rendered on demand and is not a
+    completion artifact.
     """
     if worker_id != REPORT_WRITER_WORKER_ID:
         return (worker_result_path,)
     data_json = final_report_data_path(
-        resolve_required_path(project_root, manifest, "expectedReportPath")
+        resolve_required_path(project_root, manifest, "expectedReportRecordPath")
     )
-    return (data_json, final_report_markdown_path(data_json), worker_result_path)
+    return (data_json, worker_result_path)
 
 
 def validate_initial_prompts(
@@ -1762,6 +1763,7 @@ def worker_jobs_from_file(
     jobs_file: Path,
     *,
     manifest: Mapping[str, Any],
+    active_context: Mapping[str, Any] | None = None,
     backend: str,
     idle_timeout_seconds: int,
     default_dispatch_kind: str,
@@ -1781,6 +1783,7 @@ def worker_jobs_from_file(
             project_root,
             item,
             manifest=manifest,
+            active_context=active_context,
             backend=backend,
             idle_timeout_seconds=idle_timeout_seconds,
             dispatch_kind=dispatch_kind,
@@ -1799,6 +1802,7 @@ def _worker_job_from_file(
     item: Mapping[str, Any],
     *,
     manifest: Mapping[str, Any],
+    active_context: Mapping[str, Any] | None = None,
     backend: str,
     idle_timeout_seconds: int,
     dispatch_kind: str,
@@ -1849,7 +1853,17 @@ def _worker_job_from_file(
         result_path=result_path,
         worker_result_path=worker_result_path,
         completion_paths=completion_paths,
-        worktree_path=string_value(item.get("worktreePath")),
+        # 파일이 적지 않았으면 run authority 에서 해소한다. 로스터 경로는
+        # 언제나 그렇게 하고(`dispatch_core._jobs_from_roster`), 예약 쪽
+        # (`agent_prompt_cli._run_worktree`)도 같은 seam 을 읽는다. 이 자리만
+        # 손으로 적은 값을 유일한 출처로 삼던 동안, 같은 run 이 어떤 경로로
+        # 디스패치됐는지에 따라 워커의 소스 루트가 달라졌다 — 그 값은
+        # writePolicy 의 `sourcePolicy.allowedRoot` 이므로, 예약본과 갈리면
+        # 같은 invocationRef 가 `invocationRef drift` 로 거부된다.
+        worktree_path=(
+            string_value(item.get("worktreePath"))
+            or worktree_path(manifest, active_context or {})
+        ),
         role=require_string(item, "role"),
         idle_timeout_seconds=idle_timeout_seconds,
         dispatch_kind=dispatch_kind,

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

@@ -7,30 +7,16 @@ regardless of provider — see ``ExecutionPolicy``.
 """
 from __future__ import annotations
 
-from dataclasses import dataclass, field
+from dataclasses import dataclass
 from pathlib import Path
-from collections.abc import Callable, Mapping
-from typing import Any, Literal, Protocol, runtime_checkable
+from typing import Literal, Protocol, runtime_checkable
 
-from .worker_stream import Normalise, no_events
+from .worker_presentation import Presentation
 from ..write_policy import WriteEnforcement, WritePolicy
 
-# What ``ExecCommand.stream_format`` may hold. The value decides whether the
-# runner pipes the CLI's output through the stream formatter or forwards it
-# unchanged, so it is part of the contract rather than a display hint.
-STREAM_JSON = "stream-json"
-TEXT = "text"
 SERVED_MODEL_MISMATCH_EXIT_CODE = 78
 
 
-def no_model_observation(_event: Mapping[str, Any]) -> str | None:
-    """Truthful default for provider output that exposes no model identity."""
-    return None
-
-
-ObserveServedModel = Callable[[Mapping[str, Any]], str | None]
-
-
 @dataclass(frozen=True)
 class ExecutionPolicy:
     """How a non-interactive worker is allowed to act.
@@ -75,31 +61,24 @@ class WorkerExecRequest:
 
 @dataclass(frozen=True)
 class ExecCommand:
-    """One provider invocation, fully resolved.
+    """공급자 호출 하나, 완전히 해소된 상태.
 
-    ``stdin_text`` is None when the provider takes its prompt as an argument
-    rather than on stdin.
+    ``stdin_text`` 는 프롬프트를 인자로 받는 CLI 에서 None 이다.
 
-    ``cwd`` is part of the contract because it is not derivable from the argv:
-    some CLIs name their working directory in a flag, others inherit the
-    process's, and the two groups do not choose the same directory. A runner
-    that had to re-derive it would be guessing at what the strategy already
-    decided.
+    ``cwd`` 가 계약에 있는 이유는 argv 에서 유도할 수 없기 때문이다 — 어떤
+    CLI 는 작업 디렉터리를 플래그로 받고 어떤 CLI 는 프로세스의 것을 물려받는데,
+    두 무리가 같은 디렉터리를 고르지 않는다.
 
-    ``normalise`` is the companion of ``stream_format``: declaring a JSON stream
-    without saying how to read it is what left one provider's pane blank for a
-    whole run. The two are named together so a provider whose events are shaped
-    differently cannot be silently handed a formatter that cannot see them.
+    ``presentation`` 은 이 CLI 의 출력을 무엇으로 볼 것인가를 정한다. 스트림
+    형식을 따로 선언하고 읽는 법을 나중에 붙이던 구조에서는, 형식만 선언하고
+    읽는 법이 어긋난 공급자의 화면이 런 내내 비어 있었다. 둘을 한 값으로 묶어
+    그 상태를 표현 불가능하게 만든다.
     """
 
     argv: tuple[str, ...]
     stdin_text: str | None
-    stream_format: str
     cwd: Path
-    normalise: Normalise = field(default=no_events)
-    observe_served_model: ObserveServedModel = field(
-        default=no_model_observation
-    )
+    presentation: Presentation
 
 
 @dataclass(frozen=True)

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

@@ -0,0 +1,128 @@
+"""워커 출력의 표현 전략.
+
+공급자 CLI 는 저마다 다른 것을 뱉는다 — 사람이 읽는 텍스트를 흘리는 CLI 도
+있고, 자기 어휘의 JSON 을 흘리는 CLI 도 있다. okstra 가 그 형식을 알아야만
+화면이 나오는 구조에서는 공급자가 형식을 바꿀 때마다 화면이 조용히 빈다.
+그래서 "해석하지 않는다" 를 1급 선택지로 둔다.
+
+전략은 두 가지를 답한다. stderr 를 stdout 에 합칠 것인가, 그리고 각 스트림의
+줄을 누가 받는가. 둘을 함께 두는 이유는 배치와 해석이 짝이기 때문이다 —
+JSON 을 요청하면 한 스트림으로 합쳐 읽어야 하고, 결과와 진행을 나눠 내는
+CLI 는 갈라 읽어야 한다.
+"""
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Callable, Literal, Mapping, Protocol, runtime_checkable
+
+from .worker_stream import (
+    Normalise,
+    final_text,
+    format_live,
+    format_log,
+)
+
+Sink = Callable[[str], str | None]
+Channel = Literal["stdout", "stderr"]
+SinkSpec = tuple[Channel, Sink]
+ObserveServedModel = Callable[[Mapping[str, Any]], str | None]
+
+WORKER = "worker"
+
+
+class TranscriptWriter(Protocol):
+    """세션 기록에 한 줄을 남긴다. 화면 출력도 이 구현이 함께 맡는다."""
+
+    def write(self, speaker: str, line: str) -> None: ...
+
+
+@runtime_checkable
+class Presentation(Protocol):
+    def merges_stderr(self) -> bool: ...
+
+    def sinks(self, writer: TranscriptWriter, live: bool) -> tuple[SinkSpec, ...]: ...
+
+
+@dataclass(frozen=True)
+class MergedText:
+    """CLI 가 사람에게 보여주는 출력을 그대로 흘린다.
+
+    한 스트림에 진행과 결과가 함께 온다. 해석하지 않으므로 공급자가 형식을
+    바꿔도 화면이 깨지지 않는다.
+    """
+
+    served_model_at_exit: Callable[[str, Path], str | None] | None = None
+
+    def merges_stderr(self) -> bool:
+        return True
+
+    def sinks(self, writer: TranscriptWriter, live: bool) -> tuple[SinkSpec, ...]:
+        def emit(line: str) -> str | None:
+            writer.write(WORKER, line)
+            return line
+
+        return (("stdout", emit),)
+
+
+@dataclass(frozen=True)
+class SplitText:
+    """결과와 진행을 다른 스트림으로 내는 CLI.
+
+    stdout 은 답이고 stderr 는 진행이다. 답은 어느 모드에서도 호출자에게
+    가야 하므로 종결 텍스트로 돌려주고, 진행은 기록과 화면에만 남는다.
+    """
+
+    def merges_stderr(self) -> bool:
+        return False
+
+    def sinks(self, writer: TranscriptWriter, live: bool) -> tuple[SinkSpec, ...]:
+        def result(line: str) -> str | None:
+            writer.write(WORKER, line)
+            return line
+
+        def progress(line: str) -> str | None:
+            writer.write(WORKER, line)
+            return None
+
+        return (("stdout", result), ("stderr", progress))
+
+
+@dataclass(frozen=True)
+class JsonEvents:
+    """공급자 어휘의 JSON 을 공통 이벤트로 옮겨 적는다.
+
+    사람이 읽는 출력에 진행이 없는 CLI 를 위한 경로다. 어휘를 아는 대가로
+    도구 호출을 구조로 보여줄 수 있다.
+    """
+
+    normalise: Normalise
+    observe: ObserveServedModel
+
+    def merges_stderr(self) -> bool:
+        return True
+
+    def sinks(self, writer: TranscriptWriter, live: bool) -> tuple[SinkSpec, ...]:
+        def emit(line: str) -> str | None:
+            stripped = line.strip()
+            if not stripped:
+                return None
+            try:
+                event = json.loads(stripped)
+            except ValueError:
+                # 이벤트가 아니다. CLI 자신의 오류 텍스트가 이 스트림으로
+                # 오므로 삼키면 아무도 못 본다.
+                writer.write(WORKER, stripped)
+                return None
+            if not isinstance(event, dict):
+                return None
+            self.observe(event)
+            closing: str | None = None
+            for entry in self.normalise(event):
+                for row in (format_live(entry) if live else format_log(entry)):
+                    writer.write(WORKER, row)
+                closing = final_text(entry) or closing
+            return closing
+
+        return (("stdout", emit),)

package/runtime/python/okstra_ctl/execution_manifest.py

@@ -118,6 +118,22 @@ def append_role_execution(
             )
 
 
+def _drift_detail(existing: Invocation, incoming: Invocation) -> str:
+    """어긋난 필드를 이름으로 돌려준다.
+
+    `invocationRef drift: <ref>` 만으로는 무엇이 달라졌는지 알 수 없어, 리드가
+    새 invocation id 를 몇 개씩 만들어 보는 것 말고 할 수 있는 일이 없었다.
+    같은 ref 로 두 번째 예약이 오는 것 자체는 정상 경로(재materialize)이고,
+    거절해야 하는 것은 '내용이 달라진' 경우뿐이므로 그 내용을 이름 붙인다.
+    """
+    before = existing.to_payload()
+    after = incoming.to_payload()
+    changed = sorted(
+        key for key in (*before, *after) if before.get(key) != after.get(key)
+    )
+    return ", ".join(changed) if changed else "(no field differs)"
+
+
 def reserve_derived_role_invocation(
     path: Path,
     *,
@@ -169,7 +185,8 @@ def reserve_derived_role_invocation(
         if existing_invocation is not None:
             if existing_invocation != invocation:
                 raise ExecutionManifestError(
-                    f"invocationRef drift: {invocation.invocation_ref}"
+                    f"invocationRef drift: {invocation.invocation_ref} "
+                    f"(differs in: {_drift_detail(existing_invocation, invocation)})"
                 )
             if created:
                 raise ExecutionManifestError(
@@ -242,7 +259,8 @@ def ensure_invocation(path: Path, row: Invocation, *, task_key: str) -> Invocati
         if existing is not None:
             if existing != row:
                 raise ExecutionManifestError(
-                    f"invocationRef drift: {row.invocation_ref}"
+                    f"invocationRef drift: {row.invocation_ref} "
+                    f"(differs in: {_drift_detail(existing, row)})"
                 )
             return existing
         _validate_next_invocation(manifest, row)
@@ -289,7 +307,8 @@ def record_invocation_attempt(
         )
         if existing is not None and existing != invocation:
             raise ExecutionManifestError(
-                f"invocationRef drift: {invocation.invocation_ref}"
+                f"invocationRef drift: {invocation.invocation_ref} "
+                f"(differs in: {_drift_detail(existing, invocation)})"
             )
         invocations = manifest.invocations
         if existing is None:

package/runtime/python/okstra_ctl/execution_mutation_audit.py

@@ -528,6 +528,32 @@ def _stable_git_projection(snapshot: MutationSnapshot) -> dict[str, Any]:
     }
 
 
+def _path_ledger_is_unenforceable(policy: WritePolicy) -> bool:
+    """이 정책의 경로 장부를 근거로 변경을 거절할 수 있는가.
+
+    승인된 계획서에 `plannedPaths` 컬럼이 있으면 실행기는 그 목록에 묶이고,
+    목록은 반드시 비어 있지 않다(`write_policy._planned_paths_from_report` 는
+    선언된 경우에만 항목을 싣는다). 그 컬럼이 없는 옛 계획서에서는 실을 값이
+    없어 장부가 빈 채로 온다 — 종전에는 산문에서 유도한 문장 조각(`28 rows)`,
+    `captured in Stage 1)`)을 실었고, 그래서 계획이 지시한 파일 전부가 미허가
+    변경으로 읽혔다.
+
+    `project-mutation` 정책에서만 빈 장부가 "물을 수 없음" 을 뜻한다.
+    `source-readonly` 워커는 장부가 원래 비어 있고 그것이 "아무것도 바꾸지
+    말라" 는 뜻이므로, 그쪽 집행은 건드리지 않는다.
+
+    이 판정은 감사의 두 절반이 같은 함수를 읽는다. 종전에는 git 쪽만
+    `plannedPathsDeclared` 를 봤는데 그 키는 `build_write_policy` 가 만드는
+    sourcePolicy 에 아예 실리지 않아(4개 키 고정, `validate_write_policy_payload`
+    가 그 집합을 강제) 어느 쪽에서도 참이 된 적이 없다.
+    """
+    source = policy.source_policy
+    return (
+        source.get("mode") == "project-mutation"
+        and not source.get("plannedPaths")
+    )
+
+
 def _source_policy_failures(
     policy: WritePolicy,
     changed: set[str],
@@ -537,7 +563,10 @@ def _source_policy_failures(
     declared = set(out_of_plan_edits)
     protected = set(policy.source_policy.get("protectedPaths", ()))
     failures: list[str] = []
-    if not changed <= planned | declared:
+    if (
+        not _path_ledger_is_unenforceable(policy)
+        and not changed <= planned | declared
+    ):
         failures.append("source changes exceed planned and declared out-of-plan paths")
     if not declared <= changed:
         failures.append("declared out-of-plan path did not change")
@@ -571,6 +600,11 @@ def _git_policy_failures(
     if not _is_ancestor(root, str(git.get("expectedBaseCommit")), str(after.git_projection.get("head"))):
         failures.append("final HEAD is not a fast-forward descendant")
     allowed = set(policy.source_policy.get("plannedPaths", ())) | set(out_of_plan_edits)
+    if _path_ledger_is_unenforceable(policy):
+        # The plan predates the declared path column, so there is no ledger
+        # anyone can be held to. Every other check above still applies; only
+        # the path comparison stands down.
+        return failures
     if any(
         not paths <= allowed
         for paths in _commit_paths_by_commit(