okstra 0.179.2 → 0.183.2

package/runtime/python/okstra_ctl/analysis_packet.py

@@ -101,6 +101,7 @@ def build_analysis_packet(
     instruction_set_relative_path: str,
     fix_history_text: str = "",
     stage_ledger_json: str = "",
+    stage_ledger_notice: str = "",
 ) -> str:
     """Return the primary compact input for Claude/Codex/Antigravity analysers."""
     brief_text = task_brief_path.read_text(encoding="utf-8")
@@ -124,9 +125,90 @@ def build_analysis_packet(
     parts.extend(_reference_block(reference_text))
     parts.extend(_fix_history_block(fix_history_text))
     parts.extend(_stage_ledger_block(stage_ledger_json))
+    parts.extend(_stage_ledger_unavailable_block(stage_ledger_notice))
     parts.extend(_clarification_block(clarification_text))
     parts.extend(_directive_block(directive))
-    return "\n".join(part.rstrip() for part in parts).rstrip() + "\n"
+    body = "\n".join(part.rstrip() for part in parts).rstrip() + "\n"
+    return _with_section_index(body)
+
+
+_HEADING_RE = re.compile(r"\A#{1,2} \S")
+_FENCE_RE = re.compile(r"\A\s*(```|~~~)")
+# 목차 자신이 차지하는 줄 수 중 표제 행을 뺀 나머지. 행 수는 표제 개수로
+# 정해지므로 삽입 전에 전체 이동량을 계산할 수 있다.
+_INDEX_PREAMBLE_LINES = 5
+
+
+def _with_section_index(body: str) -> str:
+    """Prefix the rendered packet with every section's line range.
+
+    The packet's own structure is the only thing a worker can navigate it by,
+    and a worker cannot navigate what it cannot see. Measured 2026-08-21: the
+    antigravity CLI's `view_file` truncates at 46,080 bytes per call, carries
+    no line-range parameter, and reports only `<n> lines, <m> bytes` — the same
+    string whether it returned the file or 40% of it. On a 114KB packet that
+    first call ended at line 510, so `## Stage Ledger` (572) and
+    `## Clarification Carry-In Extract` (680) never arrived and the worker
+    planned from the pre-migration brief that fills the first 42KB. Every
+    evidence line it cited was under 400. With the ranges here a truncated
+    reader can fetch the block it is missing by range instead of re-reading
+    the head; the lead had to write those ranges by hand to get a usable
+    retry.
+    """
+    lines = body.splitlines()
+    anchor = next(
+        (i for i, line in enumerate(lines)
+         if line.startswith("# OKSTRA Analysis Packet")),
+        None,
+    )
+    if anchor is None:
+        return body
+    headings = _heading_lines(lines)
+    if not headings:
+        return body
+    shift = _INDEX_PREAMBLE_LINES + len(headings)
+    total = len(lines) + shift
+    starts = [number + shift for number, _ in headings]
+    rows = [
+        f"- {start}-{end} `{text}`"
+        for start, end, (_, text) in zip(
+            starts, [nxt - 1 for nxt in starts[1:]] + [total], headings
+        )
+    ]
+    block = [
+        "",
+        "## Section Index",
+        "",
+        f"This packet is {total} lines. Read a section by line range with"
+        " `sed -n '<start>,<end>p'` rather than opening the whole file: a"
+        " whole-file read is truncated by some worker CLIs without reporting"
+        " it, and the sections that describe current state are last.",
+        "",
+        *rows,
+    ]
+    assert len(block) == shift, (len(block), shift)
+    return "\n".join(lines[:anchor + 1] + block + lines[anchor + 1:]) + "\n"
+
+
+def _heading_lines(lines: list[str]) -> list[tuple[int, str]]:
+    """Every `#`/`##` heading outside a fence, as (1-based line, text).
+
+    Fences are tracked because the Stage Ledger and the carried-in
+    clarification rows embed JSON and shell text where a `#` starts a comment,
+    not a section.
+    """
+    out: list[tuple[int, str]] = []
+    fenced = False
+    for number, line in enumerate(lines, start=1):
+        if _FENCE_RE.match(line):
+            fenced = not fenced
+            continue
+        if fenced or not _HEADING_RE.match(line):
+            continue
+        if line.startswith("# OKSTRA Analysis Packet"):
+            continue
+        out.append((number, line.strip()))
+    return out
 
 
 def _packet_frontmatter(brief_text: str, task_key: str) -> str:
@@ -240,8 +322,20 @@ def _stage_ledger_block(stage_ledger_json: str) -> list[str]:
         "",
         "Facts about this task's stages as they stand on disk — not a plan.",
         "A stage whose `status` is `done` is already implemented and will not",
-        "be executed again, so do not rewrite its plan body. Stage numbers",
-        "already listed here are taken; never reuse or renumber them.",
+        "be executed again, so do not rewrite its plan body.",
+        "",
+        "`stages` lists every stage the latest plan declares, so every number",
+        "in it is taken. Never reuse or renumber one: a new stage takes the",
+        "next number after the highest listed here, and reworking a completed",
+        "stage means cancelling it and adding a new number, never editing it",
+        "in place. `sourcePlan` is the plan the completed stages were built",
+        "against; `latestPlan` is the plan this list came from. When the two",
+        "differ, the completed work followed the former and the numbering",
+        "authority is the latter.",
+        "",
+        "A `planDivergence` entry means the two plans disagree about a",
+        "completed stage. Treat it as a blocker for any new stage number and",
+        "report it; do not resolve it by choosing one of the two yourself.",
         "",
         "```json",
         stage_ledger_json.strip(),
@@ -250,6 +344,33 @@ def _stage_ledger_block(stage_ledger_json: str) -> list[str]:
     ]
 
 
