okstra 0.179.2 → 0.183.2

package/runtime/python/okstra_ctl/wizard.py

@@ -94,6 +94,7 @@ from okstra_ctl.clarification_items import (
     user_response_sidecars,
 )
 from okstra_ctl.convergence_store import write_json_atomic
+from okstra_ctl.json_boundary import JsonBoundaryError, load_owned_object
 from okstra_ctl.incremental_scope import (
     parse_stage_graph,
     preview_link_availability_for_report,
@@ -869,13 +870,13 @@ def _validate_sidecar_option(plan_path: Path, option_name: str, errors_t: dict)
     candidates: list[str] = []
     if data_path.is_file():
         try:
-            data = json.loads(data_path.read_text(encoding="utf-8"))
+            data = load_owned_object(data_path, artifact="planning final report")
             planning = data.get("implementationPlanning") or {}
             candidates = [
                 c.get("name", "") for c in planning.get("optionCandidates") or []
                 if isinstance(c, dict) and c.get("name")
             ]
-        except (OSError, json.JSONDecodeError):
+        except (OSError, JsonBoundaryError):
             candidates = []
     if option_name not in candidates:
         raise WizardError(
@@ -2002,8 +2003,8 @@ def _load_wizard_root(workspace_root: str) -> dict:
             "Re-run `okstra install` or check the workspace_root."
         )
     try:
-        raw = json.loads(path.read_text(encoding="utf-8"))
-    except json.JSONDecodeError as exc:
+        raw = load_owned_object(path, artifact="wizard prompts")
+    except JsonBoundaryError as exc:
         raise WizardError(f"wizard prompt JSON malformed: {path}: {exc}") from exc
     if not isinstance(raw, dict):
         raise WizardError(f"wizard prompt JSON root must be an object: {path}")
@@ -4217,7 +4218,7 @@ def _prior_stage_numbers(state: WizardState) -> set[int]:
         )
     data_path = final_report_data_path(report)
     try:
-        data = json.loads(data_path.read_text(encoding="utf-8"))
+        data = load_owned_object(data_path, artifact="planning final report")
         stages = {num for num, _ in parse_stage_graph(data)}
     except (OSError, ValueError, KeyError, TypeError) as exc:
         raise WizardError(
@@ -4300,8 +4301,8 @@ def _suggest_project_pr_template(state: WizardState) -> str:
     if not project_json.is_file():
         return ""
     try:
-        data = json.loads(project_json.read_text(encoding="utf-8"))
-    except (OSError, json.JSONDecodeError):
+        data = load_owned_object(project_json, artifact="project config")
+    except (OSError, JsonBoundaryError):
         return ""
     val = data.get("prTemplatePath") or ""
     return val if isinstance(val, str) else ""
@@ -5138,39 +5139,6 @@ def _worktree_preview_line_impl(state: WizardState) -> str:
                 stage=stage, path=str(decision.path), branch=decision.branch)
 
 
