okstra 0.179.2 → 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
@@ -32,7 +33,11 @@ from okstra_project import project_json_path, upsert_project_json
 from okstra_project.state import slugify
 from . import fix_cycles
 from .analysis_packet import build_analysis_packet
-from .stage_ledger import build_stage_ledger, render_stage_ledger
+from .stage_ledger import (
+    build_stage_ledger,
+    render_stage_ledger,
+    stage_ledger_notice,
+)
 from .analysis_inputs import (
     ANALYSIS_TASK_TYPES,
     AnalysisInputError,
@@ -109,7 +114,10 @@ from .legacy_model_selection import (
     serialize_host_session_context,
 )
 from .model_defaults import ModelDefaultScopes
-from .worker_prompt_policy import ANALYSIS_DUTY_BY_TASK_TYPE
+from .worker_prompt_policy import (
+    ANALYSIS_DUTY_BY_TASK_TYPE,
+    critic_assignment_ref,
+)
 from .models import (
     UnknownProviderError,
     default_model,
@@ -137,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,
@@ -250,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
@@ -664,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
@@ -679,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 을 손으로 깔면 락 파일/모드가 두 경로에서 갈라질 수 있다.
@@ -1526,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
@@ -1562,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:
@@ -1584,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
@@ -1604,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"
         )
 
 
@@ -2117,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):
@@ -2504,6 +2522,7 @@ def _resolve_model_bindings(
         worker_assignments,
         critic_assignment,
         translator_assignment,
+        inp.task_type,
     )
     worker_by_provider = {
         row.provider: row for row in worker_assignments
@@ -2653,6 +2672,7 @@ def _project_model_bindings(
         workers,
         critic_assignment,
         _role_assignment(resolved=translator, role="translator"),
+        inp.task_type,
     )
     worker_by_provider = {row.provider: row for row in workers}
     return _ModelBindings(
@@ -2892,6 +2912,7 @@ def _build_invocation_assignments(
     workers: tuple[RoleAssignment, ...],
     critic: RoleAssignment | None,
     translator: RoleAssignment,
+    task_type: str,
 ) -> dict[str, dict[str, object]]:
     assignments = {"lead": lead.to_model_payload()}
     for assignment in workers:
@@ -2902,8 +2923,11 @@ def _build_invocation_assignments(
             assignment.to_model_payload()
         )
     if critic is not None:
-        assignments["critic/scope"] = critic.to_model_payload()
-        assignments["critic/acceptance"] = critic.to_model_payload()
+        # 한 run 이 도달할 수 있는 critic 은 한 종류다. 둘 다 등록하면 실행될
+        # 수 없는 로스터 행이 남고, `_optional_worker_roles` 가 provider 로만
+        # role 라벨을 만들기 때문에 두 행의 이름이 겹쳐 validate-run 이
+        # `duplicate worker role detected` 로 런을 실패시킨다.
+        assignments[critic_assignment_ref(task_type)] = critic.to_model_payload()
     assignments["translator"] = translator.to_model_payload()
     return assignments
 
@@ -3218,6 +3242,12 @@ def _write_instruction_set_sources(
     render_reference_expectations(
         str(inp.brief_path), str(instruction_set / "reference-expectations.md"), ctx,
     )
+    # 계획 phase 만 원장을 받는다. 원장은 "무엇이 이미 지어졌나" 를 계획 저작
+    # 쪽에 알려 주는 것이므로, 계획을 쓰지 않는 phase 에는 실을 자리가 없다.
+    stage_ledger = (
+        build_stage_ledger(Path(ctx["TASK_MANIFEST_PATH"]).parent)
+        if inp.task_type == "implementation-planning" else None
+    )
     packet = build_analysis_packet(
         task_key=ctx["TASK_KEY"],
         task_type=ctx["TASK_TYPE"],
@@ -3232,11 +3262,8 @@ def _write_instruction_set_sources(
         instruction_set_relative_path=ctx["INSTRUCTION_SET_RELATIVE_PATH"],
         fix_history_text=fix_cycles.packet_summary(
             fix_cycles.read_rows(Path(ctx["TASK_MANIFEST_PATH"]).parent)),
-        stage_ledger_json=(
-            render_stage_ledger(
-                build_stage_ledger(Path(ctx["TASK_MANIFEST_PATH"]).parent))
-            if inp.task_type == "implementation-planning" else ""
-        ),
+        stage_ledger_json=render_stage_ledger(stage_ledger),
+        stage_ledger_notice=stage_ledger_notice(stage_ledger),
     )
     if inp.task_type in ANALYSIS_TASK_TYPES:
         packet += (
@@ -3311,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
@@ -3323,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",
@@ -3476,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 {}
 
 
@@ -3971,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()
@@ -4286,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)
@@ -4332,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")
@@ -4470,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)
@@ -4520,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:
@@ -4560,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,
@@ -4628,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

@@ -1,11 +1,11 @@
-"""Build a task-type-scoped excerpt of the final-report schema.
+"""Build a task-type-scoped excerpt of a versioned final-report schema.
 
-The full schema (``schemas/final-report-v2.0.schema.json``) carries the
+The full schema carries the
 deliverable property blocks for ALL task-types (``errorAnalysis``, the three
 read-only analysis blocks, ``implementationPlanning``, ``releaseHandoff``,
 ``implementation``, and ``finalVerification``) plus a
 ``$defs`` library (~38% of the file) shared across them. A single run only
-authors ONE task-type's data.json, so the report-writer worker only needs
+authors ONE task-type's narrative, so the report-writer worker only needs
 the common structure + its own task-type's block + the ``$defs`` those
 reach.
 
@@ -16,7 +16,7 @@ repo/installed schema (whose `schemas/...` path is not even resolvable
 from inside a consumer project's task bundle).
 
 The excerpt is ADVISORY — a reading aid for the author. Validation always
-runs against the FULL schema via ``final_report_schema.load_schema()``, so
+runs against the matching FULL schema, so
 the excerpt never gates correctness; it only trims what the worker reads.
 """
 from __future__ import annotations
@@ -27,8 +27,10 @@ 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 CURRENT_REPORT_SCHEMA_VERSION, TASK_TYPE_DATA_PROPERTY
+from .report_contract import TASK_TYPE_DATA_PROPERTY
 
 
 _ALL_PER_TYPE_PROPERTIES = frozenset(TASK_TYPE_DATA_PROPERTY.values())
@@ -160,17 +162,22 @@ 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
     cut_from = excerpt_cut_from_version(excerpt)
     if not cut_from or cut_from == installed:
         return None
+    schema_version = (
+        excerpt.get("properties", {})
+        .get("schemaVersion", {})
+        .get("const", "2.0")
+    )
     try:
         fresh = build_schema_excerpt(
-            load_schema_version(CURRENT_REPORT_SCHEMA_VERSION), task_type, installed
+            load_schema_version(str(schema_version)), task_type, installed
         )
     except Exception:  # noqa: BLE001 — an unloadable schema proves no drift
         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