okstra 0.201.3 → 0.204.0

package/runtime/python/okstra_ctl/dispatch_core.py

@@ -96,6 +96,7 @@ from .initial_prompt_materialization import (
     InitialPromptMaterializationRequest,
     InitialPromptWorkerRequest,
     PromptDeliveryMode,
+    declared_delivery_mode,
     materialize_initial_prompts,
 )
 from .agent.invocation import AgentInvocationError, materialize_retry_invocation
@@ -183,6 +184,9 @@ def revalidate_role_execution(
                 interaction_surface="role-execution-dispatch",
             ),
             environment=host,
+            # 이 run 은 이 모델을 이미 골랐다. 지금 고를 수 있는지가 아니라 그
+            # 배정이 그대로 실행 가능한지를 묻는 자리다.
+            require_selectable=False,
         )
         binding = assignment.binding
         if binding is None:
@@ -261,6 +265,7 @@ class WorkerHandle:
     completed_process: subprocess.CompletedProcess[str] | None
     status_sidecar_path: Path | None
     degraded_from: str
+    degraded_reason: str = ""
     running_process: subprocess.Popen[str] | None = None
     mutation_snapshot: MutationSnapshot | None = None
     mutation_policies: tuple[WritePolicy, ...] = ()
@@ -1439,31 +1444,11 @@ def _invocation_job_fields(
 def _initial_prompt_delivery_mode(
     manifest: Mapping[str, Any],
 ) -> PromptDeliveryMode:
-    """이 run 의 어댑터가 선언한 초기 프롬프트 배송 방식.
-
-    선언은 `leadAdapter.initialPromptDeliveryMode` 에 있고, 그 값은 render 가
-    호스트 descriptor(어댑터가 워커 디스패치를 가져갔으면 그 어댑터)에서
-    옮겨 적은 것이다. 선언이 없는 매니페스트는 이 필드가 생기기 전에 준비된
-    run 이므로 그때의 동작인 `eager-include` 로 간다. 아는 값이 아니면 멈춘다 —
-    프롬프트를 발행하고 나면 그 프롬프트는 불변이라, 잘못 고른 배송 방식은
-    나중에 고칠 수 없다.
-    """
-    adapter = manifest.get("leadAdapter")
-    declared = (
-        _string_value(adapter.get("initialPromptDeliveryMode"))
-        if isinstance(adapter, Mapping)
-        else ""
-    )
-    if not declared:
-        return PromptDeliveryMode.EAGER_INCLUDE
+    """이 run 의 초기 프롬프트 배송 방식. 판정은 `declared_delivery_mode` 가 한다."""
     try:
-        return PromptDeliveryMode(declared)
-    except ValueError:
-        allowed = ", ".join(mode.value for mode in PromptDeliveryMode)
-        raise DispatchError(
-            "leadAdapter.initialPromptDeliveryMode is not a delivery mode: "
-            f"{declared!r} (allowed: {allowed})"
-        ) from None
+        return declared_delivery_mode(manifest)
+    except InitialPromptMaterializationError as exc:
+        raise DispatchError(str(exc)) from None
 
 
 def _materialize_roster_prompts(
@@ -2034,8 +2019,20 @@ def _start_job(plan: DispatchPlan, job: WorkerJob) -> WorkerHandle:
         raise DispatchError(str(exc)) from exc
     degraded_from = job.backend if runtime.surface != job.backend else ""
     settled = replace(job, backend=runtime.surface) if degraded_from else job
+    if degraded_from:
+        print(
+            f"DEGRADED {job.role}: {degraded_from} -> {runtime.surface} "
+            f"({runtime.fallback_reason or 'no reason reported'})",
+            flush=True,
+        )
     completed = None
-    if runtime.waitable:
+    # 강등된 job 은 여기서 기다리지 않는다. `dispatch_plan` 은 wait=True 에서
+    # pane job 을 거절하므로(같은 함수의 pane_backends 검사) 강등은 비차단 배치
+    # 에서만 일어난다. 그 배치에서 기다리면 라운드가 직렬화되고 — 실측 2026-09-21,
+    # 워커 3명이 병렬 대신 37분 — dispatch 행이 워커가 끝난 뒤에야 써져
+    # `okstra worker-liveness` 가 실행 중인 워커를 모른다. 정산은 상태 사이드카를
+    # 읽는 `await_dispatches` 가 맡는다.
+    if runtime.waitable and not degraded_from:
         from .adapters.runtime.assembly import port_for
         returncode = port_for(plan.runtime_chain, runtime.surface).wait(runtime)
         completed = subprocess.CompletedProcess(list(settled.command), returncode)
@@ -2046,6 +2043,7 @@ def _start_job(plan: DispatchPlan, job: WorkerJob) -> WorkerHandle:
         completed,
         status_path_for_prompt(settled.prompt_path),
         degraded_from,
+        degraded_reason=runtime.fallback_reason,
         runtime_handle=runtime,
         started_at=started_at,
     )
@@ -2237,9 +2235,28 @@ def _retry_from_record(
 # 사유 한 줄에 실을 경로 개수. 전부 실으면 team-state 행이 부풀고, 하나도 안
 # 실으면 읽는 쪽이 다른 파일을 뒤져야 한다.
 _MUTATION_REASON_PATH_LIMIT = 5
+# 사유는 team-state 의 한 행이다. 래퍼 실패 문장은 길 수 있으므로 자른다.
+_MUTATION_REASON_FAILURE_LIMIT = 200
+
+
+def _wrapper_failure_text(outcome: WorkerOutcome | None) -> str:
+    """워커 래퍼가 남긴 실패 문장. 없으면 빈 문자열.
+
+    `mutation-present-unresolved` 는 "시도가 실패했는데 소스가 바뀌어 있다" 는
+    뜻이고, 왜 실패했는지는 상태 사이드카에만 있었다. 읽는 쪽은 상태 이름만 보고
+    소스를 뒤져야 했다 — 실측 2026-09-23: 두 세션이 같은 자리에서 그렇게
+    진단했고, 원인은 카탈로그에 없는 served 모델이었다.
+    """
+    if outcome is None or outcome.status_sidecar_path is None:
+        return ""
+    status = read_wrapper_status(outcome.status_sidecar_path)
+    if status is None:
+        return ""
+    failure = _string_value(status.raw.get("failure"))
+    return failure[:_MUTATION_REASON_FAILURE_LIMIT]
 
 
-def _mutation_failure_reason(mutation) -> str:
+def _mutation_failure_reason(mutation, outcome: WorkerOutcome | None = None) -> str:
     """왜 실패했는지와 무엇이 바뀌었는지를 한 줄에 담는다.
 
     종전에는 디스패치 행에 `readonly source changed` 만 남고 바뀐 경로는
@@ -2249,6 +2266,9 @@ def _mutation_failure_reason(mutation) -> str:
     사유 옆에 놓는다.
     """
     reason = "; ".join(mutation.violations) or mutation.status
+    failure = _wrapper_failure_text(outcome)
+    if failure:
+        reason = f"{reason}: {failure}"
     paths = list(mutation.changed_paths)
     if not paths:
         return reason
@@ -2273,7 +2293,7 @@ def _finish_attempt(
         "contract-failed-unattributed",
         "mutation-present-unresolved",
     }:
-        reason = _mutation_failure_reason(mutation)
+        reason = _mutation_failure_reason(mutation, outcome)
         _update_dispatch_status(
             plan.team_state_path, job, attempt, "error", reason
         )
@@ -2913,6 +2933,7 @@ def _record_dispatch(
             handle.pane_id,
             handle.degraded_from,
             reason,
+            degraded_reason=handle.degraded_reason,
             mutation_snapshot_path=(
                 _mutation_snapshot_path(handle.job)
                 if handle.mutation_snapshot is not None
@@ -2932,6 +2953,7 @@ def _dispatch_record(
     degraded_from: str,
     reason: str = "",
     *,
+    degraded_reason: str = "",
     mutation_snapshot_path: Path | None = None,
     write_policy_digest: str = "",
     write_enforcement: WriteEnforcement | None = None,
@@ -2958,6 +2980,9 @@ def _dispatch_record(
         ),
         "statusSidecarPath": str(status_path_for_prompt(job.prompt_path)),
         "degradedFrom": degraded_from,
+        # `reason` 은 이 행의 정산 사유라 마감과 teardown 이 덮어쓴다. 강등 사유는
+        # 디스패치 시점의 사실이므로 자기 칸을 쓴다.
+        "degradedReason": degraded_reason,
         "reason": reason,
         "modelExecutionValue": job.model_execution_value,
         "wrapperPath": str(job.wrapper_path),
@@ -3186,6 +3211,7 @@ def _event_details(job: WorkerJob, handle: WorkerHandle) -> dict[str, Any]:
         "role": job.role,
         "paneId": handle.pane_id,
         "degradedFrom": handle.degraded_from,
+        "degradedReason": handle.degraded_reason,
     }
     return details
 

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

@@ -51,6 +51,11 @@ class HostDescriptor:
     session_accounting: str
     has_claude_session: bool
     relay_contract: str
+    # 이 호스트 세션 안에서 도는 워커(runner=native-session)가 읽어야 하는
+    # 계약 파일의 절대 경로. 호스트가 그런 계약을 선언하지 않으면 빈 문자열이다.
+    # 호스트 전역 발견 경로에 설치되지 않는다 — 디스패치 프롬프트가 경로로
+    # 전달하고, 워커가 프리앰블과 같은 방식으로 연다.
+    worker_session_contract: str = ""
     # 이 호스트가 초기 워커 프롬프트를 어떻게 싣겠다고 선언하는가. 값은
     # `relay.md` 의 `initialPromptDeliveryMode` 행과 같아야 한다 — 그 표를
     # 읽고 dispatch 를 판단하는 것은 리드이고, 실제로 프롬프트를 만드는 것은

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

@@ -31,9 +31,19 @@ class WorkerSpawnRequest:
 
 @dataclass(frozen=True)
 class RuntimeHandle:
+    """An opened surface, and why it is not the one that was planned.
+
+    `fallback_reason` is empty when the planned surface opened. It carries the
+    last `SurfaceUnavailable` message when an earlier surface in the chain was
+    skipped, because that message exists nowhere else: the chain swallows the
+    exception it recovers from, and a degraded dispatch used to be recorded
+    with an empty reason.
+    """
+
     surface: str
     identifier: str
     waitable: bool
+    fallback_reason: str = ""
 
 
 @dataclass(frozen=True)

package/runtime/python/okstra_ctl/error_report.py

@@ -1,8 +1,8 @@
 """Read-side aggregator for okstra-run error logs.
 
 task 의 모든 run errors-<type>-<seq>.jsonl 을 모아 phase / worker / errorType
-별로 집계하고 timestamp 누적 .md 리포트로 렌더한다. task 산출물을 mutate 하지
-않는다.
+별로 집계하고 timestamp 누적 .md 리포트로 렌더한다. 리포트 외에 쓰는 것은
+task 해석 중 `find_task_root` 가 끝난 implementation 결과를 기록하는 경우뿐이다.
 """
 from __future__ import annotations
 
@@ -236,7 +236,8 @@ _CLI_EPILOG = r"""Usage:
 
 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.
+Resolving a task may record a finished implementation outcome in its task
+manifest, the task catalog, and consumers.jsonl; nothing else is written.
 """
 
 

package/runtime/python/okstra_ctl/execution_manifest.py

@@ -213,7 +213,9 @@ def reserve_derived_role_invocation(
             raise ExecutionManifestError(
                 f"source role execution is unknown: {source_role_execution_ref}"
             )
-        derived, created = _derived_role_execution(manifest, source, role)
+        derived, created, derived_participant = _derived_role_execution(
+            manifest, source, role
+        )
         invocation = invocation_factory(derived)
         if not isinstance(invocation, Invocation):
             raise ExecutionManifestError("invocation factory must return Invocation")
@@ -244,14 +246,22 @@ def reserve_derived_role_invocation(
                 _write_json_atomic(task_manifest_path, recovered_task_payload)
             return derived, existing_invocation
 
+        base = manifest
+        if created and derived_participant is not None:
+            base = _replace_manifest(
+                manifest,
+                participant_assignments=(
+                    *manifest.participant_assignments,
+                    derived_participant,
+                ),
+            )
         roles = (
-            (*manifest.role_executions, derived)
-            if created
-            else manifest.role_executions
+            (*base.role_executions, derived) if created else base.role_executions
         )
-        with_role = _replace_manifest(manifest, role_executions=roles)
+        with_role = _replace_manifest(base, role_executions=roles)
         if created:
-            _validate_next_role_execution(manifest, derived)
+            # 새 참가자가 실린 뒤라야 참가자 참조 검사가 성립한다.
+            _validate_next_role_execution(base, derived)
         _validate_next_invocation(with_role, invocation)
         updated = _replace_manifest(
             with_role,
@@ -540,11 +550,13 @@ def _validate_roles(
                     "sourceRoleExecutionRef must reference an earlier different "
                     "role execution"
                 )
-            if source_role.get("participantRef") != participant_ref:
-                raise ExecutionManifestError(
-                    "sourceRoleExecutionRef participant must match derived role "
-                    "participant"
-                )
+            # 참가자는 더 이상 공유하지 않는다(ADR-0017). 파생을 파생이게 하는
+            # 것은 같은 모델로 같은 일을 다시 읽는다는 것이므로, 거기를 검사한다.
+            for key in ("provider", "modelRef", "modelId"):
+                if source_role.get(key) != row.get(key):
+                    raise ExecutionManifestError(
+                        f"derived role execution {key} must match its source"
+                    )
         earlier_roles[role_ref] = row
     for role, values in ordinals.items():
         if sorted(values) != list(range(1, len(values) + 1)):
@@ -815,20 +827,29 @@ def _derived_role_execution(
     manifest: ExecutionManifest,
     source: RoleExecution,
     role: str,
-) -> tuple[RoleExecution, bool]:
+) -> tuple[RoleExecution, bool, ParticipantAssignment | None]:
+    """The dynamic role slot derived from *source*, creating it when absent.
+
+    A created slot is its own participant. It copies the source's provider,
+    model and binding — that is what makes it the same model re-reading the
+    same work — but not the source's identity or session. Sharing the
+    participant made the derived slot indistinguishable from its source
+    wherever a participant is what gets attributed or resumed.
+    """
     if source.role == role:
-        return source, False
+        return source, False, None
     existing = [
         item
         for item in manifest.role_executions
-        if item.participant_ref == source.participant_ref and item.role == role
+        if item.source_role_execution_ref == source.role_execution_ref
+        and item.role == role
     ]
     if len(existing) > 1:
         raise ExecutionManifestError(
-            f"participant has multiple {role} role executions: {source.participant_ref}"
+            f"source has multiple {role} role executions: {source.role_execution_ref}"
         )
     if existing:
-        return existing[0], False
+        return existing[0], False, None
     ordinal = max(
         (item.ordinal for item in manifest.role_executions if item.role == role),
         default=0,
@@ -840,9 +861,10 @@ def _derived_role_execution(
         raise ExecutionManifestError(
             f"derived roleExecutionRef is already reserved: {role_ref}"
         )
+    participant = _derived_participant(manifest, source)
     return RoleExecution(
         role_execution_ref=role_ref,
-        participant_ref=source.participant_ref,
+        participant_ref=participant.participant_ref,
         source_role_execution_ref=source.role_execution_ref,
         role=role,
         provider=source.provider,
@@ -859,7 +881,38 @@ def _derived_role_execution(
         binding=source.binding,
         served_model_attestation=ServedModelAttestation.unknown(),
         status="prepared",
-    ), True
+    ), True, participant
+
+
+def _derived_participant(
+    manifest: ExecutionManifest,
+    source: RoleExecution,
+) -> ParticipantAssignment:
+    """A fresh participant carrying the source's model but none of its session."""
+    origin = next(
+        (
+            item
+            for item in manifest.participant_assignments
+            if item.participant_ref == source.participant_ref
+        ),
+        None,
+    )
+    if origin is None:
+        raise ExecutionManifestError(
+            f"source role execution references unknown participant: "
+            f"{source.participant_ref}"
+        )
+    used = {item.participant_ref for item in manifest.participant_assignments}
+    ordinal = len(used) + 1
+    while f"participant-{ordinal:03d}" in used:
+        ordinal += 1
+    return replace(
+        origin,
+        participant_ref=f"participant-{ordinal:03d}",
+        session_ref=None,
+        window_ref=None,
+        status="prepared",
+    )
 
 
 def _validate_next_invocation(manifest: ExecutionManifest, row: Invocation) -> None:

package/runtime/python/okstra_ctl/execution_mutation_audit.py

@@ -122,6 +122,7 @@ class MutationAuditResult:
     changed_artifact_paths: tuple[str, ...] = ()
     declared_out_of_plan_paths: tuple[str, ...] = ()
     unobserved_artifact_paths: tuple[str, ...] = ()
+    external_workspace_changes: tuple[str, ...] = ()
 
     def change_summary(self) -> dict[str, Any]:
         return {
@@ -138,6 +139,7 @@ class MutationAuditResult:
             "changedArtifactPaths": list(self.changed_artifact_paths),
             "declaredOutOfPlanPaths": list(self.declared_out_of_plan_paths),
             "unobservedArtifactPaths": list(self.unobserved_artifact_paths),
+            "externalWorkspaceChanges": list(self.external_workspace_changes),
             "beforeDigest": self.before_digest,
             "afterDigest": self.after_digest,
         }
@@ -240,13 +242,13 @@ class ExecutionMutationAudit:
             rows,
             source_changes,
         )
-        artifact_failures, untracked_artifact_changes, switched = (
+        artifact_failures, untracked_artifact_changes, switched, external = (
             _artifact_policy_failures(before, rows, artifact_changed, after=after)
         )
         violations.extend(artifact_failures)
         worker_artifact_changes = {
             path for path in artifact_changed
-            if path not in untracked_artifact_changes and path not in switched
+            if path not in untracked_artifact_changes and path not in switched and path not in external
             and not any(_is_relative_to(before.artifact_root / path, Path(item))
                         for item in before.orchestrator_paths)
         }
@@ -276,11 +278,14 @@ class ExecutionMutationAudit:
             untracked_artifact_paths=tuple(sorted(untracked_artifact_changes)),
             warnings=_audit_warnings(untracked_artifact_changes)
             + _branch_switch_warnings(before, after, switched)
+            + tuple(f"unattributed change outside assigned worktree and artifact paths: {path}"
+                    for path in sorted(external))
             + _plan_change_warnings(rows, source_changes | untracked_changes,
                                     artifact_changed, out_of_plan_edits, unobserved),
-            changed_artifact_paths=tuple(sorted(artifact_changed)),
+            changed_artifact_paths=tuple(sorted(artifact_changed - external)),
             declared_out_of_plan_paths=tuple(out_of_plan_edits),
             unobserved_artifact_paths=tuple(sorted(unobserved)),
+            external_workspace_changes=tuple(sorted(external)),
         )
 
 
@@ -753,22 +758,12 @@ def _artifact_policy_failures(
     changed: set[str],
     *,
     after: MutationSnapshot | None = None,
-) -> tuple[list[str], set[str], set[str]]:
-    """``(위반 목록, 위반이 아닌 비추적 신규 경로, 브랜치 전환으로 설명되는 경로)``.
-
-    artifact root 의 변경 중 위반으로 남는 것은 두 부류다 — okstra 산출물
-    서브트리(`.okstra/`) 안의 허용 밖 쓰기와, git 이 추적하는 파일의 변경.
-    그 밖의 비추적 신규 파일은 워커의 도구가 남긴 로그·캐시이므로 소스 root 의
-    `_split_tracked` 와 같은 이유로 기록만 한다. artifact root 가 git 레포가
-    아니면 추적 여부를 알 수 없으므로 종전대로 전부 위반으로 본다.
-
-    추적 파일의 변경 중 **artifact root 의 HEAD 가 실행 창 안에서 옮겨졌고 그
-    두 커밋 사이에서 실제로 달라지는 경로**는 워커의 쓰기가 아니라 사람의 브랜치
-    전환이다. 실측(2026-09-09, `fontsninja-v3-site` dev-10627 reverify r1b): 워커가
-    워크트리에서 읽기만 하는 8분 동안 프로젝트 루트에서 `checkout preprod →
-    rebase` 가 있었고, run 브랜치에만 있는 `CardHero.{tsx,styled.ts}` 가 사라져
-    완주한 결과가 `contract-failed-unattributed` 로 폐기됐다. 그 경로는 위반에서
-    빼고 경고로 남긴다. 전환으로 설명되지 않는 추적 파일 변경은 그대로 위반이다.
+) -> tuple[list[str], set[str], set[str], set[str]]:
+    """위반·비추적 파일·브랜치 전환·외부 작업공간 관측을 분리한다.
+
+    작업트리와 기본 체크아웃이 다르면 기본 체크아웃 소스의 변경 주체는
+    전후 비교로 판단할 수 없다. 배정된 산출물 밖의 변경은 관측으로 남기고,
+    `.okstra` 내부의 허용 밖 쓰기와 배정된 소스 정책은 별도로 검사한다.
     """
     allowed = _allowed_artifact_paths(policies)
     orchestrator = {
@@ -799,9 +794,14 @@ def _artifact_policy_failures(
         if path in unauthorized and not _is_within(path, _OKSTRA_ARTIFACT_SUBTREE)
     }
     untracked_outside -= switched
-    violating = unauthorized - untracked_outside - switched
+    external = {
+        path for path in unauthorized - untracked_outside - switched
+        if snapshot.artifact_root != snapshot.root
+        and not _is_within(path, _OKSTRA_ARTIFACT_SUBTREE)
+    }
+    violating = unauthorized - untracked_outside - switched - external
     failures = ["artifact-root change exceeds batch policy union"] if violating else []
-    return failures, untracked_outside, switched
+    return failures, untracked_outside, switched, external
 
 
 def _branch_switch_paths(