-def _critic_collision_lines(state: WizardState) -> list[str]:
-    """critic provider 가 분석 로스터와 겹칠 때 그 대가를 확인 화면에서 말한다.
-
-    gap 검증 투표자는 `convergence_engine._is_critic_worker` 가 critic **provider
-    이름**으로 걸러낸다 — critic 워커 id 가 아니라 provider 다. 그래서 같은
-    provider 의 분석 워커가 투표에서 빠지고, 분석 워커가 둘뿐인 로스터에서는
-    정족수가 1로 준다. 그 사실이 선택 시점에는 어디에도 드러나지 않아, critic 도
-    돌고 gap 검증 라운드도 완료된 뒤 `apply-critic-gaps` 가 거부할 때에야 알려졌다
-    — 이미 워커 실행 비용을 쓴 다음이다.
-
-    막지는 않는다. 겹치는 provider 를 고르는 것이 잘못은 아니고, 그 대가를 알고
-    고르는 것과 모르고 고르는 것의 차이만 없앤다.
-    """
-    if not state.critic or state.critic == "off":
-        return []
-    analysers = [
-        worker for worker in _resolved_roster(state) if worker != "report-writer"
-    ]
-    excluded = [
-        worker for worker in analysers
-        if worker in {state.critic, f"{state.critic}-worker"}
-    ]
-    if not excluded:
-        return []
-    return [
-        _msg(
-            state.workspace_root, "confirmation", "critic_shares_analyser_provider",
-            worker=excluded[0],
-            remaining=len(analysers) - len(excluded),
-        )
-    ]
-
-
 def _build_confirm(state: WizardState) -> Prompt:
     t = _p(state.workspace_root, "confirm")
     return Prompt(
@@ -6496,7 +6464,6 @@ def confirmation_block(state: WizardState) -> str:
     if (not role_selection
             and state.task_type in ("requirements-discovery", "error-analysis", "implementation-planning", "final-verification")):
         lines.append(f"  critic        : {state.critic or '(off)'}")
-        lines.extend(_critic_collision_lines(state))
     if state.task_type in _STAGE_SCOPED_TASK_TYPES:
         lines.append(f"  approved-plan : {state.approved_plan_path}")
         stage = wizard_stage_confirmation_label(
@@ -6631,8 +6598,8 @@ def _matching_v2_companion(
     source_metadata: dict[str, str],
 ) -> dict[str, Any] | None:
     try:
-        payload = json.loads(path.read_text(encoding="utf-8"))
-    except (OSError, UnicodeError, json.JSONDecodeError):
+        payload = load_owned_object(path, artifact="wizard state")
+    except (OSError, UnicodeError, JsonBoundaryError):
         return None
     if not isinstance(payload, dict):
         return None
@@ -6661,7 +6628,7 @@ def _load_matching_v2_state(
 def load_state_file(path: Path) -> WizardState:
     source_path = Path(path)
     source = source_path.read_bytes()
-    data = json.loads(source)
+    data = load_owned_object(source_path, artifact="wizard state")
     source_version = data.get("executionIdentityVersion", 1)
     source_metadata = _legacy_source_metadata(source_path, source)
     source_digest = source_metadata["sha256"]

package/runtime/python/okstra_ctl/work_categories.py

@@ -12,6 +12,7 @@ import json
 from pathlib import Path
 
 from .paths import task_dir, task_manifest_file
+from .json_boundary import JsonBoundaryError, load_owned_object
 
 WORK_CATEGORIES: tuple[str, ...] = (
     "bugfix",
@@ -32,8 +33,8 @@ def recorded_work_category(project_root: Path, task_group: str, task_id: str) ->
     """task-manifest.json 에 이미 기록된 work-category. 없거나 enum 밖이면 ""."""
     manifest = task_manifest_file(task_dir(project_root, task_group, task_id))
     try:
-        data = json.loads(manifest.read_text(encoding="utf-8"))
-    except (OSError, json.JSONDecodeError):
+        data = load_owned_object(manifest, artifact="task manifest")
+    except JsonBoundaryError:
         return ""
     value = str(data.get("workCategory") or "").strip()
     return value if is_valid_category(value) else ""

package/runtime/python/okstra_ctl/worker_dispatch.py

@@ -76,7 +76,7 @@ def _parser() -> argparse.ArgumentParser:
     parser.add_argument("--okstra-bin", default="")
     parser.add_argument("--workers", default="")
     parser.add_argument("--dry-run", action="store_true")
-    parser.add_argument("--idle-timeout-seconds", default="600")
+    parser.add_argument("--idle-timeout-seconds", default="")
     parser.add_argument("--dispatch-kind", default="initial")
     parser.add_argument("--jobs-file", default="")
     return parser
@@ -86,7 +86,10 @@ def _parse_workers(raw: str) -> list[str]:
     return [item.strip() for item in raw.split(",") if item.strip()]
 
 
-def _parse_idle_timeout(raw: str) -> int:
+def _parse_idle_timeout(raw: str) -> int | None:
+    """명시된 예산, 또는 역할이 정하게 두는 ``None``."""
+    if not raw:
+        return None
     try:
         value = int(raw)
     except ValueError as exc:

package/runtime/python/okstra_ctl/worker_prompt_body.py

@@ -89,8 +89,18 @@ def report_writer_prompt_body(
     team_state: Mapping[str, Any],
     model: str,
     report_language: str,
+    synthesis_packet_path: str = "",
 ) -> list[str]:
     """Render the provider-neutral body for the report-writer audience."""
+    if str(manifest.get("reportContractVersion") or "") == "3.0":
+        return _report_writer_v3_body(
+            manifest,
+            active_context,
+            team_state,
+            model,
+            report_language,
+            synthesis_packet_path,
+        )
     return [
         f"**Model:** Report writer worker, {model}",
         f"**Report Language:** {report_language}",
@@ -102,9 +112,11 @@ def report_writer_prompt_body(
         f"- Task type: `{_require_string(manifest, 'taskType')}`",
         "",
         "## Inputs",
-        *report_writer_input_lines(manifest, active_context, team_state),
-        "",
-        mcp_pointer_line(),
+        *(
+            [f"- Report synthesis packet: `{synthesis_packet_path}`"]
+            if synthesis_packet_path
+            else report_writer_input_lines(manifest, active_context, team_state)
+        ),
         "",
         "## Output Contract",
         "You are the author of TWO files:",
@@ -124,6 +136,40 @@ def report_writer_prompt_body(
     ]
 
 
+def _report_writer_v3_body(
+    manifest: Mapping[str, Any],
+    active_context: Mapping[str, Any],
+    team_state: Mapping[str, Any],
+    model: str,
+    report_language: str,
+    synthesis_packet_path: str,
+) -> list[str]:
+    return [
+        f"**Model:** Report writer worker, {model}",
+        f"**Report Language:** {report_language}",
+        "",
+        "# Report Writer Worker Dispatch",
+        "",
+        "## Task",
+        f"- Task key: `{_require_string(manifest, 'taskKey')}`",
+        f"- Task type: `{_require_string(manifest, 'taskType')}`",
+        "",
+        "## Inputs",
+        *(
+            [f"- Report synthesis packet: `{synthesis_packet_path}`"]
+            if synthesis_packet_path
+            else report_writer_input_lines(manifest, active_context, team_state)
+        ),
+        "",
+        "## Output Contract",
+        "You are the author of the report narrative Markdown at Result Path.",
+        "Write the worker-result pointer at Worker Result Path.",
+        "Maintain the separate audit sidecar at Audit sidecar path.",
+        "Do not write the final report record or another owner's input ledger.",
+        "Do not return the report inline.",
+    ]
+
+
 def report_writer_input_lines(
     manifest: Mapping[str, Any],
     active_context: Mapping[str, Any],

package/runtime/python/okstra_ctl/worker_prompt_contract.py

@@ -8,6 +8,7 @@ from pathlib import Path
 from typing import Any, Iterable, Mapping, Sequence
 
 from .worker_prompt_body import analysis_worker_label
+from .json_boundary import load_owned_object
 from .worker_prompt_policy import (
     ERRORS_PATH_HEADERS,
     IMPLEMENTATION_HEADERS,
@@ -389,8 +390,8 @@ def _validate_record_metadata(text: str, record: PromptRecord) -> list[str]:
     if record.metadata_path is None:
         return [*errors, "agent invocation metadata path is required"]
     try:
-        metadata = json.loads(
-            record.metadata_path.read_text(encoding="utf-8")
+        metadata = load_owned_object(
+            record.metadata_path, artifact="agent invocation metadata"
         )
     except (OSError, UnicodeError, ValueError):
         return [*errors, "agent invocation metadata is invalid"]

package/runtime/python/okstra_ctl/worker_prompt_policy.py

@@ -120,9 +120,7 @@ def resolve_prompt_plan(
     # that are *supposed* to differ and fail every critic-enabled run.
     analysis_equality_group = None if dispatch_kind == "critic" else "analysis-core"
     analysis_duty: AgentAudience = (
-        "acceptance-critic"
-        if dispatch_kind == "critic" and task_type == "final-verification"
-        else "scope-critic"
+        critic_duty_for_task_type(task_type)
         if dispatch_kind == "critic"
         else "acceptance-verifier"
         if task_type == "final-verification"
@@ -232,6 +230,36 @@ def _worker_facing_headers(
     return (*ERRORS_PATH_HEADERS, *required_headers)
 
 
+# 하나의 run 이 실제로 디스패치할 수 있는 critic 은 한 종류다. 판정은 task type
+# 만의 함수이므로 여기 한 번만 적고, 로스터 등록과 프롬프트 정체성 검사가 같은
+# 값을 읽는다 — 로스터가 실행될 수 없는 critic 행을 하나 더 들고 있으면 provider
+# 로만 만든 role 라벨이 겹쳐 validate-run 의 중복 역할 검사에 걸린다.
+CRITIC_DUTY_BY_ASSIGNMENT_SEGMENT: dict[str, AgentAudience] = {
+    "scope": "scope-critic",
+    "acceptance": "acceptance-critic",
+}
+
+
+def critic_duty_for_task_type(task_type: str) -> AgentAudience:
+    """이 task type 의 critic 직무."""
+    return (
+        "acceptance-critic"
+        if task_type == "final-verification"
+        else "scope-critic"
+    )
+
+
+def critic_assignment_ref(task_type: str) -> str:
+    """이 task type 이 등록할 유일한 critic 배정 참조."""
+    duty = critic_duty_for_task_type(task_type)
+    segment = next(
+        key
+        for key, value in CRITIC_DUTY_BY_ASSIGNMENT_SEGMENT.items()
+        if value == duty
+    )
+    return f"critic/{segment}"
+
+
 def _executor_worker_id(manifest: Mapping[str, Any]) -> str | None:
     team_contract = manifest.get("teamContract")
     if not isinstance(team_contract, Mapping):

package/runtime/python/okstra_ctl/worker_runner.py

@@ -28,6 +28,7 @@ from .domain.worker_exec import (
 )
 from .domain.worker_presentation import JsonEvents, Presentation
 from .session_transcript import SessionTranscript
+from .json_boundary import JsonBoundaryError, write_owned_object_atomic
 
 LIVE = "live"
 QUIET = "quiet"
@@ -225,7 +226,11 @@ def _with_served_model_observation(
         observation.record(observed)
         return observed
 
-    return JsonEvents(normalise=presentation.normalise, observe=observe)
+    return JsonEvents(
+        normalise=presentation.normalise,
+        observe=observe,
+        join_adjacent_text=presentation.join_adjacent_text,
+    )
 
 
 class _ServedModelObservation:
@@ -350,9 +355,7 @@ def _pump(
     stdin_text: str | None = None,
 ) -> tuple[int, bool, int]:
     selector = selectors.DefaultSelector()
-    readers = _register_streams(
-        selector, process, strategy, transcript, presentation == LIVE
-    )
+    readers = _register_streams(selector, process, strategy, transcript)
     outgoing = _register_prompt(selector, process, stdin_text)
     closing_text: str | None = None
     last_output = time.monotonic()
@@ -387,6 +390,7 @@ def _pump(
 
     for reader in readers.values():
         closing_text = reader.flush() or closing_text
+    strategy.flush(transcript)
 
     exit_code = process.wait()
     if closing_text is None and isinstance(strategy, JsonEvents):
@@ -441,13 +445,12 @@ def _register_streams(
     process: subprocess.Popen[bytes],
     presentation: Presentation,
     transcript: SessionTranscript,
-    live: bool,
 ) -> dict[int, _LineReader]:
     """이 자식이 말하는 스트림마다 전략이 지정한 싱크를 붙인다."""
     assert process.stdout is not None
     streams = {"stdout": process.stdout, "stderr": process.stderr}
     readers: dict[int, _LineReader] = {}
-    for channel, sink in presentation.sinks(transcript, live):
+    for channel, sink in presentation.sinks(transcript):
         stream = streams[channel]
         assert stream is not None, channel
         selector.register(stream, selectors.EVENT_READ)
@@ -599,12 +602,11 @@ def _write_status(path: Path, status: Mapping[str, Any]) -> None:
     Replaced whole rather than rewritten in place: readers poll this file while
     the worker is still running and must never see a half-written document.
     """
-    temporary = Path(f"{path}.tmp")
     try:
-        path.parent.mkdir(parents=True, exist_ok=True)
-        temporary.write_text(
-            json.dumps(status, ensure_ascii=False, indent=2) + "\n", encoding="utf-8"
+        write_owned_object_atomic(
+            path,
+            status,
+            artifact="worker wrapper status",
         )
-        os.replace(temporary, path)
-    except OSError:
+    except (OSError, JsonBoundaryError):
         return

package/runtime/python/okstra_ctl/workflow.py

@@ -14,6 +14,7 @@ from __future__ import annotations
 
 import json
 from pathlib import Path
+from .json_boundary import load_owned_object
 
 PHASE_SEQUENCE = [
     "requirements-discovery",
@@ -160,7 +161,7 @@ def load_phase_forbidden(workspace_root: Path) -> dict[str, str]:
     `prompts/profiles/forbidden-actions.json`.
     """
     path = Path(workspace_root) / "prompts" / "profiles" / "forbidden-actions.json"
-    data = json.loads(path.read_text(encoding="utf-8"))
+    data = load_owned_object(path, artifact="forbidden actions profile")
     if "unknown" not in data:
         # compute_workflow_state falls back to the "unknown" entry for any
         # unmapped task_type; without it a missing/renamed key would surface as

package/runtime/python/okstra_ctl/worktree.py

@@ -44,6 +44,7 @@ from typing import Optional
 from okstra_project.dirs import okstra_home, project_json_path
 
 from .ids import _safe_fs_segment
+from .json_boundary import JsonBoundaryError, load_owned_object
 from . import worktree_registry
 from .seeding import (
     SettingsLinkError,
@@ -415,8 +416,8 @@ def _read_project_json_field(project_root: Path, field: str) -> Optional[tuple[s
     if not target.is_file():
         return None
     try:
-        data = json.loads(target.read_text(encoding="utf-8"))
-    except (OSError, json.JSONDecodeError):
+        data = load_owned_object(target, artifact="project config")
+    except (OSError, JsonBoundaryError):
         return None
     if not isinstance(data, dict):
         return None

package/runtime/python/okstra_ctl/wrapper_status.py

@@ -6,6 +6,8 @@ from dataclasses import dataclass
 from pathlib import Path
 from typing import Any, Mapping
 
+from .json_boundary import JsonBoundaryError, load_owned_object
+
 
 @dataclass(frozen=True)
 class WrapperStatus:
@@ -65,8 +67,8 @@ def prompt_derived_paths(prompt_path: Path) -> tuple[Path, ...]:
 
 def read_wrapper_status(path: Path) -> WrapperStatus | None:
     try:
-        raw = json.loads(path.read_text(encoding="utf-8"))
-    except (OSError, json.JSONDecodeError):
+        raw = load_owned_object(path, artifact="worker wrapper status")
+    except (OSError, JsonBoundaryError):
         return None
     if not isinstance(raw, dict):
         return None

package/runtime/python/okstra_ctl/write_policy.py

@@ -9,6 +9,8 @@ from dataclasses import dataclass
 from pathlib import Path, PurePosixPath
 from typing import Any, Literal
 
+from .json_boundary import JsonBoundaryError, load_owned_object
+
 BoundaryPrecision = Literal["exact-path", "directory-boundary", "none"]
 
 _PRECISION_RANK = {"none": 0, "directory-boundary": 1, "exact-path": 2}
@@ -538,8 +540,8 @@ def _rooted(project_root: Path, value: str) -> Path:
 
 def _read_json(path: Path, label: str) -> Mapping[str, Any]:
     try:
-        value = json.loads(path.read_text(encoding="utf-8"))
-    except (OSError, UnicodeError, json.JSONDecodeError) as exc:
+        value = load_owned_object(path, artifact=label)
+    except (OSError, UnicodeError, JsonBoundaryError) as exc:
         raise WritePolicyError(f"{label} is invalid: {path}") from exc
     if not isinstance(value, Mapping):
         raise WritePolicyError(f"{label} must be an object: {path}")

package/runtime/python/okstra_token_usage/antigravity.py

@@ -1,29 +1,56 @@
 """Antigravity (`agy`) CLI usage collector.
 
-okstra dispatches the antigravity-worker via `agy --print` (see
-`okstra-antigravity-exec.sh`). That non-interactive print mode does not persist
-a parseable transcript with per-call token counts to any known location, so
-per-run token/cost usage cannot be attributed to the antigravity worker. These
-collectors therefore report "unavailable" rather than fabricating numbers — the
-worker's usage block degrades to `na` and `/okstra-inspect context-cost` shows
-N/A for antigravity. If a future `agy` build exposes a transcript, wire its
-parser here (model ids stay `gemini-*`, so `antigravity_cost_usd` already prices it).
+공식 headless 문서는 ``--output-format json`` / ``stream-json`` 의 최종
+``usage`` 객체에 토큰을 둔다. okstra 는 이미 ``stream-json`` 으로 호출하고
+그 줄을 워커 로그에 남긴다. 정본은 마지막 ``result.usage`` 이다.
 """
 from __future__ import annotations
 
 from pathlib import Path
 
-
-PRINT_MODE_USAGE_NOTE = "N/A — print mode exposes no transcript"
+from .jsonl_io import iter_jsonl
 
 
 def antigravity_session_total(json_path: Path) -> dict:
-    return {"totalTokens": 0, "available": False}
+    """stream-json 로그에서 마지막 result.usage 를 읽는다."""
+    result_usage: dict | None = None
+    step_usage: dict | None = None
+    model: str | None = None
+    for record in iter_jsonl(json_path):
+        kind = record.get("event")
+        if kind == "init":
+            init = record.get("init")
+            if isinstance(init, dict) and isinstance(init.get("model"), str):
+                model = init["model"]
+            continue
+        if kind == "result":
+            result = record.get("result")
+            if isinstance(result, dict) and isinstance(result.get("usage"), dict):
+                result_usage = result["usage"]
+            continue
+        if kind == "step_update":
+            step = record.get("step_update")
+            if isinstance(step, dict) and isinstance(step.get("usage"), dict):
+                step_usage = step["usage"]
+    usage = result_usage or step_usage
+    if usage is None:
+        return {"totalTokens": 0, "available": False}
+    return {
+        "totalTokens": usage.get("total_tokens", 0) or 0,
+        "inputTokens": usage.get("input_tokens", 0) or 0,
+        "outputTokens": usage.get("output_tokens", 0) or 0,
+        "thoughtsTokens": usage.get("thinking_tokens", 0) or 0,
+        "cacheReadTokens": usage.get("cache_read_tokens", 0) or 0,
+        "model": model,
+        "available": True,
+    }
 
 
 def find_antigravity_session(project_root: Path, started_at: str, ended_at: str) -> Path | None:
-    return None
+    sessions = find_antigravity_sessions(project_root, started_at, ended_at)
+    return sessions[-1] if sessions else None
 
 
 def find_antigravity_sessions(project_root: Path, started_at: str, ended_at: str) -> list[Path]:
+    # 세션 파일은 홈 디렉터리가 아니라 워커 로그다. 경로는 호출부가 prompt 에서 붙인다.
     return []