+def _stage_ledger_unavailable_block(notice: str) -> list[str]:
+    """원장을 못 읽었다는 사실을 packet 에 남긴다.
+
+    블록을 생략하면 저작 쪽은 "이전 계획이 없다" 로 읽는다 — 프로파일이 그렇게
+    지시한다. 계획이 있는데 못 읽은 경우에 그 침묵은 거짓이고, 이미 점유된
+    번호를 새 stage 에 다시 내주는 경로가 된다.
+    """
+    if not notice.strip():
+        return []
+    return [
+        "",
+        "## Stage Ledger",
+        "",
+        "This task's stage facts could NOT be read, so no ledger is included.",
+        "Do not read this as 'the task has no prior plan' — a plan exists and",
+        "this run could not parse it.",
+        "",
+        f"- Reason: {notice.strip()}",
+        "",
+        "Do not assign a number to any new stage in this state. A number taken",
+        "by a plan this run could not read would collide with the completed",
+        "work under it, and that collision stays silent until integration.",
+        "Report this as a blocker instead.",
+        "",
+    ]
+
+
 def _clarification_block(clarification_text: str) -> list[str]:
     if not clarification_text.strip():
         return []

package/runtime/python/okstra_ctl/approval_decisions.py

@@ -0,0 +1,328 @@
+"""선임 에이전트가 소유하는 승인 결정 입력 원장."""
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from copy import deepcopy
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Mapping, Sequence
+
+from .convergence_store import write_json_atomic
+from .json_boundary import JsonBoundaryError, load_owned_object
+
+
+DISPOSITIONS = frozenset({"select", "accept-risk", "request-revision", "reject"})
+REACHES = frozenset({"in-repo", "cross-repo"})
+SCOPE_EFFECTS = frozenset({"new-schema", "deferrable"})
+CLASSIFICATIONS = frozenset(
+    {"user-decision", "noncritical-dissent", "correctness-critical"}
+)
+_FORBIDDEN_BY_CLASSIFICATION = {
+    "correctness-critical": frozenset({"select", "accept-risk"}),
+    "noncritical-dissent": frozenset({"select"}),
+    "user-decision": frozenset(),
+}
+
+
+class ApprovalDecisionError(ValueError):
+    """승인 결정 입력이 역할 계약이나 선택지 불변식을 위반했다."""
+
+
+def _required(value: str, field: str) -> str:
+    if not isinstance(value, str) or not value.strip():
+        raise ApprovalDecisionError(f"{field} must be a non-empty string")
+    return value.strip()
+
+
+@dataclass(frozen=True)
+class DecisionOption:
+    role: str
+    answer: str
+    rationale: str
+    disposition: str
+    reach: str
+    scope_effects: tuple[str, ...]
+    added_work: str
+    direction_change: str
+
+    def __post_init__(self) -> None:
+        if self.role not in {"recommended", "alternative"}:
+            raise ApprovalDecisionError(f"invalid option role: {self.role}")
+        for field in ("answer", "rationale", "added_work", "direction_change"):
+            _required(getattr(self, field), field)
+        if self.disposition not in DISPOSITIONS:
+            raise ApprovalDecisionError(f"invalid disposition: {self.disposition}")
+        if self.reach not in REACHES:
+            raise ApprovalDecisionError(f"invalid reach: {self.reach}")
+        unknown = sorted(set(self.scope_effects) - SCOPE_EFFECTS)
+        if unknown or len(set(self.scope_effects)) != len(self.scope_effects):
+            raise ApprovalDecisionError(f"invalid scope_effects: {unknown}")
+
+    def to_payload(self) -> dict[str, Any]:
+        return {
+            "role": self.role,
+            "answer": self.answer,
+            "rationale": self.rationale,
+            "disposition": self.disposition,
+            "reach": self.reach,
+            "scopeEffects": list(self.scope_effects),
+            "addedWork": self.added_work,
+            "directionChange": self.direction_change,
+        }
+
+
+def _new_ledger(task_key: str, task_type: str, run_seq: str) -> dict[str, Any]:
+    return {
+        "schemaVersion": "1.0",
+        "owner": "lead",
+        "taskKey": _required(task_key, "task_key"),
+        "taskType": _required(task_type, "task_type"),
+        "runSeq": _required(run_seq, "run_seq"),
+        "activeClarifications": [],
+        "carriedDecisions": [],
+    }
+
+
+def _read_ledger(path: Path) -> dict[str, Any]:
+    try:
+        value = load_owned_object(path, artifact="approval decision ledger")
+    except JsonBoundaryError as exc:
+        raise ApprovalDecisionError(f"cannot read approval ledger {path}: {exc}") from exc
+    if not isinstance(value, dict) or value.get("owner") != "lead":
+        raise ApprovalDecisionError(f"approval ledger owner must be lead: {path}")
+    return value
+
+
+def _ledger(path: Path, task_key: str, task_type: str, run_seq: str) -> dict[str, Any]:
+    if not path.is_file():
+        return _new_ledger(task_key, task_type, run_seq)
+    ledger = _read_ledger(path)
+    expected = (task_key, task_type, run_seq)
+    actual = (ledger.get("taskKey"), ledger.get("taskType"), ledger.get("runSeq"))
+    if actual != expected:
+        raise ApprovalDecisionError("approval ledger identity does not match this run")
+    return ledger
+
+
+def _validate_option_set(
+    options: Sequence[DecisionOption], classification: str,
+    recommended_disposition: str,
+) -> None:
+    if len(options) < 2:
+        raise ApprovalDecisionError("a decision requires at least two options")
+    if sum(option.role == "recommended" for option in options) != 1:
+        raise ApprovalDecisionError("a decision requires exactly one recommended option")
+    forbidden = _FORBIDDEN_BY_CLASSIFICATION[classification]
+    used = {recommended_disposition, *(option.disposition for option in options)}
+    invalid = sorted(used & forbidden)
+    if invalid:
+        raise ApprovalDecisionError(f"{classification} forbids dispositions: {invalid}")
+    recommended = next(option for option in options if option.role == "recommended")
+    if recommended.disposition != recommended_disposition:
+        raise ApprovalDecisionError(
+            "recommended_disposition must match the recommended option"
+        )
+
+
+def _decision_row(
+    *, clarification_id: str, ticket_id: str, statement: str,
+    expected_form: str, classification: str, origin: str,
+    user_confirmation: str, unblock_condition: str,
+    recommended_disposition: str, options: Sequence[DecisionOption],
+) -> dict[str, Any]:
+    if classification not in CLASSIFICATIONS:
+        raise ApprovalDecisionError(f"invalid classification: {classification}")
+    if recommended_disposition not in DISPOSITIONS:
+        raise ApprovalDecisionError(
+            f"invalid recommended_disposition: {recommended_disposition}"
+        )
+    _validate_option_set(options, classification, recommended_disposition)
+    return {
+        "id": _required(clarification_id, "clarification_id"),
+        "ticketId": _required(ticket_id, "ticket_id"),
+        "kind": "decision",
+        "statement": _required(statement, "statement"),
+        "expectedForm": _required(expected_form, "expected_form"),
+        "blocks": "approval",
+        "origin": _required(origin, "origin"),
+        "userConfirmation": _required(user_confirmation, "user_confirmation"),
+        "approval": {
+            "classification": classification,
+            "unblockCondition": _required(unblock_condition, "unblock_condition"),
+            "recommendedDisposition": recommended_disposition,
+        },
+        "options": [option.to_payload() for option in options],
+    }
+
+
+def open_decision(
+    *, ledger_path: Path, task_key: str, task_type: str, run_seq: str,
+    clarification_id: str, ticket_id: str, statement: str, expected_form: str,
+    classification: str, origin: str, user_confirmation: str,
+    unblock_condition: str, recommended_disposition: str,
+    options: Sequence[DecisionOption],
+) -> None:
+    row = _decision_row(
+        clarification_id=clarification_id, ticket_id=ticket_id,
+        statement=statement, expected_form=expected_form,
+        classification=classification, origin=origin,
+        user_confirmation=user_confirmation, unblock_condition=unblock_condition,
+        recommended_disposition=recommended_disposition, options=options,
+    )
+    ledger = _ledger(ledger_path, task_key, task_type, run_seq)
+    active = ledger.get("activeClarifications")
+    if not isinstance(active, list):
+        raise ApprovalDecisionError("activeClarifications must be an array")
+    if any(item.get("id") == clarification_id for item in active if isinstance(item, Mapping)):
+        raise ApprovalDecisionError(f"duplicate active clarification: {clarification_id}")
+    active.append(row)
+    write_json_atomic(ledger_path, ledger)
+
+
+def resolve_decision(
+    ledger_path: Path, clarification_id: str, *, disposition: str,
+    user_text: str, user_response_ref: str, check_refs: Sequence[str],
+) -> None:
+    if disposition not in DISPOSITIONS:
+        raise ApprovalDecisionError(f"invalid disposition: {disposition}")
+    resolution = {
+        "disposition": disposition,
+        "userText": _required(user_text, "user_text"),
+        "userResponseRef": _required(user_response_ref, "user_response_ref"),
+        "checkRefs": [_required(ref, "check_refs") for ref in check_refs],
+    }
+    if not resolution["checkRefs"]:
+        raise ApprovalDecisionError("check_refs requires at least one value")
+    invalid_refs = [
+        ref for ref in resolution["checkRefs"]
+        if re.fullmatch(r"A-\d{3,}", ref) is None
+    ]
+    if invalid_refs:
+        raise ApprovalDecisionError(f"check_refs must be activity IDs: {invalid_refs}")
+    ledger = _read_ledger(ledger_path)
+    active = ledger.get("activeClarifications")
+    rows = active if isinstance(active, list) else []
+    matches = [row for row in rows if isinstance(row, dict) and row.get("id") == clarification_id]
+    if len(matches) != 1:
+        raise ApprovalDecisionError(f"active clarification not found: {clarification_id}")
+    matches[0]["resolutionInput"] = resolution
+    write_json_atomic(ledger_path, ledger)
+
+
+def carry_decision(
+    ledger_path: Path, *, source_run_ref: str, decision: Mapping[str, Any],
+) -> None:
+    ledger = _read_ledger(ledger_path)
+    carried = ledger.get("carriedDecisions")
+    if not isinstance(carried, list):
+        raise ApprovalDecisionError("carriedDecisions must be an array")
+    row = {
+        "sourceRunRef": _required(source_run_ref, "source_run_ref"),
+        "decision": deepcopy(dict(decision)),
+    }
+    if row not in carried:
+        carried.append(row)
+    write_json_atomic(ledger_path, ledger)
+
+
+def _options_from_args(args: argparse.Namespace) -> tuple[DecisionOption, ...]:
+    fields = (
+        args.option_role, args.option_answer, args.option_rationale,
+        args.option_disposition, args.option_reach, args.option_scope_effect,
+        args.option_added_work, args.option_direction_change,
+    )
+    if len({len(values) for values in fields}) != 1:
+        raise ApprovalDecisionError("every repeated option field needs the same count")
+    return tuple(
+        DecisionOption(role, answer, rationale, disposition, reach,
+                       tuple(effect.split(",")) if effect else (), added, direction)
+        for role, answer, rationale, disposition, reach, effect, added, direction
+        in zip(*fields, strict=True)
+    )
+
+
+def _add_open_arguments(parser: argparse.ArgumentParser) -> None:
+    required = (
+        "task-key", "task-type", "run-seq", "clarification-id", "ticket-id",
+        "statement", "expected-form", "classification", "origin",
+        "user-confirmation", "unblock-condition", "recommended-disposition",
+    )
+    for flag in required:
+        parser.add_argument(f"--{flag}", required=True)
+    repeated = (
+        "role", "answer", "rationale", "disposition", "reach",
+        "scope-effect", "added-work", "direction-change",
+    )
+    for flag in repeated:
+        parser.add_argument(f"--option-{flag}", action="append", default=[])
+
+
+def _parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="okstra approval-decision")
+    commands = parser.add_subparsers(dest="command", required=True)
+    opened = commands.add_parser("open")
+    opened.add_argument("--ledger", type=Path, required=True)
+    _add_open_arguments(opened)
+    resolved = commands.add_parser("resolve")
+    resolved.add_argument("--ledger", type=Path, required=True)
+    resolved.add_argument("--clarification-id", required=True)
+    resolved.add_argument("--disposition", required=True)
+    resolved.add_argument("--user-text", required=True)
+    resolved.add_argument("--user-response-ref", required=True)
+    resolved.add_argument("--check-ref", action="append", default=[])
+    carried = commands.add_parser("carry")
+    carried.add_argument("--ledger", type=Path, required=True)
+    carried.add_argument("--source-ledger", type=Path, required=True)
+    carried.add_argument("--source-run-ref", required=True)
+    carried.add_argument("--clarification-id", required=True)
+    return parser
+
+
+def _open_from_args(args: argparse.Namespace) -> None:
+    values = vars(args).copy()
+    values.pop("command")
+    values["ledger_path"] = values.pop("ledger")
+    for key in tuple(values):
+        if key.startswith("option_"):
+            values.pop(key)
+    open_decision(**values, options=_options_from_args(args))
+
+
+def _carry_from_args(args: argparse.Namespace) -> None:
+    source = _read_ledger(args.source_ledger)
+    rows = source.get("activeClarifications") or []
+    matches = [row for row in rows if isinstance(row, dict) and row.get("id") == args.clarification_id]
+    if len(matches) != 1:
+        raise ApprovalDecisionError(f"source clarification not found: {args.clarification_id}")
+    carry_decision(args.ledger, source_run_ref=args.source_run_ref, decision=matches[0])
+
+
+def _run(args: argparse.Namespace) -> None:
+    if args.command == "open":
+        _open_from_args(args)
+    elif args.command == "resolve":
+        resolve_decision(
+            args.ledger, args.clarification_id, disposition=args.disposition,
+            user_text=args.user_text, user_response_ref=args.user_response_ref,
+            check_refs=args.check_ref,
+        )
+    else:
+        _carry_from_args(args)
+
+
+def main(argv: list[str] | None = None) -> int:
+    try:
+        args = _parser().parse_args(argv)
+        _run(args)
+        print(json.dumps({"ok": True, "ledger": str(args.ledger)}, ensure_ascii=False))
+        return 0
+    except (ApprovalDecisionError, OSError) as exc:
+        print(f"approval-decision: {exc}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/runtime/python/okstra_ctl/attempt_evidence.py

@@ -12,6 +12,7 @@ from .domain.worker_stream import host_event_row
 from .execution_identity import Attempt, ExecutionManifestError
 from .execution_manifest import read_execution_manifest
 from .execution_manifest import _replace_manifest, _write_manifest_over_existing
+from .jsonl import append_jsonl
 from .run_context import task_mutex
 
 
@@ -104,8 +105,7 @@ class HostEventStreamWriter:
             payload=payload,
             timestamp=_utc_now(),
         )
