okstra 0.167.0 → 0.169.0

package/runtime/python/okstra_ctl/run.py

@@ -22,6 +22,7 @@ import re
 import shutil
 import subprocess as _subprocess
 import sys
+import tempfile
 from dataclasses import dataclass, field
 from datetime import datetime, timezone
 from pathlib import Path
@@ -82,6 +83,18 @@ from .models import (
 from .schema_excerpt import build_schema_excerpt
 from .registry.host_registry import default_host_registry
 from .registry.provider_registry import default_provider_registry
+from .ports.host_model import HostModelBindingError, HostModelBindingRequest
+from .agent_invocation import (
+    AgentInstruction,
+    AgentInstructionSource,
+    AgentInvocationRequest,
+    AgentModelAssignment,
+    AgentInvocationError,
+    agent_model_assignment_from_payload,
+    digest_duty_catalog,
+    prepare_agent_invocation,
+    verify_agent_invocation,
+)
 from .report_contract import CURRENT_REPORT_SCHEMA_VERSION
 from .path_resolve import relative_to_project_root, resolve_user_file
 from .render import (
@@ -1355,15 +1368,24 @@ class RoleAssignment:
     model_display: str
     model_execution_value: str
     runner: str
+    host_runtime: str
+    host_model_value: str | None
     worker_id: str = ""
 
-    def to_payload(self) -> dict[str, str]:
-        payload = {
-            "role": self.role,
+    def to_model_payload(self) -> dict[str, object]:
+        return {
             "provider": self.provider,
             "model": self.model_display,
             "modelExecutionValue": self.model_execution_value,
             "runner": self.runner,
+            "hostRuntime": self.host_runtime,
+            "hostModelValue": self.host_model_value,
+        }
+
+    def to_payload(self) -> dict[str, object]:
+        payload = {
+            "role": self.role,
+            **self.to_model_payload(),
         }
         if self.worker_id:
             payload["workerId"] = self.worker_id
@@ -1386,15 +1408,13 @@ class _ModelBindings:
     rw: ModelAssignment
     critic_choice: str
     critic_model_execution: str
-    executor_provider: str
     executor_display_name: str
-    executor_worker_agent: str
-    executor_model_meta: ModelAssignment
     codex_worker_execution: str
     antigravity_worker_execution: str
-    executor_execution: str
+    executor_assignment: RoleAssignment
     lead_assignment: RoleAssignment
     worker_assignments: tuple[RoleAssignment, ...]
+    invocation_assignments: dict[str, dict[str, object]]
 
 
 def recommended_role_models() -> dict[str, str]:
@@ -1536,6 +1556,7 @@ def _resolve_model_bindings(inp: PrepareInputs, workers: list[str]) -> _ModelBin
             f"(got: {critic_choice!r})"
         )
     critic_model_execution = ""
+    critic_meta = None
     if critic_choice in provider_ids("critic"):
         critic_meta = _model_for_role(
             critic_choice,
@@ -1561,7 +1582,6 @@ def _resolve_model_bindings(inp: PrepareInputs, workers: list[str]) -> _ModelBin
         )
     model_meta = m["providers"][executor_provider]
     display_name = f"{provider_spec(executor_provider).display_label} executor"
-    worker_agent = f"{executor_provider}-worker"
     lead_provider = m["lead_provider"]
     lead_execution = m["lead"].execution
     lead_runner = _assignment_runner(inp.lead_runtime, lead_provider, "lead")
@@ -1569,29 +1589,69 @@ def _resolve_model_bindings(inp: PrepareInputs, workers: list[str]) -> _ModelBin
         lead_execution = _normalized_execution(
             m["lead"], provider=lead_provider, role="lead",
         )
+    lead_assignment = _role_assignment(
+        host_runtime=inp.lead_runtime,
+        role="lead",
+        provider=lead_provider,
+        model=m["lead"],
+        execution=lead_execution,
+        runner_role="lead",
+    )
     worker_assignments = _build_worker_assignments(inp, workers, m)
+    critic_assignment = (
+        _role_assignment(
+            host_runtime=inp.lead_runtime,
+            role="critic",
+            provider=critic_choice,
+            model=critic_meta,
+            execution=critic_model_execution,
+            runner_role="critic",
+        )
+        if critic_meta is not None
+        else None
+    )
+    translator_assignment = _role_assignment(
+        host_runtime=inp.lead_runtime,
+        role="translator",
+        provider=m["report_writer_provider"],
+        model=m["rw"],
+        execution=_normalized_execution(
+            m["rw"],
+            provider=m["report_writer_provider"],
+            role="report-writer",
+        ),
+        runner_role="report-writer",
+    )
+    executor_assignment = _role_assignment(
+        host_runtime=inp.lead_runtime,
+        role="executor",
+        provider=executor_provider,
+        model=model_meta,
+        execution=_normalized_execution(
+            model_meta, provider=executor_provider, role="executor"
+        ),
+        runner_role="executor",
+        worker_id=executor_provider,
+    )
+    invocation_assignments = _build_invocation_assignments(
+        lead_assignment,
+        worker_assignments,
+        critic_assignment,
+        translator_assignment,
+    )
     return _ModelBindings(
         lead=m["lead"], cw=m["cw"], co=m["co"], ge=m["ge"], rw=m["rw"],
         critic_choice=critic_choice,
         critic_model_execution=critic_model_execution,
-        executor_provider=executor_provider,
         executor_display_name=display_name,
-        executor_worker_agent=worker_agent,
-        executor_model_meta=model_meta,
         codex_worker_execution=_worker_execution_value(
             m["co"], "codex", "worker", workers),
         antigravity_worker_execution=_worker_execution_value(
             m["ge"], "antigravity", "worker", workers),
-        executor_execution=_normalized_execution(
-            model_meta, provider=executor_provider, role="executor"),
-        lead_assignment=RoleAssignment(
-            role="lead",
-            provider=lead_provider,
-            model_display=m["lead"].display,
-            model_execution_value=lead_execution,
-            runner=lead_runner,
-        ),
+        executor_assignment=executor_assignment,
+        lead_assignment=lead_assignment,
         worker_assignments=worker_assignments,
+        invocation_assignments=invocation_assignments,
     )
 
 
@@ -1609,17 +1669,90 @@ def _build_worker_assignments(
         execution = _worker_execution_value(
             meta, provider, "worker", [provider],
         )
-        assignments.append(RoleAssignment(
+        assignments.append(_role_assignment(
+            host_runtime=inp.lead_runtime,
             role=role,
             provider=provider,
-            model_display=meta.display,
-            model_execution_value=execution,
-            runner=_assignment_runner(inp.lead_runtime, provider, role),
+            model=meta,
+            execution=execution,
+            runner_role=role,
             worker_id=worker_id,
         ))
     return tuple(assignments)
 
 
+def _role_assignment(
+    *,
+    host_runtime: str,
+    role: str,
+    provider: str,
+    model: ModelAssignment,
+    execution: str,
+    runner_role: str,
+    worker_id: str = "",
+) -> RoleAssignment:
+    runner = _assignment_runner(host_runtime, provider, runner_role)
+    host_model_value = _resolve_host_model_value(
+        host_runtime=host_runtime,
+        provider=provider,
+        model=model,
+        execution=execution,
+        runner=runner,
+    )
+    return RoleAssignment(
+        role=role,
+        provider=provider,
+        model_display=model.display,
+        model_execution_value=execution,
+        runner=runner,
+        host_runtime=host_runtime,
+        host_model_value=host_model_value,
+        worker_id=worker_id,
+    )
+
+
+def _resolve_host_model_value(
+    *,
+    host_runtime: str,
+    provider: str,
+    model: ModelAssignment,
+    execution: str,
+    runner: str,
+) -> str | None:
+    try:
+        port = default_host_registry().resolve(host_runtime).host_model()
+        return port.resolve(HostModelBindingRequest(
+            host_runtime=host_runtime,
+            provider=provider,
+            model=model.display,
+            model_execution_value=execution,
+            runner=runner,
+        ))
+    except (HostModelBindingError, HostNotRegistered) as exc:
+        raise PrepareError(str(exc)) from exc
+
+
+def _build_invocation_assignments(
+    lead: RoleAssignment,
+    workers: tuple[RoleAssignment, ...],
+    critic: RoleAssignment | None,
+    translator: RoleAssignment,
+) -> dict[str, dict[str, object]]:
+    assignments = {"lead": lead.to_model_payload()}
+    for assignment in workers:
+        assignments[f"initial/{assignment.worker_id}"] = (
+            assignment.to_model_payload()
+        )
+        assignments[f"reverify/{assignment.worker_id}"] = (
+            assignment.to_model_payload()
+        )
+    if critic is not None:
+        assignments["critic/scope"] = critic.to_model_payload()
+        assignments["critic/acceptance"] = critic.to_model_payload()
+    assignments["translator"] = translator.to_model_payload()
+    return assignments
+
+
 def _normalized_execution(meta: ModelAssignment, provider: str, role: str) -> str:
     """Route a role's catalog execution value through the CLI-identity normalizer
     so the manifest carries the dispatch-correct spelling. SSOT for the mapping
@@ -1853,11 +1986,14 @@ def _write_instruction_set_sources(
     if inp.task_type == "implementation":
         profile_rendered += "\n\n{{DESIGN_PREP_CONTEXT}}\n\n{{FIX_RUN_CONTEXT}}"
     profile_tokens = (
+        "EXECUTOR_WORKER_ID",
         "EXECUTOR_PROVIDER",
         "EXECUTOR_DISPLAY_NAME",
-        "EXECUTOR_WORKER_AGENT",
         "EXECUTOR_MODEL_DISPLAY",
         "EXECUTOR_MODEL_EXECUTION_VALUE",
+        "EXECUTOR_HOST_MODEL_VALUE",
+        "EXECUTOR_RUNNER",
+        "EXECUTOR_DISPATCH_MODE",
         "EXECUTOR_WORKTREE_PATH",
         "EXECUTOR_WORKTREE_BRANCH",
         "EXECUTOR_WORKTREE_BASE_REF",
@@ -1980,8 +2116,7 @@ def _render_lead_prompt_and_snapshot(
     final_report_template: Path,
     prompt_template: Path,
 ) -> str:
-    """compute/default 토큰을 ctx 에 주입한 뒤 final-report 템플릿 사본과 lead 실행
-    프롬프트를 렌더하고, 프롬프트 스냅샷을 기록한 후 prompt_text 를 돌려준다."""
+    """Render lead instructions, then publish one verified lead invocation."""
     # inject populates ctx with compute + default tokens consumed by the lead
     # prompt render below (lead-execution-prompt.md). The final-report
     # template render is effectively a copy (Jinja2 `{{ var }}` syntax does
@@ -2016,14 +2151,48 @@ def _render_lead_prompt_and_snapshot(
         )
     except Exception:  # noqa: BLE001 — advisory artifact; never fail prep over it
         pass
-    lead_prompt_path = instruction_set / "lead-execution-prompt.md"
-    legacy_claude_prompt_path = instruction_set / "claude-execution-prompt.md"
-    render_template_with_ctx(str(prompt_template), str(lead_prompt_path), ctx)
-    prompt_text = lead_prompt_path.read_text(encoding="utf-8")
-    legacy_claude_prompt_path.write_text(prompt_text, encoding="utf-8")
-    Path(ctx["RUN_PROMPT_SNAPSHOT_FILE"]).parent.mkdir(parents=True, exist_ok=True)
-    Path(ctx["RUN_PROMPT_SNAPSHOT_FILE"]).write_text(prompt_text, encoding="utf-8")
-    return prompt_text
+    instructions_path = Path(ctx["LEAD_INSTRUCTIONS_PATH"])
+    render_template_with_ctx(str(prompt_template), str(instructions_path), ctx)
+    assignment = _agent_model_assignment(
+        json.loads(ctx["INVOCATION_ASSIGNMENTS_JSON"])["lead"]
+    )
+    prepared = prepare_agent_invocation(AgentInvocationRequest(
+        invocation_id=(
+            f"{ctx['TASK_TYPE_SEGMENT']}-{ctx['RUN_PROMPTS_SEQ']}-lead"
+        ),
+        worker_id="lead",
+        audience="lead",
+        assignment_ref="lead",
+        purpose=None,
+        assignment=assignment,
+        instruction=AgentInstruction(
+            anchor_lines=(),
+            body=instructions_path.read_text(encoding="utf-8"),
+            source_paths=(
+                AgentInstructionSource(
+                    "project", ctx["LEAD_INSTRUCTIONS_RELATIVE_PATH"]
+                ),
+                AgentInstructionSource("runtime", "prompts/launch.template.md"),
+                AgentInstructionSource(
+                    "runtime", "prompts/lead/okstra-lead-contract.md"
+                ),
+            ),
+        ),
+        project_root=Path(ctx["PROJECT_ROOT"]),
+        run_manifest_path=Path(ctx["RUN_MANIFEST_PATH"]),
+        duty_root=Path(ctx["DUTY_CONTRACT_ROOT"]),
+        prompt_path=Path(ctx["RUN_PROMPT_SNAPSHOT_FILE"]),
+        metadata_path=Path(ctx["LEAD_PROMPT_METADATA_PATH"]),
+        dispatch_kind="lead",
+    ))
+    return prepared.prompt_path.read_text(encoding="utf-8")
+
+
+def _agent_model_assignment(payload: object) -> AgentModelAssignment:
+    try:
+        return agent_model_assignment_from_payload(payload)
+    except AgentInvocationError as exc:
+        raise PrepareError(str(exc)) from exc
 
 
 def _persist_run_inputs(
@@ -2066,7 +2235,7 @@ def _persist_run_inputs(
                 inp.report_writer_provider or "claude",
             ),
             "reportWriterModel": models.rw.display,
-            "executor": models.executor_provider,
+            "executor": models.executor_assignment.provider,
             "relatedTasks": inp.related_tasks_raw,
             "approvedPlanPath": approved_plan_path,
             "clarificationResponsePath": inp.clarification_response_path,
@@ -2083,6 +2252,19 @@ def _persist_run_inputs(
     )
 
 
+def _persist_pre_dispatch_run_manifest(ctx: dict) -> None:
+    """Publish and re-read the complete invocation authority before prompts."""
+    render_run_manifest(ctx["RUN_MANIFEST_PATH"], ctx)
+    manifest = _read_existing_manifest(Path(ctx["RUN_MANIFEST_PATH"]))
+    expected_contract = json.loads(ctx["AGENT_CONTRACT_JSON"])
+    expected_assignments = json.loads(ctx["INVOCATION_ASSIGNMENTS_JSON"])
+    if (
+        manifest.get("agentContract") != expected_contract
+        or manifest.get("invocationAssignments") != expected_assignments
+    ):
+        raise PrepareError("pre-dispatch run manifest is incomplete")
+
+
 def _read_existing_manifest(manifest_path: Path) -> dict:
     if not manifest_path.exists():
         return {}
@@ -2255,6 +2437,98 @@ def _write_bundle_artifacts(
     ctx["FIX_CYCLE_ID"] = _record_fix_cycle_events(inp, ctx)
 
 
+def _prepare_agent_contract(
+    inp: PrepareInputs,
+    ctx: dict,
+    workspace_root: Path,
+    models: _ModelBindings,
+) -> None:
+    source = _duty_catalog_source(workspace_root)
+    destination = Path(ctx["DUTY_CONTRACT_ROOT"])
+    _snapshot_duty_catalog(source, destination)
+    digest = digest_duty_catalog(destination)
+    allowed_audiences = _allowed_agent_audiences(inp, models)
+    contract = {
+        "schemaVersion": 1,
+        "dutyRootPath": ctx["DUTY_CONTRACT_ROOT_RELATIVE_PATH"],
+        "catalogDigest": digest,
+        "invocationReservationRootPath": (
+            ctx["INVOCATION_RESERVATION_ROOT_RELATIVE_PATH"]
+        ),
+        "allowedAudiences": allowed_audiences,
+        "authorizedPaths": {
+            "instructionRoots": [
+                ctx["RUN_PROMPTS_RELATIVE_PATH"],
+                ctx["RUN_STATE_RELATIVE_PATH"],
+            ],
+            "promptRoots": [ctx["RUN_PROMPTS_RELATIVE_PATH"]],
+            "resultRoots": [
+                ctx["WORKER_RESULTS_RELATIVE_PATH"],
+                ctx["RUN_REPORTS_RELATIVE_PATH"],
+            ],
+        },
+    }
+    ctx["DUTY_CATALOG_DIGEST"] = digest
+    ctx["AGENT_CONTRACT_JSON"] = json.dumps(contract, ensure_ascii=False)
+    ctx["INVOCATION_ASSIGNMENTS_JSON"] = json.dumps(
+        models.invocation_assignments,
+        ensure_ascii=False,
+    )
+
+
+def _duty_catalog_source(workspace_root: Path) -> Path:
+    candidates = (
+        workspace_root / "prompts" / "duties",
+        okstra_home() / "prompts" / "duties",
+    )
+    for candidate in candidates:
+        if (candidate / "common.md").is_file():
+            return candidate
+    raise PrepareError("agent duty catalog is missing from the runtime")
+
+
+def _snapshot_duty_catalog(source: Path, destination: Path) -> None:
+    if destination.exists():
+        if digest_duty_catalog(destination) != digest_duty_catalog(source):
+            raise PrepareError("existing run duty snapshot conflicts with runtime catalog")
+        return
+    destination.parent.mkdir(parents=True, exist_ok=True)
+    temp_dir = Path(tempfile.mkdtemp(
+        dir=destination.parent,
+        prefix=f".{destination.name}.",
+        suffix=".tmp",
+    ))
+    try:
+        shutil.copytree(source, temp_dir, dirs_exist_ok=True)
+        os.rename(temp_dir, destination)
+    except FileExistsError as exc:
+        if digest_duty_catalog(destination) != digest_duty_catalog(source):
+            raise PrepareError("run duty snapshot publication conflict") from exc
+    finally:
+        if temp_dir.exists():
+            shutil.rmtree(temp_dir)
+
+
+def _allowed_agent_audiences(
+    inp: PrepareInputs,
+    models: _ModelBindings,
+) -> list[str]:
+    audiences = {"lead", "translator"}
+    if models.worker_assignments:
+        audiences.add("reverification-worker")
+    if any(item.worker_id == "report-writer" for item in models.worker_assignments):
+        audiences.add("report-writer")
+    if inp.task_type == "implementation":
+        audiences.update({"implementation-executor", "implementation-verifier"})
+    elif inp.task_type == "final-verification":
+        audiences.add("acceptance-verifier")
+    else:
+        audiences.add("analysis-worker")
+    if models.critic_choice not in {"", "off"}:
+        audiences.update({"scope-critic", "acceptance-critic"})
+    return sorted(audiences)
+
+
 def _record_run_in_central_index(
     inp: PrepareInputs,
     ctx: dict,
@@ -2351,6 +2625,10 @@ def _model_ctx(models: "_ModelBindings") -> dict[str, str]:
             [assignment.to_payload() for assignment in models.worker_assignments],
             ensure_ascii=False,
         ),
+        "INVOCATION_ASSIGNMENTS_JSON": json.dumps(
+            models.invocation_assignments,
+            ensure_ascii=False,
+        ),
         "CLAUDE_WORKER_MODEL": models.cw.display,
         "CLAUDE_WORKER_MODEL_EXECUTION_VALUE": models.cw.execution,
         "CODEX_WORKER_MODEL": models.co.display,
@@ -2366,11 +2644,22 @@ def _model_ctx(models: "_ModelBindings") -> dict[str, str]:
             ),
             "",
         ),
-        "EXECUTOR_PROVIDER": models.executor_provider,
+        "EXECUTOR_WORKER_ID": models.executor_assignment.worker_id,
+        "EXECUTOR_PROVIDER": models.executor_assignment.provider,
         "EXECUTOR_DISPLAY_NAME": models.executor_display_name,
-        "EXECUTOR_WORKER_AGENT": models.executor_worker_agent,
-        "EXECUTOR_MODEL_DISPLAY": models.executor_model_meta.display,
-        "EXECUTOR_MODEL_EXECUTION_VALUE": models.executor_execution,
+        "EXECUTOR_MODEL_DISPLAY": models.executor_assignment.model_display,
+        "EXECUTOR_MODEL_EXECUTION_VALUE": (
+            models.executor_assignment.model_execution_value
+        ),
+        "EXECUTOR_HOST_MODEL_VALUE": (
+            models.executor_assignment.host_model_value or ""
+        ),
+        "EXECUTOR_RUNNER": models.executor_assignment.runner,
+        "EXECUTOR_DISPATCH_MODE": (
+            "host-native"
+            if models.executor_assignment.runner == "native-session"
+            else "worker-dispatch"
+        ),
         "CRITIC_CHOICE": models.critic_choice,
         "CRITIC_MODEL_EXECUTION_VALUE": models.critic_model_execution,
     }
@@ -2667,18 +2956,21 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
     _write_bundle_artifacts(
         inp, ctx, project_root, lead_runtime, claude_session_id,
     )
+    _prepare_agent_contract(inp, ctx, workspace_root, models)
 
-    # ---- write instruction-set scaffolding + lead prompt ----
+    # ---- write instruction-set scaffolding ----
     instruction_set = _write_instruction_set_sources(
         inp, ctx, profile_content, review_material, assets.host_rules_file
     )
+    # ---- run-inputs persistence ----
+    _persist_run_inputs(inp, ctx, models, selected_reviewers, brief_relative)
+    _persist_pre_dispatch_run_manifest(ctx)
+
+    # ---- lead prompt publication (manifest is now the external authority) ----
     prompt_text = _render_lead_prompt_and_snapshot(
         inp, ctx, instruction_set, final_report_template, prompt_template
     )
 
-    # ---- run-inputs persistence ----
-    _persist_run_inputs(inp, ctx, models, selected_reviewers, brief_relative)
-
     # ---- final status + manifest/discovery renders ----
     _finalize_status_and_render_manifests(
         inp, ctx, task_index_template, forbidden_by_phase
@@ -2997,14 +3289,37 @@ def main(argv: list[str]) -> int:
 
 def _lead_launch_payload(ctx: dict[str, object]) -> dict[str, object]:
     lead_runtime = str(ctx.get("LEAD_RUNTIME", "claude-code"))
-    lead_provider = str(ctx.get("LEAD_PROVIDER", ""))
-    launch = lead_launch_spec(lead_provider)
-    prompt_file = (
-        Path(str(ctx["INSTRUCTION_SET_PATH"])) / "lead-execution-prompt.md"
+    project_root = Path(str(ctx["PROJECT_ROOT"]))
+    run_manifest_path = Path(str(ctx["RUN_MANIFEST_PATH"]))
+    try:
+        manifest = json.loads(run_manifest_path.read_text(encoding="utf-8"))
+        resources = manifest["resources"]
+        assignment = agent_model_assignment_from_payload(
+            manifest["invocationAssignments"]["lead"]
+        )
+        prompt_file = project_root / resources["leadExecutionPromptPath"]
+        metadata_path = project_root / resources["leadPromptMetadataPath"]
+        metadata = json.loads(metadata_path.read_text(encoding="utf-8"))
+        if metadata["prompt"]["path"] != resources["leadExecutionPromptPath"]:
+            raise KeyError("lead prompt resource does not match metadata")
+    except (OSError, json.JSONDecodeError, KeyError, TypeError, AgentInvocationError) as exc:
+        raise PrepareError("lead invocation authority is incomplete") from exc
+    errors = verify_agent_invocation(
+        metadata_path,
+        project_root=project_root,
+        expected_run_manifest_path=run_manifest_path,
+        expected_assignment=assignment,
+        expected_worker_id="lead",
+        expected_assignment_ref="lead",
+        expected_audience="lead",
     )
+    if errors:
+        raise PrepareError("lead invocation verification failed: " + "; ".join(errors))
+    lead_provider = assignment.provider
+    launch = lead_launch_spec(lead_provider)
     launch_argv = lead_launch_argv(
         lead_provider,
-        model=str(ctx["LEAD_MODEL_EXECUTION_VALUE"]),
+        model=assignment.model_execution_value,
         session_id=str(ctx["CLAUDE_SESSION_ID"]),
         prompt=prompt_file.read_text(encoding="utf-8"),
     )
@@ -3014,9 +3329,11 @@ def _lead_launch_payload(ctx: dict[str, object]) -> dict[str, object]:
         "leadProvider": lead_provider,
         "leadExecutable": launch.executable,
         "leadSessionId": ctx["CLAUDE_SESSION_ID"],
-        "leadModelExecutionValue": ctx["LEAD_MODEL_EXECUTION_VALUE"],
-        "projectRoot": ctx["PROJECT_ROOT"],
+        "leadModelExecutionValue": assignment.model_execution_value,
+        "projectRoot": str(project_root),
         "promptFile": str(prompt_file),
+        "runManifestPath": str(run_manifest_path),
+        "leadPromptMetadataPath": str(metadata_path),
         "sandboxWaiverNote": launch.sandbox_waiver_note,
         "launchArgv": launch_argv,
         "launchRequestArgv": launch_argv[launch_prefix_size:],

package/runtime/python/okstra_ctl/session.py

@@ -10,6 +10,8 @@ import os
 import uuid
 from pathlib import Path
 
+from .dispatch_state import DispatchError, mutate_team_state
+
 
 def generate_claude_session_id() -> str:
     """UUIDv4 문자열."""
@@ -105,20 +107,22 @@ def record_observed_lead_session(project_root: Path, team_state_path: Path) -> s
     sid = resolve_lead_session_id_for_run(project_root, team_state_path.parent.parent)
     if not sid:
         return ""
+    def add_observed_session(state: dict) -> bool:
+        lead_ids = state.setdefault("leadSessionIds", [])
+        if sid in lead_ids:
+            return False
+        lead_ids.append(sid)
+        team = f"session-{sid[:8]}"
+        observed = state.setdefault("observedTeamNames", [])
+        if team not in observed:
+            observed.append(team)
+        return True
+
     try:
-        state = json.loads(team_state_path.read_text(encoding="utf-8"))
-    except (OSError, json.JSONDecodeError):
-        return ""
-    lead_ids = state.setdefault("leadSessionIds", [])
-    if sid in lead_ids:
+        changed = mutate_team_state(team_state_path, add_observed_session)
+    except (DispatchError, OSError):
         return ""
-    lead_ids.append(sid)
-    team = f"session-{sid[:8]}"
-    observed = state.setdefault("observedTeamNames", [])
-    if team not in observed:
-        observed.append(team)
-    team_state_path.write_text(json.dumps(state, indent=2), encoding="utf-8")
-    return sid
+    return sid if changed else ""
 
 
 def write_claude_resume_command_file(

package/runtime/python/okstra_ctl/team.py

@@ -19,7 +19,7 @@ from . import tmux
 from .adapters.dispatch import provider_worker_wrappers
 from .adapters.dispatch.cmux import dispatch_port_for_terminal_backend
 from .application.dispatch_assignments import dispatch_assignments
-from .dispatch_state import TEARDOWN_BEFORE_TERMINAL_REASON
+from .dispatch_state import TEARDOWN_BEFORE_TERMINAL_REASON, mutate_team_state
 from .dispatch_core import (
     BACKEND_CMUX_PANE,
     BACKEND_TMUX_PANE,
@@ -253,12 +253,16 @@ def _append_pane(panes: list[dict[str, str]], seen: set[str], pane_id: str, kind
 
 
 def _mark_teardown_errors(team_state_path: Path) -> None:
-    payload = _load_json(team_state_path, "team-state")
-    for record in payload.get("workerDispatches", []):
-        if isinstance(record, dict) and record.get("status") not in _TERMINAL_STATUSES:
-            record["status"] = "error"
-            record["reason"] = TEARDOWN_BEFORE_TERMINAL_REASON
-    _write_json(team_state_path, payload)
+    def mark(payload: dict[str, Any]) -> bool:
+        changed = False
+        for record in payload.get("workerDispatches", []):
+            if isinstance(record, dict) and record.get("status") not in _TERMINAL_STATUSES:
+                record["status"] = "error"
+                record["reason"] = TEARDOWN_BEFORE_TERMINAL_REASON
+                changed = True
+        return changed
+
+    mutate_team_state(team_state_path, mark)
 
 
 def _emit_teardown(as_json: bool, panes: list[dict[str, str]]) -> None:
@@ -310,10 +314,6 @@ def _load_json(path: Path, label: str) -> dict[str, Any]:
     return payload
 
 
-def _write_json(path: Path, payload: Mapping[str, Any]) -> None:
-    path.write_text(json.dumps(payload, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
-
-
 def _resolve_project_path(project_root: Path, value: str | Path) -> Path:
     path = Path(value)
     return path if path.is_absolute() else project_root / path