okstra 0.179.2 → 0.183.2

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

@@ -13,12 +13,14 @@ CLI 는 갈라 읽어야 한다.
 from __future__ import annotations
 
 import json
-from dataclasses import dataclass
+from dataclasses import dataclass, field
 from pathlib import Path
 from typing import Any, Callable, Literal, Mapping, Protocol, runtime_checkable
 
 from .worker_stream import (
     Normalise,
+    StreamEvent,
+    Text,
     final_text,
     format_live,
     format_log,
@@ -33,16 +35,22 @@ WORKER = "worker"
 
 
 class TranscriptWriter(Protocol):
-    """세션 기록에 한 줄을 남긴다. 화면 출력도 이 구현이 함께 맡는다."""
+    """세션 기록에 남긴다. 화면 출력도 이 구현이 함께 맡는다."""
 
     def write(self, speaker: str, line: str) -> None: ...
 
+    def write_event(
+        self, speaker: str, *, screen: list[str], archive: list[str]
+    ) -> None: ...
+
 
 @runtime_checkable
 class Presentation(Protocol):
     def merges_stderr(self) -> bool: ...
 
-    def sinks(self, writer: TranscriptWriter, live: bool) -> tuple[SinkSpec, ...]: ...
+    def sinks(self, writer: TranscriptWriter) -> tuple[SinkSpec, ...]: ...
+
+    def flush(self, writer: TranscriptWriter) -> None: ...
 
 
 @dataclass(frozen=True)
@@ -58,13 +66,16 @@ class MergedText:
     def merges_stderr(self) -> bool:
         return True
 
-    def sinks(self, writer: TranscriptWriter, live: bool) -> tuple[SinkSpec, ...]:
+    def sinks(self, writer: TranscriptWriter) -> tuple[SinkSpec, ...]:
         def emit(line: str) -> str | None:
             writer.write(WORKER, line)
             return line
 
         return (("stdout", emit),)
 
+    def flush(self, writer: TranscriptWriter) -> None:
+        return
+
 
 @dataclass(frozen=True)
 class SplitText:
@@ -77,7 +88,7 @@ class SplitText:
     def merges_stderr(self) -> bool:
         return False
 
-    def sinks(self, writer: TranscriptWriter, live: bool) -> tuple[SinkSpec, ...]:
+    def sinks(self, writer: TranscriptWriter) -> tuple[SinkSpec, ...]:
         def result(line: str) -> str | None:
             writer.write(WORKER, line)
             return line
@@ -88,6 +99,9 @@ class SplitText:
 
         return (("stdout", result), ("stderr", progress))
 
+    def flush(self, writer: TranscriptWriter) -> None:
+        return
+
 
 @dataclass(frozen=True)
 class JsonEvents:
@@ -99,11 +113,16 @@ class JsonEvents:
 
     normalise: Normalise
     observe: ObserveServedModel
+    # 어떤 CLI 의 streaming-json 은 문장이 아니라 토큰을 한 줄씩 보낸다. 붙이지
+    # 않으면 pane 이 한 글자 한 줄이 된다. 기본은 끄고, 그런 CLI 의 어댑터가 켠다 —
+    # 어느 CLI 가 그런지는 이 계층이 알 필요도, 알아서도 안 되는 사실이다.
+    join_adjacent_text: bool = False
+    _pending_text: list[str] = field(default_factory=list, repr=False, compare=False)
 
     def merges_stderr(self) -> bool:
         return True
 
-    def sinks(self, writer: TranscriptWriter, live: bool) -> tuple[SinkSpec, ...]:
+    def sinks(self, writer: TranscriptWriter) -> tuple[SinkSpec, ...]:
         def emit(line: str) -> str | None:
             stripped = line.strip()
             if not stripped:
@@ -113,6 +132,7 @@ class JsonEvents:
             except ValueError:
                 # 이벤트가 아니다. CLI 자신의 오류 텍스트가 이 스트림으로
                 # 오므로 삼키면 아무도 못 본다.
+                self._publish_text(writer)
                 writer.write(WORKER, stripped)
                 return None
             if not isinstance(event, dict):
@@ -120,9 +140,50 @@ class JsonEvents:
             self.observe(event)
             closing: str | None = None
             for entry in self.normalise(event):
-                for row in (format_live(entry) if live else format_log(entry)):
-                    writer.write(WORKER, row)
-                closing = final_text(entry) or closing
+                closing = self._write_entry(writer, entry) or closing
             return closing
 
         return (("stdout", emit),)
+
+    def flush(self, writer: TranscriptWriter) -> None:
+        self._publish_text(writer)
+
+    def _write_entry(
+        self, writer: TranscriptWriter, entry: StreamEvent
+    ) -> str | None:
+        if isinstance(entry, Text) and self.join_adjacent_text:
+            self._pending_text.append(entry.body)
+            self._publish_complete_lines(writer)
+            return None
+        self._publish_text(writer)
+        # 두 투영을 고르는 것이 아니라 둘 다 보낸다. 화면은 요약, 기록은
+        # 본문까지. 고르던 동안에는 pane 이 붙은 run 의 기록에서 도구 결과
+        # 본문이 통째로 사라졌다.
+        writer.write_event(
+            WORKER,
+            screen=format_live(entry),
+            archive=format_log(entry),
+        )
+        return final_text(entry)
+
+    def _publish_complete_lines(self, writer: TranscriptWriter) -> None:
+        combined = "".join(self._pending_text)
+        if "\n" not in combined:
+            return
+        *complete, remainder = combined.split("\n")
+        self._pending_text.clear()
+        if remainder:
+            self._pending_text.append(remainder)
+        self._write_text_rows(writer, "\n".join(complete))
+
+    def _publish_text(self, writer: TranscriptWriter) -> None:
+        combined = "".join(self._pending_text)
+        self._pending_text.clear()
+        self._write_text_rows(writer, combined)
+
+    def _write_text_rows(self, writer: TranscriptWriter, body: str) -> None:
+        event = Text(body=body)
+        screen = format_live(event)
+        archive = format_log(event)
+        if screen or archive:
+            writer.write_event(WORKER, screen=screen, archive=archive)

package/runtime/python/okstra_ctl/entrypoints/hosts.py

@@ -16,6 +16,7 @@ from ..agent_invocation import (
     verify_agent_invocation,
 )
 from ..dispatch_state import DispatchError, record_verified_agent_dispatch
+from ..json_boundary import JsonBoundaryError, load_owned_object
 
 from ..application.start_run import start_run
 from ..application.resume_run import resume_run
@@ -108,7 +109,13 @@ def _build_parser() -> argparse.ArgumentParser:
     resolve = commands.add_parser("resolve")
     resolve.add_argument("--requested", required=True)
     resolve.add_argument("--command", dest="runtime_command", required=True)
-    resolve.add_argument("--context-json", required=True)
+    resolve.add_argument("--environment-host", default="")
+    resolve.add_argument(
+        "--capability",
+        action="append",
+        choices=("claude-skill-handoff", "tmux"),
+        default=[],
+    )
     launch = commands.add_parser("launch-plan")
     _add_session_plan_args(launch)
     launch.add_argument("--prepared-launch-json", default="")
@@ -152,7 +159,9 @@ def _command_payload(
     if args.command == "catalog":
         return catalog_payload(registry)
     if args.command == "resolve":
-        context = _parse_resolution_context(args.context_json)
+        context = HostResolutionContext(
+            args.environment_host, frozenset(args.capability)
+        )
         try:
             return resolve_payload(registry, args.requested, context)
         except HostUnavailable as exc:
@@ -215,31 +224,6 @@ def _probe_paths(project_root: str, home_dir: str):
                 os.environ[key] = value
 
 
-def _parse_resolution_context(raw_context: str) -> HostResolutionContext:
-    try:
-        raw = json.loads(raw_context)
-    except json.JSONDecodeError as exc:
-        raise ValueError("invalid host resolution context JSON") from exc
-    if not isinstance(raw, dict):
-        raise ValueError("invalid host resolution context JSON")
-    env = raw.get("env", {})
-    capabilities = raw.get("capabilities", {})
-    if not isinstance(env, dict) or not isinstance(capabilities, dict):
-        raise ValueError("invalid host resolution context JSON")
-    explicit_env_host = env.get("OKSTRA_RUNTIME_HOST", "")
-    if not isinstance(explicit_env_host, str):
-        raise ValueError("invalid host resolution context JSON")
-    signals = frozenset(
-        signal
-        for capability, signal in (
-            ("claudeSkillHandoff", "claude-skill-handoff"),
-            ("tmuxAvailable", "tmux"),
-        )
-        if capabilities.get(capability) is True
-    )
-    return HostResolutionContext(explicit_env_host, signals)
-
-
 def _unclaimed_host_message(registry: HostAdapterRegistry, command: str) -> str:
     runtime_flag = "--runtime" if command in {
         "install", "ensure-installed", "doctor"
@@ -336,17 +320,19 @@ def _launch_request(
     run_manifest_path = Path(run_manifest_value)
     metadata_path = Path(metadata_value)
     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_path = root / resources["leadExecutionPromptPath"]
         canonical_metadata = root / resources["leadPromptMetadataPath"]
-        metadata = json.loads(canonical_metadata.read_text(encoding="utf-8"))
+        metadata = load_owned_object(
+            canonical_metadata, 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 ValueError("lead invocation authority is incomplete") from exc
     if metadata_path.resolve(strict=False) != canonical_metadata.resolve(strict=False):
         raise ValueError("prepared lead metadata does not match run manifest")

package/runtime/python/okstra_ctl/error_log_write.py

@@ -15,6 +15,7 @@ import os
 from pathlib import Path
 
 from .models import provider_ids
+from .json_boundary import external_error_sidecar_source, load_external_json
 
 STDERR_EXCERPT_MAX_BYTES = 2048
 TRUNCATION_SUFFIX = "...[truncated]"
@@ -240,6 +241,31 @@ def append_observed(
     return rec
 
 
+def _worker_sidecar_record(entry, *, recorded_at, task_key, agent, agent_role, model, identity):
+    error_type = entry.get("errorType")
+    if error_type not in ALLOWED_ERROR_TYPES:
+        raise ValueError(f"invalid errorType in sidecar: {error_type!r}")
+    rec = {
+        "ts": entry.get("ts"), "recordedAt": recorded_at,
+        "taskKey": task_key,
+        "phase": str(entry.get("phase")) if entry.get("phase") is not None else None,
+        "agent": agent, "agentRole": agent_role, "model": model,
+        "source": "worker-reported", "errorType": error_type,
+        "command": entry.get("command"), "commandKind": entry.get("commandKind"),
+        "exitCode": entry.get("exitCode"), "durationMs": entry.get("durationMs"),
+        "message": entry.get("message"),
+        "stderrExcerpt": truncate_stderr(entry.get("stderrExcerpt")),
+        "context": normalize_cause_context(
+            entry.get("context"), message=entry.get("message")
+        ),
+    }
+    from okstra_ctl.execution_identity import stored_identity
+
+    rec.update(stored_identity(identity))
+    rec.update(stored_identity(entry))
+    return rec
+
+
 def dump_from_worker_sidecar(
     *,
     sidecar_path,
@@ -276,42 +302,21 @@ def dump_from_worker_sidecar(
     p = Path(sidecar_path)
     if not p.exists():
         return 0
-    payload = json.loads(p.read_text())
+    # 외부 입력: 레거시 자동화가 제공하는 오류 sidecar 호환 경로다.
+    payload = load_external_json(
+        external_error_sidecar_source(p),
+        artifact="legacy error sidecar",
+    )
     schema = payload.get("schemaVersion")
     if schema not in SUPPORTED_SIDECAR_SCHEMA_VERSIONS:
         raise ValueError(f"unsupported sidecar schemaVersion: {schema!r}")
-    entries = payload.get("errors") or []
     recorded_at = _iso(now or _now_utc())
     count = 0
-    for e in entries:
-        et = e.get("errorType")
-        if et not in ALLOWED_ERROR_TYPES:
-            raise ValueError(f"invalid errorType in sidecar: {et!r}")
-        entry_context = normalize_cause_context(
-            e.get("context"), message=e.get("message")
+    for entry in payload.get("errors") or []:
+        rec = _worker_sidecar_record(
+            entry, recorded_at=recorded_at, task_key=task_key, agent=agent,
+            agent_role=agent_role, model=model, identity=identity,
         )
-        rec = {
-            "ts": e.get("ts"),
-            "recordedAt": recorded_at,
-            "taskKey": task_key,
-            "phase": str(e.get("phase")) if e.get("phase") is not None else None,
-            "agent": agent,
-            "agentRole": agent_role,
-            "model": model,
-            "source": "worker-reported",
-            "errorType": et,
-            "command": e.get("command"),
-            "commandKind": e.get("commandKind"),
-            "exitCode": e.get("exitCode"),
-            "durationMs": e.get("durationMs"),
-            "message": e.get("message"),
-            "stderrExcerpt": truncate_stderr(e.get("stderrExcerpt")),
-            "context": entry_context,
-        }
-        from okstra_ctl.execution_identity import stored_identity
-
-        rec.update(stored_identity(identity))
-        rec.update(stored_identity(e))
         append_jsonl_line(out_path, rec)
         count += 1
     return count

package/runtime/python/okstra_ctl/error_report.py

@@ -12,6 +12,8 @@ import json
 import sys
 from pathlib import Path
 
+from .fixed_text import line
+
 from okstra_ctl.task_target import resolve_task_root, project_rel
 from okstra_project import read_task_key
 from okstra_ctl.error_log_core import (
@@ -187,6 +189,27 @@ def build_and_write(task_root: Path, project_root: Path, now: dt.datetime) -> di
     }
 
 
+def render_result_text(result: dict) -> str:
+    totals = result.get("totals") if isinstance(result.get("totals"), dict) else {}
+    parts = ["# Okstra Error Report Input\n\n", line("Task key", result.get("taskKey")), line("Report path", result.get("reportPath")), line("Total errors", totals.get("errorCount")), line("Run count", totals.get("runCount")), line("Parse skipped", result.get("parseSkipped"))]
+    for key, label in (("byErrorType", "Error type"), ("bySource", "Source")):
+        values = totals.get(key)
+        if isinstance(values, dict):
+            for name, count in sorted(values.items()):
+                parts.append(line(f"{label} {name}", count))
+    for key, label in (("byPhase", "Phase"), ("byAgent", "Agent")):
+        values = result.get(key)
+        if isinstance(values, dict):
+            for name, count in sorted(values.items()):
+                parts.append(line(f"{label} {name}", count))
+        elif isinstance(values, list):
+            identity = "phase" if key == "byPhase" else "agent"
+            for row in values:
+                if isinstance(row, dict):
+                    parts.append(line(f"{label} {row.get(identity)}", row.get("count")))
+    return "".join(parts)
+
+
 def main(argv: list[str] | None = None) -> int:
     parser = argparse.ArgumentParser(
         description="Aggregate okstra-run error logs into a task-level report."
@@ -194,11 +217,13 @@ def main(argv: list[str] | None = None) -> int:
     parser.add_argument("target", help="task root path or task-key")
     parser.add_argument("--project-root", default="", help="project root for task-key lookup")
     parser.add_argument("--cwd", default=".", help="cwd for project root resolution")
+    parser.add_argument("--text", action="store_true", help="emit fixed text fields")
     args = parser.parse_args(argv)
 
     task_root, project_root = resolve_task_root(args.target, args.project_root, args.cwd)
     result = build_and_write(task_root, project_root, dt.datetime.now(dt.timezone.utc))
-    print(json.dumps(result, ensure_ascii=False, indent=2))
+    output = render_result_text(result) if args.text else json.dumps(result, ensure_ascii=False, indent=2)
+    print(output, end="" if args.text else "\n")
     return 0
 
 

package/runtime/python/okstra_ctl/error_zip.py

@@ -13,10 +13,13 @@ import sys
 import zipfile
 from pathlib import Path
 
+from .fixed_text import line
+
 from okstra_ctl.error_log_core import aggregate, parse_records
 from okstra_ctl.jsonl import read_jsonl
 from okstra_ctl.locks import central_lock
 from okstra_ctl.paths import okstra_home, resolve_under_root
+from okstra_ctl.json_boundary import load_owned_object, write_owned_object_atomic
 
 
 def run_dirs(home: Path) -> list[tuple[str, Path, dict]]:
@@ -262,9 +265,10 @@ _CONFIG_NAME = "error-zip.json"
 
 def remember_output_path(home: Path, out_path: Path) -> None:
     cfg = home / _CONFIG_NAME
-    cfg.write_text(
-        json.dumps({"lastOutputPath": str(out_path)}, ensure_ascii=False, indent=2),
-        encoding="utf-8",
+    write_owned_object_atomic(
+        cfg,
+        {"lastOutputPath": str(out_path)},
+        artifact="error zip configuration",
     )
 
 
@@ -273,7 +277,11 @@ def last_output_path(home: Path) -> str:
     if not cfg.is_file():
         return ""
     try:
-        return str(json.loads(cfg.read_text(encoding="utf-8")).get("lastOutputPath", ""))
+        return str(
+            load_owned_object(cfg, artifact="error zip configuration").get(
+                "lastOutputPath", ""
+            )
+        )
     except Exception:
         return ""
 
@@ -315,16 +323,30 @@ def build_zip(home: Path, out_path: Path, now: dt.datetime) -> dict:
     }
 
 
+def render_result_text(result: dict) -> str:
+    labels = (
+        ("outPath", "Output zip"), ("errorCount", "Total errors"),
+        ("runCount", "Run count"), ("unreachableRuns", "Unreachable runs"),
+        ("clusterCount", "Cluster count"), ("projectCount", "Project count"),
+    )
+    lines = ["# Okstra Error Zip Result\n\n"]
+    for key, label in labels:
+        lines.append(line(label, result.get(key)))
+    return "".join(lines)
+
+
 def main(argv: list[str] | None = None) -> int:
     parser = argparse.ArgumentParser(
         prog="okstra error-zip",
         description="cross-project okstra 에러를 수집·익명화해 zip 으로 묶는다.",
     )
     parser.add_argument("--out", required=True, help="출력 .zip 절대/상대 경로")
+    parser.add_argument("--text", action="store_true", help="emit fixed text fields")
     args = parser.parse_args(argv)
     home = okstra_home()
     result = build_zip(home, Path(args.out), dt.datetime.now(dt.timezone.utc))
-    print(json.dumps(result, ensure_ascii=False, indent=2))
+    output = render_result_text(result) if args.text else json.dumps(result, ensure_ascii=False, indent=2)
+    print(output, end="" if args.text else "\n")
     return 0
 
 

package/runtime/python/okstra_ctl/execution_identity.py

@@ -10,6 +10,7 @@ from typing import Any
 
 from .domain.provider import HostModelBinding, ServedModelAttestation
 from .domain.worker_exec import WorkerWriteCapability
+from .json_boundary import JsonBoundaryError, load_owned_object
 
 
 V2_SCHEMA_VERSION = "2.0"
@@ -479,8 +480,8 @@ def _capability_payload(
 
 def _read_json_object(path: Path) -> dict[str, Any]:
     try:
-        payload = json.loads(path.read_text(encoding="utf-8"))
-    except (OSError, json.JSONDecodeError) as exc:
+        payload = load_owned_object(path, artifact="execution identity")
+    except JsonBoundaryError as exc:
         raise ExecutionManifestError(f"cannot read execution identity: {path}") from exc
     if not isinstance(payload, dict):
         raise ExecutionManifestError("execution identity surface must be an object")

package/runtime/python/okstra_ctl/execution_manifest.py

@@ -27,6 +27,7 @@ from .execution_identity import (
     validate_task_role_execution_index,
 )
 from .final_report_schema import SchemaError, load_schema, validate as validate_schema
+from .json_boundary import JsonBoundaryError, load_owned_object, serialize_owned_object
 from .run_context import task_mutex
 from .write_policy import (
     WritePolicyError,
@@ -1257,8 +1258,8 @@ def _required_text(row: Mapping[str, Any], key: str) -> str:
 
 def _read_json_object(path: Path) -> dict[str, Any]:
     try:
-        payload = json.loads(path.read_text(encoding="utf-8"))
-    except (OSError, json.JSONDecodeError) as exc:
+        payload = load_owned_object(path, artifact="execution manifest")
+    except (OSError, JsonBoundaryError) as exc:
         raise ExecutionManifestError(f"cannot read JSON object: {path}") from exc
     if not isinstance(payload, dict):
         raise ExecutionManifestError(f"JSON surface must be an object: {path}")
@@ -1272,14 +1273,16 @@ def _write_json_atomic(
     create_only: bool = False,
 ) -> None:
     path.parent.mkdir(parents=True, exist_ok=True)
+    serialized = serialize_owned_object(
+        path, payload, artifact="execution manifest"
+    )
     descriptor, temporary_name = tempfile.mkstemp(
         prefix=f".{path.name}.", suffix=".tmp", dir=path.parent
     )
     temporary = Path(temporary_name)
     try:
         with os.fdopen(descriptor, "w", encoding="utf-8") as stream:
-            json.dump(payload, stream, indent=2, ensure_ascii=False)
-            stream.write("\n")
+            stream.write(serialized)
             stream.flush()
             os.fsync(stream.fileno())
         if create_only:

package/runtime/python/okstra_ctl/execution_mutation_audit.py

@@ -32,6 +32,10 @@ class MutationSnapshot:
     scratch_digests: Mapping[str, str]
     git_projection: Mapping[str, Any]
     digest: str
+    # 오케스트레이터가 쓰는 경로. 파일 하나를 싣거나 디렉터리를 실어 그 트리
+    # 전체를 덮을 수 있다 — 한 배치가 무엇을 쓸지 파일 단위로 미리 셀 수 없기
+    # 때문이다(다른 라운드의 재시도 프롬프트, 로그, 상태 사이드카가 그 창에
+    # 들어온다).
     orchestrator_paths: tuple[str, ...] = ()
 
     def to_payload(self) -> dict[str, Any]:
@@ -445,7 +449,7 @@ def _source_changes(
             snapshot.artifact_root == snapshot.root
             and any(_is_within(path, item) for item in artifacts)
         )
-        and path not in orchestrator
+        and not any(_is_within(path, item) for item in orchestrator)
         and not _excluded(Path(path), generated)
     }
 
@@ -464,7 +468,7 @@ def _artifact_policy_failures(
     unauthorized = {
         path for path in changed
         if not any(_is_within(path, item) for item in allowed)
-        and path not in orchestrator
+        and not any(_is_within(path, item) for item in orchestrator)
     }
     if snapshot.artifact_root == snapshot.root:
         return []

package/runtime/python/okstra_ctl/final_report_schema.py

@@ -1,11 +1,11 @@
-"""Mini JSON Schema validator for the final-report data.json.
+"""Mini JSON Schema validator for versioned final-report data.json records.
 
 This is a deliberately narrow JSON Schema implementation that supports
 exactly the keywords used by ``schemas/final-report-v2.0.schema.json``:
 
   type, required, properties, additionalProperties, enum, const, pattern,
   minLength, minItems, maxItems, uniqueItems, items, minimum, maximum, $ref ($defs),
-  oneOf, allOf, if/then/else, contains, not
+  oneOf, allOf, if/then/else, contains, minContains, maxContains, not
 
 We do NOT depend on the ``jsonschema`` PyPI package because its
 dependency tree (``referencing``, ``rpds-py``) includes a Rust C
@@ -13,8 +13,8 @@ extension which we would have to vendor or ship pre-built per platform.
 The ~250 lines below cover everything the final-report schema needs;
 strict spec compliance is not a goal — strict validation of OUR schema is.
 
-Error messages include the JSON pointer of the failing field so the
-report-writer can fix the exact data.json cell.
+Error messages include the JSON pointer of the failing field so report
+assembly can return the defect to the input owner.
 """
 from __future__ import annotations
 
@@ -23,9 +23,6 @@ import re
 from pathlib import Path
 from typing import Any
 
-from okstra_ctl.report_contract import CURRENT_REPORT_SCHEMA_VERSION
-
-
 class SchemaError(ValueError):
     """Raised when a schema itself is malformed (e.g. a $ref points
     nowhere). Distinct from a data validation failure.
@@ -204,10 +201,20 @@ class _Validator:
             for i, value in enumerate(instance):
                 self.validate(value, items, path + (i,))
         contains = schema.get("contains")
-        if contains is not None and not any(
-            self._matches(value, contains) for value in instance
-        ):
-            self._err(path, f"array does not contain any item matching {self._summarise(contains)}")
+        if contains is not None:
+            matches = sum(self._matches(value, contains) for value in instance)
+            minimum = schema.get("minContains", 1)
+            maximum = schema.get("maxContains")
+            if matches < minimum:
+                self._err(
+                    path,
+                    f"array contains {matches} matching item(s), below minContains {minimum}",
+                )
+            if maximum is not None and matches > maximum:
+                self._err(
+                    path,
+                    f"array contains {matches} matching item(s), above maxContains {maximum}",
+                )
 
     def _validate_conditional(self, instance: Any, schema: dict, path: tuple[str | int, ...]) -> None:
         if_schema = schema.get("if")
@@ -263,10 +270,11 @@ def validate(data: Any, schema: dict) -> list[str]:
 
 SCHEMA_FILENAMES = {
     "2.0": "final-report-v2.0.schema.json",
+    "3.0": "final-report-v3.0.schema.json",
 }
 
 
-def _locate_and_load_schema(filename: str, start: Path | None = None) -> dict:
+def load_named_schema(filename: str, start: Path | None = None) -> dict:
     here = (start or Path(__file__)).resolve()
     if here.is_file():
         here = here.parent
@@ -283,7 +291,7 @@ def load_schema_version(version: str, start: Path | None = None) -> dict:
         filename = SCHEMA_FILENAMES[version]
     except KeyError as exc:
         raise SchemaError(f"unsupported final-report schemaVersion: {version}") from exc
-    return _locate_and_load_schema(filename, start=start)
+    return load_named_schema(filename, start=start)
 
 
 def load_schema_for_data(data: dict, start: Path | None = None) -> dict:
@@ -295,10 +303,11 @@ def load_schema_for_data(data: dict, start: Path | None = None) -> dict:
 
 
 def load_schema(schema_path: Path | None = None) -> dict:
-    """Load the final-report schema. If ``schema_path`` is None, locate
-    ``schemas/final-report-v2.0.schema.json`` relative to this file's
-    repo root.
+    """Load the compatibility schema used by historical direct callers.
+
+    New write paths select contract 3.0 explicitly. Readers select from the
+    record's ``schemaVersion`` through :func:`load_schema_for_data`.
     """
     if schema_path is not None:
         return json.loads(Path(schema_path).read_text(encoding="utf-8"))
-    return load_schema_version(CURRENT_REPORT_SCHEMA_VERSION)
+    return load_schema_version("2.0")

package/runtime/python/okstra_ctl/fix_cycles.py

@@ -20,6 +20,7 @@ from pathlib import Path
 from typing import Any, Dict, List, Optional
 
 from .run_context import dir_flock
+from .jsonl import append_jsonl
 
 FIX_CYCLES_FILENAME = "fix-cycles.jsonl"
 _LOCK_FILENAME = ".fix-cycles.lock"
@@ -122,8 +123,7 @@ def append_closed(task_root: Path, *, cycle: str, closed_by: str,
 def _append_row(task_root: Path, record: Dict[str, Any]) -> None:
     p = fix_cycles_path(task_root)
     p.parent.mkdir(parents=True, exist_ok=True)
-    with p.open("a", encoding="utf-8") as f:
-        f.write(json.dumps(record, ensure_ascii=False) + "\n")
+    append_jsonl(p, record, ensure_ascii=False, compact=False)
 
 
 def summarize(rows: List[Dict[str, Any]]) -> Dict[str, Any]: