okstra 0.179.2 → 0.183.2

package/runtime/python/okstra_ctl/agent_activity.py

@@ -3,10 +3,8 @@ from __future__ import annotations
 
 import argparse
 import json
-import os
 import re
 import sys
-import tempfile
 from collections.abc import Mapping, Sequence
 from datetime import datetime, timezone
 from pathlib import Path
@@ -22,6 +20,11 @@ from okstra_ctl.worker_audit_ledger import (
     parse_evidence_commands,
     read_evidence_commands,
 )
+from okstra_ctl.json_boundary import (
+    JsonBoundaryError,
+    load_owned_object,
+    mutate_owned_object_atomic,
+)
 
 
 ACTIVITY_KINDS = frozenset({
@@ -59,12 +62,9 @@ class ActivityProjectionError(ValueError):
 
 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:
-        raise ActivityProjectionError(f"cannot read JSON object {path}: {exc}") from exc
-    if not isinstance(payload, dict):
-        raise ActivityProjectionError(f"JSON value must be an object: {path}")
-    return payload
+        return load_owned_object(path, artifact="agent activity artifact")
+    except JsonBoundaryError as exc:
+        raise ActivityProjectionError(str(exc)) from exc
 
 
 def _resolve_project_path(project_root: Path, value: str | Path) -> Path:
@@ -88,6 +88,50 @@ def _manifest_run_seq(manifest: Mapping[str, Any]) -> str:
     return _require_string(sequences, "manifests")
 
 
+def _validate_activity_ownership(
+    project_root: Path,
+    manifest: Mapping[str, Any],
+    details: Mapping[str, Any],
+) -> None:
+    executions = manifest.get("roleExecutions")
+    assignments = manifest.get("workerAssignments")
+    if isinstance(assignments, list):
+        assigned = {
+            row["workerId"] for row in assignments
+            if isinstance(row, Mapping) and isinstance(row.get("workerId"), str)
+        }
+    elif isinstance(executions, list):
+        assigned = {
+            f"{row['provider']}-worker"
+            for row in executions
+            if isinstance(row, Mapping) and isinstance(row.get("provider"), str)
+        }
+    else:
+        assigned = set()
+    if isinstance(assignments, list) or isinstance(executions, list):
+        assigned.update({"okstra-lead", f"{manifest.get('leadRuntime', '')}-lead"})
+        agent = _require_string(details, "agent")
+        if agent not in assigned:
+            raise ActivityProjectionError(
+                f"agent `{agent}` is not assigned to this run"
+            )
+    state_value = manifest.get("planBodyVerificationPath")
+    if not isinstance(state_value, str) or not details.get("planItemIds"):
+        return
+    state = _read_json_object(_resolve_project_path(project_root, state_value))
+    verification = state.get("planBodyVerification")
+    items = verification.get("planItems") if isinstance(verification, Mapping) else []
+    known = {
+        row.get("id") for row in items
+        if isinstance(row, Mapping) and isinstance(row.get("id"), str)
+    }
+    unknown = sorted(set(details["planItemIds"]) - known)
+    if unknown:
+        raise ActivityProjectionError(
+            "plan item(s) not in the current plan state: " + ", ".join(unknown)
+        )
+
+
 def _utc_now() -> str:
     return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
 
@@ -116,6 +160,14 @@ def _activity_row(event: LeadEvent) -> dict[str, Any]:
     from okstra_ctl.execution_identity import stored_identity
 
     row = {key: details[key] for key in ACTIVITY_FIELDS}
+    if "clarificationRefs" in details:
+        refs = details["clarificationRefs"]
+        if not isinstance(refs, list) or any(
+            not isinstance(ref, str) or re.fullmatch(r"C-\d{3,}", ref) is None
+            for ref in refs
+        ):
+            raise ActivityProjectionError("invalid clarificationRefs")
+        row["clarificationRefs"] = list(refs)
     row.update(stored_identity(details))
     return row
 
@@ -131,27 +183,6 @@ def _validate_activity_order(rows: Sequence[Mapping[str, Any]]) -> None:
         )
 
 
-def _atomic_write_json(path: Path, payload: Mapping[str, Any]) -> None:
-    path.parent.mkdir(parents=True, exist_ok=True)
-    temporary_path: Path | None = None
-    try:
-        with tempfile.NamedTemporaryFile(
-            mode="w",
-            encoding="utf-8",
-            dir=path.parent,
-            prefix=f".{path.name}.",
-            suffix=".tmp",
-            delete=False,
-        ) as handle:
-            temporary_path = Path(handle.name)
-            json.dump(payload, handle, ensure_ascii=False, indent=2)
-            handle.write("\n")
-        os.replace(temporary_path, path)
-    finally:
-        if temporary_path is not None and temporary_path.exists():
-            temporary_path.unlink()
-
-
 def record_activity(
     project_root: Path,
     run_manifest_path: Path,
@@ -164,6 +195,7 @@ def record_activity(
         raise ActivityProjectionError(
             "run manifest does not declare activityContractVersion 1"
         )
+    _validate_activity_ownership(project_root, manifest, details)
     event = LeadEvent(
         event_type="activity",
         lead_runtime=_require_string(manifest, "leadRuntime"),
@@ -176,15 +208,17 @@ def record_activity(
     events_path = _resolve_project_path(
         project_root, _require_string(manifest, "leadEventsPath")
     )
-    return append_activity_event(events_path, event)
+    try:
+        return append_activity_event(events_path, event)
+    except ValueError as exc:
+        raise ActivityProjectionError(str(exc)) from exc
 
 
-def project_agent_activity(
+def agent_activity_rows(
     project_root: Path,
     run_manifest_path: Path,
-    data_path: Path,
 ) -> tuple[dict[str, Any], ...]:
-    """Replace only ``agentActivity`` with this run's canonical events."""
+    """현재 실행의 정본 활동을 파일 변경 없이 반환한다."""
     manifest = _read_json_object(run_manifest_path)
     if manifest.get("activityContractVersion") != 1:
         return ()
@@ -204,9 +238,27 @@ def project_agent_activity(
     )
     rows = tuple(_activity_row(event) for event in events)
     _validate_activity_order(rows)
-    data = _read_json_object(data_path)
-    data["agentActivity"] = list(rows)
-    _atomic_write_json(data_path, data)
+    return rows
+
+
+def project_agent_activity(
+    project_root: Path,
+    run_manifest_path: Path,
+    data_path: Path,
+) -> tuple[dict[str, Any], ...]:
+    """2.0 호환 경로에서 ``agentActivity``만 교체한다."""
+    rows = agent_activity_rows(project_root, run_manifest_path)
+    manifest = _read_json_object(run_manifest_path)
+    if manifest.get("activityContractVersion") != 1:
+        return ()
+    try:
+        mutate_owned_object_atomic(
+            data_path,
+            lambda data: {**data, "agentActivity": list(rows)},
+            artifact="final report record",
+        )
+    except JsonBoundaryError as exc:
+        raise ActivityProjectionError(str(exc)) from exc
     return rows
 
 
@@ -222,6 +274,9 @@ def _parse_command_records(raw_records: Sequence[str]) -> tuple[EvidenceCommand,
 
 def _activity_commands(args: argparse.Namespace) -> tuple[EvidenceCommand, ...]:
     commands = list(_parse_command_records(args.command_record))
+    typed = _typed_command(args)
+    if typed is not None:
+        commands.append(typed)
     if args.audit_sidecar is not None:
         audit_commands, failures = read_evidence_commands(args.audit_sidecar)
         if failures:
@@ -230,6 +285,45 @@ def _activity_commands(args: argparse.Namespace) -> tuple[EvidenceCommand, ...]:
     return tuple(commands)
 
 
+def _typed_command(args: argparse.Namespace) -> EvidenceCommand | None:
+    values = (
+        args.evidence_command,
+        args.command_cwd,
+        args.command_exit_code,
+        args.command_output_file,
+    )
+    if not any(value is not None for value in values):
+        return None
+    if any(value is None for value in values):
+        raise ActivityProjectionError(
+            "--command requires --command-cwd, --command-exit-code, and "
+            "--command-output-file"
+        )
+    try:
+        output_summary = args.command_output_file.read_text(encoding="utf-8")
+    except (OSError, UnicodeError) as exc:
+        raise ActivityProjectionError(
+            f"cannot read command output {args.command_output_file}: {exc}"
+        ) from exc
+    return EvidenceCommand(
+        command=args.evidence_command,
+        cwd=args.command_cwd,
+        exit_code=args.command_exit_code,
+        output_summary=output_summary,
+    )
+
+
+def _activity_summary(args: argparse.Namespace) -> str:
+    if args.summary is not None:
+        return args.summary
+    try:
+        return args.summary_file.read_text(encoding="utf-8").strip()
+    except (OSError, UnicodeError) as exc:
+        raise ActivityProjectionError(
+            f"cannot read activity summary {args.summary_file}: {exc}"
+        ) from exc
+
+
 def _conversation_activity_line(details: Mapping[str, Any]) -> str:
     plan_items = ",".join(details["planItemIds"]) or "<none>"
     result_path = str(details["resultPath"] or "<none>")
@@ -246,13 +340,15 @@ def _append(args: argparse.Namespace) -> int:
     details = {
         "kind": args.kind,
         "agent": args.agent,
-        "summary": args.summary,
+        "summary": _activity_summary(args),
         "planItemIds": args.plan_item_id,
         "resultPath": args.result_path,
         "commands": [command.to_record() for command in commands],
         "evidenceRefs": args.evidence_ref,
         "outcome": args.outcome,
     }
+    if args.request_ref is not None:
+        details["activityRequestRef"] = args.request_ref
     event = record_activity(args.project_root, args.run_manifest, details)
     payload = dict(event.details)
     payload["ok"] = True
@@ -281,15 +377,22 @@ def _parser() -> argparse.ArgumentParser:
         "--kind", choices=sorted(ACTIVITY_KINDS), required=True
     )
     append_parser.add_argument("--agent", required=True)
-    append_parser.add_argument("--summary", required=True)
+    summary = append_parser.add_mutually_exclusive_group(required=True)
+    summary.add_argument("--summary")
+    summary.add_argument("--summary-file", type=Path)
     append_parser.add_argument(
         "--outcome", choices=sorted(ACTIVITY_OUTCOMES), required=True
     )
     append_parser.add_argument("--plan-item-id", action="append", default=[])
     append_parser.add_argument("--evidence-ref", action="append", default=[])
     append_parser.add_argument("--command-record", action="append", default=[])
+    append_parser.add_argument("--command", dest="evidence_command")
+    append_parser.add_argument("--command-cwd")
+    append_parser.add_argument("--command-exit-code", type=int)
+    append_parser.add_argument("--command-output-file", type=Path)
     append_parser.add_argument("--result-path", default="")
     append_parser.add_argument("--audit-sidecar", type=Path)
+    append_parser.add_argument("--request-ref")
     project_parser = subparsers.add_parser("project")
     project_parser.add_argument("--project-root", type=Path, required=True)
     project_parser.add_argument("--run-manifest", type=Path, required=True)

package/runtime/python/okstra_ctl/agent_invocation.py

@@ -15,6 +15,12 @@ import tempfile
 from typing import Iterator, Literal, Mapping, get_args
 
 from .domain.role import RoleCatalogError, role_for_duty
+from .json_boundary import (
+    JsonBoundaryError,
+    external_invocation_json_source,
+    load_external_json,
+    load_owned_object,
+)
 
 
 AgentAudience = Literal[
@@ -935,8 +941,15 @@ def _verified_result_envelope(
 ) -> tuple[bytes, str]:
     try:
         body = result_path.read_bytes()
-        envelope = json.loads(body.decode("utf-8"))
-    except (OSError, UnicodeDecodeError, json.JSONDecodeError) as exc:
+        envelope = load_external_json(
+            external_invocation_json_source(
+                result_path,
+                project_root=project_root,
+                purpose=purpose,
+            ),
+            artifact="standalone worker result",
+        )
+    except (OSError, UnicodeDecodeError, json.JSONDecodeError, JsonBoundaryError) as exc:
         raise AgentInvocationError(
             f"standalone result envelope is missing or invalid: {result_path}"
         ) from exc
@@ -1494,8 +1507,8 @@ def _metadata_difference(
     so they are reported by name too.
     """
     try:
-        existing = json.loads(metadata.read_text(encoding="utf-8"))
-    except (OSError, json.JSONDecodeError) as exc:
+        existing = load_owned_object(metadata, artifact="agent invocation metadata")
+    except JsonBoundaryError as exc:
         return f"existing metadata is unreadable: {exc}"
     composed = materialized.metadata
     if not isinstance(existing, dict):
@@ -2240,8 +2253,8 @@ def _load_json_object(path: Path, label: str) -> dict[str, object]:
 
 def _read_json_if_object(path: Path) -> dict[str, object] | None:
     try:
-        value = json.loads(path.read_text(encoding="utf-8"))
-    except (OSError, json.JSONDecodeError):
+        value = load_owned_object(path, artifact="agent invocation metadata")
+    except JsonBoundaryError:
         return None
     return value if isinstance(value, dict) else None
 

package/runtime/python/okstra_ctl/agent_prompt_cli.py

@@ -34,6 +34,8 @@ from .agent_invocation import (
     verify_agent_invocation,
     v2_role_assignment_authority_errors,
 )
+from .fixed_text import line
+from .json_boundary import JsonBoundaryError, load_owned_object
 from .convergence_store import (
     DYNAMIC_VERIFIER_SOURCE_ROLES,
     reserve_dynamic_verifier,
@@ -48,7 +50,11 @@ from .wrapper_status import (
     prompt_derived_paths,
     status_path_for_prompt,
 )
-from .worker_prompt_policy import resolve_prompt_plan_for_manifest
+from .report_inputs import report_narrative_path, uses_report_contract_v3
+from .worker_prompt_policy import (
+    CRITIC_DUTY_BY_ASSIGNMENT_SEGMENT,
+    resolve_prompt_plan_for_manifest,
+)
 from .dispatch_state import (
     BACKEND_CLI_WRAPPER,
     BACKEND_CMUX_PANE,
@@ -70,6 +76,13 @@ class AgentPromptCliError(RuntimeError):
 def _parser() -> argparse.ArgumentParser:
     parser = argparse.ArgumentParser(prog="okstra agent-prompt")
     commands = parser.add_subparsers(dest="command", required=True)
+    _add_materialize_parser(commands)
+    _add_completion_parsers(commands)
+    _add_dispatch_parsers(commands)
+    return parser
+
+
+def _add_materialize_parser(commands: argparse._SubParsersAction) -> None:
     materialize = commands.add_parser("materialize")
     _common_paths(materialize)
     materialize.add_argument("--invocation-id", required=True)
@@ -110,7 +123,10 @@ def _parser() -> argparse.ArgumentParser:
     verify.add_argument("--run-manifest")
     verify.add_argument("--metadata", required=True)
     verify.add_argument("--json", action="store_true")
+    verify.add_argument("--text", action="store_true")
 
+
+def _add_completion_parsers(commands: argparse._SubParsersAction) -> None:
     materialize_result = commands.add_parser("materialize-result")
     _standalone_completion_args(materialize_result)
     materialize_result.add_argument("--returned-body-file", required=True)
@@ -124,6 +140,8 @@ def _parser() -> argparse.ArgumentParser:
     verify_completion.add_argument("--completion", required=True)
     verify_completion.add_argument("--json", action="store_true")
 
+
+def _add_dispatch_parsers(commands: argparse._SubParsersAction) -> None:
     record_dispatch = commands.add_parser("record-dispatch")
     _common_paths(record_dispatch)
     record_dispatch.add_argument("--run-manifest", required=True)
@@ -153,7 +171,6 @@ def _parser() -> argparse.ArgumentParser:
     link_result.add_argument("--dispatch-id", required=True)
     link_result.add_argument("--result", required=True)
     link_result.add_argument("--json", action="store_true")
-    return parser
 
 
 def _common_paths(parser: argparse.ArgumentParser) -> None:
@@ -179,6 +196,7 @@ def main(argv: list[str] | None = None) -> int:
             _emit(
                 {"ok": True, "metadataPath": str(Path(args.metadata).resolve())},
                 args.json,
+                args.text,
             )
             return 0
         if args.command == "materialize-result":
@@ -314,16 +332,32 @@ def _materialize_run(
     )
     if args.audience == "report-writer" and not args.audit_source:
         # The report writer is the one audience whose result path is not its own
-        # worker result: it writes the report `data.json`, while the audit
-        # sidecar is derived from its `.md`. With both collapsed into one value
-        # the prompt loses its `**Worker Result Path:**` anchor and the writer
-        # puts the report where the audit file belongs — silently, because every
-        # header is still present and well-formed. The roster path derives both
-        # from the manifest; a dynamic call has to name them.
+        # worker result: it writes the report body, while the audit sidecar is
+        # derived from its `.md`. With both collapsed into one value the prompt
+        # loses its `**Worker Result Path:**` anchor and the writer puts the
+        # report where the audit file belongs — silently, because every header
+        # is still present and well-formed. The roster path derives both from
+        # the manifest; a dynamic call has to name them.
+        #
+        # Which artifact `--result` names depends on the report contract, and
+        # `dispatch_state.dispatch_result_path` is what decides it. Naming only
+        # the v2 answer here sent v3 runs to the data.json, so the narrative
+        # `report-finalize` assembles from was never written and the phase
+        # failed later, at a place that does not point back here.
+        if uses_report_contract_v3(manifest):
+            expected = report_narrative_path(project_root, manifest)
+            raise AgentPromptCliError(
+                "report-writer materialization requires --audit-source: under "
+                f"report contract 3.0 --result is the narrative ({expected}), "
+                "which `report-finalize` assembles the report data.json from, "
+                "and --audit-source the worker-result .md the audit sidecar is "
+                "derived from"
+            )
         raise AgentPromptCliError(
-            "report-writer materialization requires --audit-source: --result is "
-            "the report data.json, --audit-source the worker-result .md the "
-            "audit sidecar is derived from"
+            "report-writer materialization requires --audit-source: under "
+            "report contract 2.0 --result is the report data.json, and "
+            "--audit-source the worker-result .md the audit sidecar is "
+            "derived from"
         )
     audit_source_path = (
         _authorized_path(
@@ -630,17 +664,15 @@ def _validate_run_identity(
             raise AgentPromptCliError("translator assignment requires worker ID 'translator'")
     elif assignment_ref.startswith("critic/"):
         scope = assignment_ref.split("/", 1)[1]
-        expected = {"scope": "scope-critic", "acceptance": "acceptance-critic"}.get(
-            scope,
-            "",
-        )
+        expected = CRITIC_DUTY_BY_ASSIGNMENT_SEGMENT.get(scope, "")
         if not expected or dispatch_kind != "critic":
             raise AgentPromptCliError("critic assignment identity is invalid")
-        convergence = manifest.get("convergence")
-        critic = convergence.get("critic") if isinstance(convergence, Mapping) else None
-        provider = critic.get("provider") if isinstance(critic, Mapping) else None
-        if provider and provider != worker_id:
-            raise AgentPromptCliError("critic worker does not match manifest provider")
+        # provider 대조는 여기 두지 않는다. critic 의 `worker_id` 는 배정 참조의
+        # 마지막 마디(`scope` / `acceptance`)이고 provider 이름이 아니다
+        # (`render.py` 의 로스터 행이 `assignment_ref.rsplit("/", 1)[-1]` 로 만든다).
+        # 종전에 있던 `provider != worker_id` 검사는 두 어휘를 비교해서 늘 참이 되는
+        # 형태였고, 설정을 run manifest 에서 찾다 못 찾아 조용히 건너뛰었기에
+        # 드러나지 않았다. 정본에서 읽게 고치면 모든 critic 디스패치가 거부된다.
     else:
         try:
             expected = resolve_prompt_plan_for_manifest(
@@ -1039,8 +1071,8 @@ def _relative(project_root: Path, path: Path) -> str:
 
 def _read_json_object(path: Path, label: str) -> dict[str, Any]:
     try:
-        value = json.loads(path.read_text(encoding="utf-8"))
-    except (OSError, UnicodeDecodeError, json.JSONDecodeError) as exc:
+        value = load_owned_object(path, artifact="agent prompt metadata")
+    except JsonBoundaryError as exc:
         raise AgentPromptCliError(f"{label} is invalid: {path}") from exc
     if not isinstance(value, dict):
         raise AgentPromptCliError(f"{label} must be a JSON object: {path}")
@@ -1098,12 +1130,27 @@ def _prepared_payload(
     }
 
 
-def _emit(payload: Mapping[str, object], as_json: bool) -> None:
+def _emit(
+    payload: Mapping[str, object], as_json: bool, as_text: bool = False
+) -> None:
     if as_json:
         print(json.dumps(payload, ensure_ascii=False, indent=2))
+    elif as_text:
+        print(render_agent_prompt_text(payload), end="")
     else:
         print(payload.get("promptPath") or payload.get("metadataPath") or "ok")
 
 
+def render_agent_prompt_text(payload: Mapping[str, object]) -> str:
+    """agent prompt 검증 결과의 승인된 경로만 투영한다."""
+    rows = ["Okstra agent prompt\n"]
+    rows.append(line("Status", "ready" if payload.get("ok", True) else "error"))
+    for label, key in (("Prompt path", "promptPath"), ("Metadata path", "metadataPath"),
+                       ("Assignment ID", "assignmentId"), ("Worker role", "workerRole")):
+        if key in payload:
+            rows.append(line(label, payload.get(key)))
+    return "".join(rows)
+
+
 if __name__ == "__main__":
     raise SystemExit(main())

package/runtime/python/okstra_ctl/analysis_inputs.py

@@ -11,6 +11,7 @@ from typing import Mapping, Sequence
 
 from .final_report_paths import final_report_data_path
 from .paths import task_manifest_file
+from .json_boundary import JsonBoundaryError, load_owned_object
 from .user_response import (
     UserResponseError,
     load_authoritative_analysis_review,
@@ -196,8 +197,8 @@ def _task_key_from_manifest(task_root: Path, okstra_root: Path) -> str:
         task_manifest_file(task_root), okstra_root, "task manifest path"
     )
     try:
-        manifest = json.loads(manifest_path.read_text(encoding="utf-8"))
-    except (OSError, json.JSONDecodeError) as exc:
+        manifest = load_owned_object(manifest_path, artifact="task manifest")
+    except JsonBoundaryError as exc:
         raise AnalysisInputError(f"cannot read task manifest: {manifest_path}") from exc
     if not isinstance(manifest, dict):
         raise AnalysisInputError("task manifest must contain an object")
@@ -219,8 +220,8 @@ def load_analysis_report_candidate(
         raise AnalysisInputError("report filename is not a final report")
     data_path = _resolved_within(final_report_data_path(report), okstra_root, "data.json path")
     try:
-        data = json.loads(data_path.read_text(encoding="utf-8"))
-    except (OSError, json.JSONDecodeError) as exc:
+        data = load_owned_object(data_path, artifact="analysis report record")
+    except JsonBoundaryError as exc:
         raise AnalysisInputError(f"cannot read data.json: {data_path}") from exc
     if not isinstance(data, dict):
         raise AnalysisInputError("data.json must contain an object")