-        with self.path.open("a", encoding="utf-8") as handle:
-            handle.write(json.dumps(row, ensure_ascii=False) + "\n")
+        append_jsonl(self.path, row, ensure_ascii=False, compact=False)
         return row
 
 

package/runtime/python/okstra_ctl/backfill.py

@@ -13,6 +13,7 @@ from .ids import build_run_id
 from .paths import runs_dir_of
 from .invocation import save_invocation
 from .jsonl import append_jsonl, read_jsonl, rotate_recent_if_needed
+from .json_boundary import JsonBoundaryError, load_owned_object, write_owned_object_atomic
 from .project_meta import _project_meta_path
 from .reconcile import _now_iso, normalize_central_status
 from .run_index_row import build_run_index_row
@@ -64,8 +65,8 @@ def discover_project_roots(home: Path) -> List[tuple]:
         if not meta_file.is_file():
             continue
         try:
-            meta = json.loads(meta_file.read_text())
-        except (OSError, json.JSONDecodeError):
+            meta = load_owned_object(meta_file, artifact="project metadata")
+        except JsonBoundaryError:
             continue
         pid = str(meta.get("projectId") or "")
         root = str(meta.get("projectRoot") or "")
@@ -89,7 +90,7 @@ def _apply_backfill_meta(home: Path, project_id: str, project_root: Path, *,
     target = _project_meta_path(home, project_id)
     target.parent.mkdir(parents=True, exist_ok=True)
     if target.is_file():
-        meta = json.loads(target.read_text())
+        meta = load_owned_object(target, artifact="project metadata")
     else:
         meta = {"projectId": project_id, "projectRoot": str(project_root),
                 "firstRunAt": "", "lastRunAt": "",
@@ -108,9 +109,7 @@ def _apply_backfill_meta(home: Path, project_id: str, project_root: Path, *,
     meta["runCount"] = int(meta.get("runCount", 0)) + run_count_inc
     meta["activeCount"] = max(
         0, int(meta.get("activeCount", 0)) + active_count_inc)
-    tmp = target.with_suffix(".json.tmp")
-    tmp.write_text(json.dumps(meta, indent=2) + "\n")
-    os.replace(tmp, target)
+    write_owned_object_atomic(target, meta, artifact="project metadata")
 
 
 def backfill_project(home: Path, project_id: str, project_root: Path) -> int:
@@ -142,8 +141,8 @@ def backfill_project(home: Path, project_id: str, project_root: Path) -> int:
                     task_type = m.group("tt")
                     seq = int(m.group("seq"))
                     try:
-                        manifest = json.loads(mf.read_text())
-                    except (OSError, json.JSONDecodeError):
+                        manifest = load_owned_object(mf, artifact="run manifest")
+                    except JsonBoundaryError:
                         # 부분 기록 / 손상된 매니페스트를 빈 dict 로 강등해 row 를
                         # 만들면, 빈 status 가 'completed' 로 normalize 되어
                         # recent 에 박히고, 같은 runId 가 existing_ids 로 인덱싱
@@ -268,6 +267,10 @@ def backfill_project(home: Path, project_id: str, project_root: Path) -> int:
 
 def mark_backfilled(home: Path) -> None:
     state_file = home / "state.json"
-    state = json.loads(state_file.read_text()) if state_file.is_file() else {}
+    state = (
+        load_owned_object(state_file, artifact="okstra home state")
+        if state_file.is_file()
+        else {}
+    )
     state["backfilledAt"] = _now_iso()
-    state_file.write_text(json.dumps(state, indent=2) + "\n")
+    write_owned_object_atomic(state_file, state, artifact="okstra home state")

package/runtime/python/okstra_ctl/batch.py

@@ -9,6 +9,7 @@ from pathlib import Path
 from typing import List, Optional
 
 from .listing import list_runs
+from .json_boundary import write_owned_object_atomic
 from .resolver import resolve_last, resolve_run_id
 
 
@@ -20,10 +21,7 @@ def make_batch_id() -> str:
 
 def write_batch_meta(home: Path, batch_id: str, payload: dict) -> Path:
     target = home / "batches" / f"{batch_id}.json"
-    target.parent.mkdir(parents=True, exist_ok=True)
-    tmp = target.with_suffix(".json.tmp")
-    tmp.write_text(json.dumps(payload, indent=2) + "\n")
-    os.replace(tmp, target)
+    write_owned_object_atomic(target, payload, artifact="batch metadata")
     return target
 
 

package/runtime/python/okstra_ctl/build_tools.py

@@ -16,6 +16,8 @@ import json
 import shlex
 from pathlib import Path
 
+from .json_boundary import JsonBoundaryError, load_owned_object
+
 DEFAULT_BUILD_TOOL_TOKENS: tuple[str, ...] = (
     "npm",
     "yarn",
@@ -49,10 +51,11 @@ def resolve_build_tool_tokens(project_root: Path) -> tuple[str, ...]:
     uses, so one rule covers both.
     """
     try:
-        payload = json.loads(
-            (Path(project_root) / ".okstra" / "project.json").read_text(encoding="utf-8")
+        payload = load_owned_object(
+            Path(project_root) / ".okstra" / "project.json",
+            artifact="project configuration",
         )
-    except (OSError, json.JSONDecodeError):
+    except JsonBoundaryError:
         return DEFAULT_BUILD_TOOL_TOKENS
     configured = payload.get("buildToolTokens") if isinstance(payload, dict) else None
     if not isinstance(configured, list):