okstra 0.180.0 → 0.183.2

package/runtime/python/okstra_ctl/run.py

@@ -16,6 +16,7 @@ state passing, and are read once at the start.
 from __future__ import annotations
 
 import hashlib
+from argparse import Action, ArgumentError, ArgumentParser, Namespace
 import json
 import os
 import re
@@ -144,6 +145,11 @@ from .agent_invocation import (
     verify_agent_invocation,
 )
 from .report_contract import CURRENT_REPORT_SCHEMA_VERSION
+from .json_boundary import (
+    JsonBoundaryError,
+    load_owned_object,
+    write_owned_object_atomic,
+)
 from .path_resolve import relative_to_project_root, resolve_user_file
 from .render import (
     apply_lead_prompt_defaults,
@@ -257,8 +263,8 @@ def _load_final_report_data_if_present(report_path: Path) -> tuple[Path, dict] |
     if not data_path.is_file():
         return None
     try:
-        data = json.loads(data_path.read_text(encoding="utf-8"))
-    except json.JSONDecodeError as exc:
+        data = load_owned_object(data_path, artifact="approved plan final report")
+    except JsonBoundaryError as exc:
         raise PrepareError(
             f"approved plan data.json is invalid JSON: {data_path}: {exc}"
         ) from exc
@@ -671,7 +677,6 @@ def _record_start(
     """record_start hook 호출. okstra-central.sh 의 bash wrapper 와 같은 동작
     이지만 python 직접 호출이라 환경 변수 의존 없음.
     """
-    import json as _json
     from datetime import datetime, timezone
     from okstra_ctl import record_start
     from .locks import central_lock
@@ -686,11 +691,15 @@ def _record_start(
         (home / f).touch(exist_ok=True)
     state_file = home / "state.json"
     if not state_file.exists():
-        state_file.write_text(_json.dumps({
-            "schemaVersion": "1",
-            "createdAt": datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"),
-            "backfilledAt": None,
-        }, indent=2) + "\n", encoding="utf-8")
+        write_owned_object_atomic(
+            state_file,
+            {
+                "schemaVersion": "1",
+                "createdAt": datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"),
+                "backfilledAt": None,
+            },
+            artifact="global state",
+        )
         os.chmod(state_file, 0o600)
     # 중앙 인덱스 락은 reconcile.py 와 공유하는 central_lock 단일 기준점을 쓴다.
     # 직접 flock 을 손으로 깔면 락 파일/모드가 두 경로에서 갈라질 수 있다.
@@ -1533,8 +1542,8 @@ def validate_project_qa_commands(task_type: str, project_root: Path) -> None:
     if not project_json.is_file():
         return
     try:
-        project_meta = json.loads(project_json.read_text())
-    except (OSError, json.JSONDecodeError) as exc:
+        project_meta = load_owned_object(project_json, artifact="project config")
+    except (OSError, JsonBoundaryError) as exc:
         raise PrepareError(
             f"project.json read failed at {project_json}: {exc}"
         ) from exc
@@ -1569,11 +1578,13 @@ def _apply_qa_waiver_if_requested(inp: "PrepareInputs", project_root: Path) -> N
     ):
         if not manifest_path.is_file():
             raise PrepareError(f"--qa-waiver: conformance manifest not found at {manifest_path}")
-        manifest = json.loads(manifest_path.read_text())
+        manifest = load_owned_object(manifest_path, artifact="conformance manifest")
         when = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
         if not apply_qa_waiver(manifest, stage_key, reason, at=when):
             raise PrepareError(f"--qa-waiver: stageKey {stage_key!r} not in manifest {manifest_path}")
-        manifest_path.write_text(json.dumps(manifest, indent=2, ensure_ascii=False) + "\n")
+        write_owned_object_atomic(
+            manifest_path, manifest, artifact="conformance manifest"
+        )
 
 
 def _clear_stale_stage_waiver(inp: "PrepareInputs", project_root: Path, stage: int) -> None:
@@ -1591,7 +1602,7 @@ def _clear_stale_stage_waiver(inp: "PrepareInputs", project_root: Path, stage: i
     )
     if not manifest_path.is_file():
         return
-    manifest = json.loads(manifest_path.read_text())
+    manifest = load_owned_object(manifest_path, artifact="conformance manifest")
     entries = manifest.get("entries") if isinstance(manifest, dict) else None
     if not isinstance(entries, list):
         return
@@ -1611,8 +1622,8 @@ def _clear_stale_stage_waiver(inp: "PrepareInputs", project_root: Path, stage: i
         if parsed is not None and parsed[0] == stage_key:
             return  # user intentionally waived this stage for this run
     if clear_qa_waiver(manifest, stage_key):
-        manifest_path.write_text(
-            json.dumps(manifest, indent=2, ensure_ascii=False) + "\n"
+        write_owned_object_atomic(
+            manifest_path, manifest, artifact="conformance manifest"
         )
 
 
@@ -2124,8 +2135,8 @@ def _read_model_defaults(path: Path) -> dict[str, tuple[str, ...]]:
     if not path.is_file():
         return {}
     try:
-        payload = json.loads(path.read_text(encoding="utf-8"))
-    except (OSError, json.JSONDecodeError) as exc:
+        payload = load_owned_object(path, artifact="model defaults config")
+    except (OSError, JsonBoundaryError) as exc:
         raise PrepareError(f"model defaults file is invalid: {path}: {exc}") from exc
     raw_defaults = payload.get("modelDefaults", {}) if isinstance(payload, dict) else {}
     if not isinstance(raw_defaults, dict):
@@ -3327,9 +3338,10 @@ def _render_lead_prompt_and_snapshot(
             inp.task_type,
             installed_version(),
         )
-        Path(ctx["FINAL_REPORT_SCHEMA_PATH"]).write_text(
-            json.dumps(_excerpt, indent=2, ensure_ascii=False) + "\n",
-            encoding="utf-8",
+        write_owned_object_atomic(
+            Path(ctx["FINAL_REPORT_SCHEMA_PATH"]),
+            _excerpt,
+            artifact="final report schema excerpt",
         )
     except Exception:  # noqa: BLE001 — advisory artifact; never fail prep over it
         pass
@@ -3339,7 +3351,9 @@ def _render_lead_prompt_and_snapshot(
         json.loads(ctx["INVOCATION_ASSIGNMENTS_JSON"])["lead"]
     )
     identity = invocation_execution_identity_from_manifest(
-        json.loads(Path(ctx["RUN_MANIFEST_PATH"]).read_text(encoding="utf-8")),
+        load_owned_object(
+            Path(ctx["RUN_MANIFEST_PATH"]), artifact="run manifest"
+        ),
         assignment=assignment,
         assignment_ref="lead",
         duty_id="lead",
@@ -3492,8 +3506,8 @@ def _read_existing_manifest(manifest_path: Path) -> dict:
     if not manifest_path.exists():
         return {}
     try:
-        return json.loads(manifest_path.read_text(encoding="utf-8"))
-    except (OSError, json.JSONDecodeError):
+        return load_owned_object(manifest_path, artifact="run manifest")
+    except (OSError, JsonBoundaryError):
         return {}
 
 
@@ -3987,7 +4001,7 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
     try:
         json.loads(runtime_resolution_json or "{}")
     except json.JSONDecodeError as exc:
-        raise PrepareError(f"invalid --runtime-resolution-json: {exc}") from exc
+        raise PrepareError(f"invalid runtime resolution data: {exc}") from exc
     # Probed once here and reused below, so the gate and the manifest cannot
     # disagree about which backend this run is on.
     terminal_backend = detect_terminal_backend()
@@ -4302,11 +4316,77 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
     )
 
 
+class _StoreRuntimeSingleton(Action):
+    def __call__(
+        self,
+        parser: ArgumentParser,
+        namespace: Namespace,
+        values: object,
+        option_string: str | None = None,
+    ) -> None:
+        seen = getattr(namespace, "_runtime_singletons_seen", frozenset())
+        if self.dest in seen:
+            raise ArgumentError(
+                self, f"{option_string} may be supplied only once"
+            )
+        setattr(namespace, self.dest, True if self.nargs == 0 else values)
+        setattr(namespace, "_runtime_singletons_seen", seen | {self.dest})
+
+
+def _add_runtime_resolution_arguments(parser: ArgumentParser) -> None:
+    runtime_ids = (*default_host_registry().ids(), "all")
+    parser.add_argument(
+        "--lead-runtime",
+        action=_StoreRuntimeSingleton,
+        default="claude-code",
+        choices=runtime_ids,
+        dest="lead_runtime",
+        help=(
+            "Lead runtime adapter. Default: claude-code. `codex` renders "
+            "Codex CLI artifact bundles; `antigravity` renders Antigravity CLI "
+            "artifact bundles; `external` renders neutral bootstrap bundles for "
+            "manifest inspection until a dispatch backend is enabled."
+        ),
+    )
+    parser.add_argument(
+        "--lead-runtime-request", action=_StoreRuntimeSingleton, default=""
+    )
+    parser.add_argument(
+        "--runtime-resolution-launch-mode",
+        action=_StoreRuntimeSingleton,
+        choices=("lead", "team", "catalog"),
+        default="",
+    )
+    parser.add_argument(
+        "--runtime-resolution-install-target", action="append", default=[]
+    )
+    for flag in (
+        "--runtime-resolution-host",
+        "--runtime-resolution-reason",
+        "--runtime-resolution-fallback-from",
+    ):
+        parser.add_argument(flag, action=_StoreRuntimeSingleton, default="")
+    parser.add_argument(
+        "--runtime-resolution-confidence",
+        action=_StoreRuntimeSingleton,
+        choices=("none", "low", "medium", "high"),
+        default="",
+    )
+    parser.add_argument("--runtime-resolution-warning", action="append", default=[])
+    parser.add_argument(
+        "--runtime-resolution-catalog-hosts-present",
+        action=_StoreRuntimeSingleton,
+        nargs=0,
+        default=False,
+    )
+    parser.add_argument(
+        "--runtime-resolution-catalog-host-id", action="append", default=[]
+    )
+
+
 def build_prepare_argument_parser():
     """Build the shared flat-argument parser used by public prepare shims."""
-    import argparse
-
-    p = argparse.ArgumentParser()
+    p = ArgumentParser()
     p.add_argument("--workspace-root", required=True)
     p.add_argument("--project-root", required=True)
     p.add_argument("--project-id", required=True)
@@ -4348,30 +4428,7 @@ def build_prepare_argument_parser():
     p.add_argument("--worker-model", default="", dest="worker_models_raw")
     p.add_argument("--report-writer-provider", default="")
     p.add_argument("--report-writer-model", default="")
-    p.add_argument(
-        "--lead-runtime",
-        default="claude-code",
-        choices=list(default_host_registry().ids()),
-        dest="lead_runtime",
-        help=(
-            "Lead runtime adapter. Default: claude-code. `codex` renders "
-            "Codex CLI artifact bundles; `antigravity` renders Antigravity CLI "
-            "artifact bundles; `external` renders neutral bootstrap bundles for "
-            "manifest inspection until a dispatch backend is enabled."
-        ),
-    )
-    p.add_argument(
-        "--lead-runtime-request",
-        default="",
-        dest="lead_runtime_request",
-        help="Original lead runtime request before Node-side resolution, e.g. auto.",
-    )
-    p.add_argument(
-        "--runtime-resolution-json",
-        default="",
-        dest="runtime_resolution_json",
-        help="Node-side runtime resolution payload serialized as JSON.",
-    )
+    _add_runtime_resolution_arguments(p)
     p.add_argument("--executor", default="")
     p.add_argument("--critic", default="")
     p.add_argument("--related-tasks", default="", dest="related_tasks_raw")
@@ -4486,6 +4543,51 @@ def build_prepare_argument_parser():
     return p
 
 
+def _runtime_resolution_json_from_args(args: Namespace) -> str:
+    values = {
+        "launch mode": args.runtime_resolution_launch_mode,
+        "host": args.runtime_resolution_host,
+        "confidence": args.runtime_resolution_confidence,
+        "reason": args.runtime_resolution_reason,
+    }
+    optional_values = (
+        args.runtime_resolution_install_target,
+        args.runtime_resolution_fallback_from,
+        args.runtime_resolution_warning,
+        args.runtime_resolution_catalog_hosts_present,
+        args.runtime_resolution_catalog_host_id,
+    )
+    if not any(values.values()) and not any(optional_values):
+        return "{}"
+    missing = [name for name, value in values.items() if not value]
+    if missing:
+        raise PrepareError(
+            "incomplete runtime resolution arguments: " + ", ".join(missing)
+        )
+    if (
+        args.runtime_resolution_catalog_host_id
+        and not args.runtime_resolution_catalog_hosts_present
+    ):
+        raise PrepareError(
+            "runtime resolution catalog host IDs require the presence marker"
+        )
+    payload: dict[str, object] = {
+        "ok": True,
+        "requestedRuntime": args.lead_runtime_request or args.lead_runtime,
+        "resolvedRuntime": args.lead_runtime,
+        "launchMode": args.runtime_resolution_launch_mode,
+        "installTargets": args.runtime_resolution_install_target,
+        "host": args.runtime_resolution_host,
+        "confidence": args.runtime_resolution_confidence,
+        "reason": args.runtime_resolution_reason,
+        "fallbackFrom": args.runtime_resolution_fallback_from or None,
+        "warnings": args.runtime_resolution_warning,
+    }
+    if args.runtime_resolution_catalog_hosts_present:
+        payload["catalogHostIds"] = args.runtime_resolution_catalog_host_id
+    return json.dumps(payload, ensure_ascii=False)
+
+
 def main(argv: list[str]) -> int:
     """Parse one public prepare invocation and emit its rendered bundle."""
     args = build_prepare_argument_parser().parse_args(argv)
@@ -4536,7 +4638,8 @@ def main(argv: list[str]) -> int:
         host_session_context = deserialize_host_session_context(
             args.host_session_context_json
         )
-    except ModelSelectionInputError as exc:
+        runtime_resolution_json = _runtime_resolution_json_from_args(args)
+    except (ModelSelectionInputError, PrepareError) as exc:
         print(str(exc), file=__import__("sys").stderr)
         return 1
     if not args.host_session_context_json:
@@ -4576,7 +4679,7 @@ def main(argv: list[str]) -> int:
         report_writer_model=args.report_writer_model,
         lead_runtime=args.lead_runtime,
         lead_runtime_request=args.lead_runtime_request,
-        runtime_resolution_json=args.runtime_resolution_json,
+        runtime_resolution_json=runtime_resolution_json,
         executor=args.executor,
         critic=args.critic,
         related_tasks_raw=args.related_tasks_raw,
@@ -4644,17 +4747,17 @@ def _lead_launch_payload(ctx: dict[str, object]) -> dict[str, object]:
     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"))
+        manifest = load_owned_object(run_manifest_path, artifact="run manifest")
         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"))
+        metadata = load_owned_object(metadata_path, artifact="lead prompt metadata")
         if metadata["prompt"]["path"] != resources["leadExecutionPromptPath"]:
             raise KeyError("lead prompt resource does not match metadata")
-    except (OSError, json.JSONDecodeError, KeyError, TypeError, AgentInvocationError) as exc:
+    except (OSError, JsonBoundaryError, KeyError, TypeError, AgentInvocationError) as exc:
         raise PrepareError("lead invocation authority is incomplete") from exc
     errors = verify_agent_invocation(
         metadata_path,

package/runtime/python/okstra_ctl/run_audit.py

@@ -19,6 +19,7 @@ from okstra_ctl.paths import okstra_home, resolve_under_root
 from okstra_ctl.reconcile import NON_TERMINAL_RECENT_STATUSES
 from okstra_ctl.task_target import project_rel
 from okstra_ctl.workflow import PHASE_SEQUENCE
+from okstra_ctl.json_boundary import JsonBoundaryError, load_owned_object
 
 # 불변식 이름은 여기서만 정의한다. `INVARIANTS` 와 방출부가 같은 상수를 봐야,
 # 이름을 하나 더할 때 한쪽만 고치고도 스위트가 green 인 상태가 생기지 않는다 —
@@ -74,8 +75,8 @@ _RECORDED_WORKER_STATUSES = frozenset(
 
 def _load_json(path: Path) -> dict:
     try:
-        loaded = json.loads(path.read_text(encoding="utf-8"))
-    except (OSError, json.JSONDecodeError):
+        loaded = load_owned_object(path, artifact="run audit input")
+    except JsonBoundaryError:
         return {}
     return loaded if isinstance(loaded, dict) else {}
 

package/runtime/python/okstra_ctl/run_context.py

@@ -26,6 +26,7 @@ from typing import Iterator, Optional
 from okstra_project.dirs import okstra_home
 
 from .path_hints import compact_run_context, hydrate_run_context
+from .json_boundary import JsonBoundaryError, load_owned_object, write_owned_object_atomic
 from .paths import compute_run_paths, task_runs_dir
 
 
@@ -66,8 +67,8 @@ def latest_run_inputs(
         return {}
     candidates.sort(key=lambda x: -x[0])
     try:
-        data = json.loads(candidates[0][1].read_text(encoding="utf-8"))
-    except (OSError, json.JSONDecodeError):
+        data = load_owned_object(candidates[0][1], artifact="run context")
+    except JsonBoundaryError:
         return {}
     inputs = data.get("inputs")
     return inputs if isinstance(inputs, dict) else {}
@@ -129,11 +130,7 @@ def consumers_mutex(plan_run_root: Path) -> Iterator[None]:
 
 
 def _atomic_write_json(path: Path, payload: dict) -> None:
-    path.parent.mkdir(parents=True, exist_ok=True)
-    tmp = path.with_suffix(path.suffix + ".tmp")
-    tmp.write_text(json.dumps(payload, indent=2, ensure_ascii=False) + "\n",
-                   encoding="utf-8")
-    os.replace(tmp, path)
+    write_owned_object_atomic(path, payload, artifact="run context")
 
 
 def _run_context_filename(task_type_segment: str, seq: str) -> str:
@@ -240,7 +237,7 @@ def read_run_context(run_manifests_dir: Path, task_type_segment: str,
     path = Path(run_manifests_dir) / _run_context_filename(task_type_segment, seq)
     if not path.is_file():
         return None
-    payload = json.loads(path.read_text(encoding="utf-8"))
+    payload = load_owned_object(path, artifact="run context")
     context = hydrate_run_context(payload)
     analysis = payload.get("analysis")
     if isinstance(analysis, dict):
@@ -268,4 +265,4 @@ def read_run_inputs(run_manifests_dir: Path, task_type_segment: str,
     path = Path(run_manifests_dir) / _run_inputs_filename(task_type_segment, seq)
     if not path.is_file():
         return None
-    return json.loads(path.read_text(encoding="utf-8"))
+    return load_owned_object(path, artifact="run inputs")

package/runtime/python/okstra_ctl/run_index_row.py

@@ -8,14 +8,12 @@ slim row 에 raw 로 보존한다 — taskGroup/taskId 와 동일한 이유다.
 """
 from __future__ import annotations
 
-import json
-import os
 from pathlib import Path
 from typing import Optional
 
 from .ids import build_run_id, parse_run_id
 from .invocation import invocation_path
-from .jsonl import read_jsonl
+from .jsonl import read_jsonl, rewrite_jsonl
 
 DERIVED_FIELDS = ("taskType", "runSeq", "taskKey", "invocationFile")
 
@@ -103,11 +101,7 @@ def _rewrite_slim(path: Path) -> int:
     rows = read_jsonl(path)
     if not rows:
         return 0
-    tmp = path.with_suffix(path.suffix + ".tmp")
-    with tmp.open("w") as f:
-        for r in rows:
-            f.write(json.dumps(slim_run_row(r), separators=(",", ":")) + "\n")
-    os.replace(tmp, path)
+    rewrite_jsonl(path, [slim_run_row(row) for row in rows])
     return len(rows)
 
 

package/runtime/python/okstra_ctl/schedule_semantics.py

@@ -9,6 +9,7 @@ from pathlib import Path
 from typing import Any
 
 from .md_table import is_separator_row, split_pipe_row
+from .json_boundary import external_user_json_source, load_external_json
 
 
 _ROOT_FIELDS = {"schemaVersion", "tasks"}
@@ -404,8 +405,10 @@ def _strict_json_object(pairs: list[tuple[str, Any]]) -> dict[str, Any]:
 
 
 def load_schedule_selection(path: Path) -> tuple[SelectionTask, ...]:
-    payload = json.loads(
-        path.read_text(encoding="utf-8"),
+    # 외부 입력: okstra-schedule 사용자가 선택한 작업 집합 문서다.
+    payload = load_external_json(
+        external_user_json_source(path),
+        artifact="schedule selection",
         object_pairs_hook=_strict_json_object,
     )
     root = _require_object(payload, "selection")

package/runtime/python/okstra_ctl/schema_excerpt.py

@@ -27,6 +27,8 @@ from collections.abc import Sequence
 from dataclasses import dataclass
 from pathlib import Path
 
+from .json_boundary import JsonBoundaryError, load_owned_object
+
 from .final_report_schema import load_schema_version
 from .report_contract import TASK_TYPE_DATA_PROPERTY
 
@@ -160,8 +162,8 @@ def excerpt_contract_skew(
     if not installed:
         return None
     try:
-        excerpt = json.loads(excerpt_path.read_text(encoding="utf-8"))
-    except (OSError, json.JSONDecodeError):
+        excerpt = load_owned_object(excerpt_path, artifact="schema excerpt")
+    except JsonBoundaryError:
         return None
     if not isinstance(excerpt, dict):
         return None

package/runtime/python/okstra_ctl/session_transcript.py

@@ -50,13 +50,39 @@ class SessionTranscript:
         결론과 okstra 자신의 기록이 그렇다. 잘린 도구 에코는 세부를 잃지만
         잘린 결론은 사후 분석 전체를 잃는다.
         """
+        row = self._row(speaker, line)
+        self._show(row)
+        self._keep(row, capped=capped)
+
+    def write_event(
+        self, speaker: str, *, screen: list[str], archive: list[str]
+    ) -> None:
+        """한 이벤트의 두 투영을 각자의 목적지로 보낸다.
+
+        화면은 요약을 받고 기록은 본문까지 받는다. 둘 중 하나를 골라 양쪽에
+        쓰던 동안에는 pane 이 붙은 run 의 기록이 화면 투영으로 대체됐다 —
+        도구 결과가 `← done (23 bytes)` 한 줄로만 남고 그 23 바이트가 무엇이
+        었는지는 파일 어디에도 없었다. antigravity `view_file` 은 파일 내용이
+        아니라 `721 lines, 114306 bytes` 같은 요약을 돌려주므로, 본문이 빠진
+        기록에서는 46KB 를 읽은 호출과 잘린 호출이 같은 줄로 보인다.
+        """
+        for line in screen:
+            self._show(self._row(speaker, line))
+        for line in archive:
+            self._keep(self._row(speaker, line), capped=True)
+
+    def _row(self, speaker: str, line: str) -> str:
         # 패딩이 본문 앞 공백을 겸한다. 뒤에 공백을 한 칸 더 넣으면
         # `[worker:grok]`(13칸) 줄이 두 칸이 되고 `[okstra]` 정렬이 깨진다.
         label = f"[{speaker}]".ljust(_SPEAKER_WIDTH)
-        row = f"{self._clock()} {label}{line}".rstrip()
+        return f"{self._clock()} {label}{line}".rstrip()
+
+    def _show(self, row: str) -> None:
         # 화면은 상한과 무관하다. 사람이 보고 있는 것을 잘라 낼 이유가 없다.
         if self._live:
             print(row, flush=True)
+
+    def _keep(self, row: str, *, capped: bool) -> None:
         if not capped:
             self._append(row)
             return