okstra 0.186.7 → 0.188.0

package/runtime/python/okstra_ctl/doctor_cli.py

@@ -0,0 +1,48 @@
+"""`okstra doctor` 가 부르는 진단 프로젝션.
+
+진단 로직 자체는 `okstra_ctl.doctor` 에 있다. 이 모듈은 그것을 CLI 경계로
+노출하기만 한다 — 원래 `src/commands/lifecycle/doctor.mts` 의 문자열 리터럴
+안에 있던 두 스니펫을 옮긴 것이다(docs/coding-rules.md R1 위반).
+"""
+from __future__ import annotations
+
+import argparse
+import json
+
+from .doctor import model_pool_diagnostics, phase_diagnostics
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="okstra doctor")
+    sub = parser.add_subparsers(dest="op", required=True)
+
+    pool = sub.add_parser("model-pool")
+    pool.add_argument("--host-runtime", default="claude-code")
+    pool.add_argument("--cwd", required=True)
+
+    phase = sub.add_parser("phase")
+    phase.add_argument("--phase", required=True)
+    phase.add_argument("--cwd", required=True)
+    phase.add_argument("--workspace-root", required=True)
+    # `--home` 은 사용자 홈이다. 에이전트 설치 루트가 `<home>/.claude/agents` 라서
+    # okstra 홈(~/.okstra)을 넘기면 모든 worker-agent 점검이 없는 경로를 짚는다.
+    phase.add_argument("--home", required=True)
+    phase.add_argument("--host-runtime", default="")
+
+    args = parser.parse_args(argv)
+    if args.op == "model-pool":
+        payload = model_pool_diagnostics(host_runtime=args.host_runtime, cwd=args.cwd)
+    else:
+        payload = phase_diagnostics(
+            args.phase,
+            cwd=args.cwd,
+            workspace_root=args.workspace_root,
+            home=args.home,
+            host_runtime=args.host_runtime,
+        )
+    print(json.dumps(payload, ensure_ascii=False))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

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

@@ -12,9 +12,12 @@ from pathlib import Path
 from typing import Literal, Protocol, runtime_checkable
 
 from .worker_presentation import Presentation
-from ..write_policy import WriteEnforcement, WritePolicy
+from .write_policy import WriteEnforcement, WritePolicy
 
 SERVED_MODEL_MISMATCH_EXIT_CODE = 78
+# JSON 이벤트 스트림이 result 이벤트 없이 깨끗하게(exit 0) 끝난 run.
+# CLI 가 성공을 주장했지만 답을 내지 않았다 — sysexits 의 EX_PROTOCOL.
+NO_RESULT_EXIT_CODE = 76
 
 
 @dataclass(frozen=True)
@@ -22,10 +25,12 @@ class ExecutionPolicy:
     """How a non-interactive worker is allowed to act.
 
     Identical for every worker: nobody is at the keyboard to answer an approval
-    prompt, so the gate has to be open and the boundary has to come from a
-    sandbox instead. Declared once here rather than per provider, because a
-    policy that lives in one adapter file per provider drifts into one policy
-    per provider.
+    prompt, so the gate has to be open. No provider CLI enforces a sandbox
+    boundary any more, so `write_scope` is what the worker is told to write, not
+    what it is prevented from leaving — `write_policy` and `write_enforcement`
+    are what the run checks after the fact. Declared once here rather than per
+    provider, because a policy that lives in one adapter file per provider
+    drifts into one policy per provider.
     """
 
     auto_approve: bool

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

@@ -30,6 +30,8 @@ Sink = Callable[[str], str | None]
 Channel = Literal["stdout", "stderr"]
 SinkSpec = tuple[Channel, Sink]
 ObserveServedModel = Callable[[Mapping[str, Any]], str | None]
+# 이벤트가 실어 온 토큰 사용량 스냅샷(공급자 어휘 그대로). 없으면 None.
+ObserveUsage = Callable[[Mapping[str, Any]], Mapping[str, Any] | None]
 
 WORKER = "worker"
 
@@ -113,15 +115,33 @@ class JsonEvents:
 
     normalise: Normalise
     observe: ObserveServedModel
+    # 어떤 CLI 는 토큰 사용량을 홈 디렉터리의 트랜스크립트가 아니라 이 스트림에만
+    # 싣는다(agy 의 `result.usage`). 어댑터가 그 스냅샷을 읽는 법을 넘기면
+    # 러너가 마지막 값을 status 사이드카에 적어, 수집기가 로그를 다시 파싱하지
+    # 않아도 된다. 어느 CLI 가 그런지는 이 계층이 알 필요도, 알아서도 안 된다.
+    observe_usage: ObserveUsage | None = None
     # 어떤 CLI 의 streaming-json 은 문장이 아니라 토큰을 한 줄씩 보낸다. 붙이지
     # 않으면 pane 이 한 글자 한 줄이 된다. 기본은 끄고, 그런 CLI 의 어댑터가 켠다 —
     # 어느 CLI 가 그런지는 이 계층이 알 필요도, 알아서도 안 되는 사실이다.
     join_adjacent_text: bool = False
+    # 이 어휘에서 "정상 종결" 을 뜻하는 원시 이벤트. 기본은 Result 이벤트지만,
+    # 어떤 CLI 의 어휘에는 Result 가 없고 별도의 종결 이벤트가 있다 — 어댑터가
+    # 자기 어휘의 표지를 넘긴다. 어느 CLI 가 그런지는 이 계층이 알 필요도,
+    # 알아서도 안 되는 사실이다. 판정 없이는 그런 CLI 의 건강한 run 전부가
+    # 결과 부재로 강등된다.
+    is_conclusion: Callable[[Mapping[str, Any]], bool] | None = None
     _pending_text: list[str] = field(default_factory=list, repr=False, compare=False)
+    _saw_conclusion: list[bool] = field(
+        default_factory=list, repr=False, compare=False
+    )
 
     def merges_stderr(self) -> bool:
         return True
 
+    def concluded(self) -> bool:
+        """스트림이 이 어휘의 종결 표지로 끝났는가."""
+        return bool(self._saw_conclusion)
+
     def sinks(self, writer: TranscriptWriter) -> tuple[SinkSpec, ...]:
         def emit(line: str) -> str | None:
             stripped = line.strip()
@@ -138,6 +158,8 @@ class JsonEvents:
             if not isinstance(event, dict):
                 return None
             self.observe(event)
+            if self.is_conclusion is not None and self.is_conclusion(event):
+                self._saw_conclusion.append(True)
             closing: str | None = None
             for entry in self.normalise(event):
                 closing = self._write_entry(writer, entry) or closing
@@ -164,7 +186,12 @@ class JsonEvents:
             screen=format_live(entry),
             archive=format_log(entry),
         )
-        return final_text(entry)
+        closing = final_text(entry)
+        if closing is not None:
+            # Result 이벤트는 어휘와 무관한 종결이다. 빈 결과 텍스트도 종결이므로
+            # closing_text 의 진릿값과 따로 기록한다.
+            self._saw_conclusion.append(True)
+        return closing
 
     def _publish_complete_lines(self, writer: TranscriptWriter) -> None:
         combined = "".join(self._pending_text)

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

@@ -12,9 +12,10 @@ to be worth a default here — ``content_block_events``, whose events are keyed
 provider, and an adapter that speaks something else says so in its own file.
 
 Screen output folds what the log keeps in full — a tool call becomes one line, a
-tool result becomes an outcome and a size. Thinking is dropped at normalisation,
-which is safe only because worker liveness is measured from stream arrival
-rather than from log writes (see the spec's 7.2).
+tool result becomes an outcome, a size, and the first few rows of what came
+back. Thinking is dropped at normalisation, which is safe only because worker
+liveness is measured from stream arrival rather than from log writes (see the
+spec's 7.2).
 
 Three projections of the same stream: ``format_live`` for the pane,
 ``format_log`` for the archive, and ``final_text`` for the caller that must
@@ -31,6 +32,14 @@ from typing import Any, Callable, Mapping
 # previous one off the top of a short pane.
 _MAX_SUMMARY = 120
 
+# 화면이 받는 도구 결과 본문의 줄 수. 0 줄이던 동안 pane 에 남는 것은 성패와
+# 바이트 수뿐이었다. 어떤 어댑터가 본문 대신 도구 이름표를 넘겨 모든 호출이
+# 한 자릿수 바이트로 보이던 run 을, 화면만 보고는 아무도 판별하지 못했다.
+# 결과 하나가 pane 을 다 차지하면 직전 호출이 위로 밀려 나가므로 앞부분만
+# 보여주고, 나머지는 로그가 갖는다.
+_LIVE_BODY_ROWS = 4
+_BODY_INDENT = "    "
+
 
 @dataclass(frozen=True)
 class Text:
@@ -58,11 +67,20 @@ class ToolResult:
     ``failed`` is None when the stream closed the tool step without reporting an
     outcome at all. Reading that absence as success would put a confident "ok"
     next to a command that failed.
+
+    ``body_describes_result`` marks a tool that reported *about* its result
+    instead of returning it — a file read that answers ``54 lines, 4293 bytes``
+    rather than the 4293 bytes. Without the mark the two are the same shape and
+    the size reads as the payload, so a 4293-byte read is archived as
+    ``← done (20 bytes)`` and a reader concludes the read came back nearly
+    empty. The provider that emits such a report says so; this layer only
+    renders it differently.
     """
 
     body: str
     size_bytes: int
     failed: bool | None = None
+    body_describes_result: bool = False
 
 
 @dataclass(frozen=True)
@@ -112,17 +130,6 @@ def host_event_row(
     return row
 
 
-def no_events(event: Mapping[str, Any]) -> tuple[StreamEvent, ...]:
-    """The normaliser for a CLI that emits no events at all.
-
-    A text CLI's output is already what a person reads, so the runner forwards
-    it whole and never calls this. It exists so ``ExecCommand`` can default to
-    a truthful "there is nothing here to normalise" instead of to some
-    provider's schema.
-    """
-    return ()
-
-
 def content_block_events(event: Mapping[str, Any]) -> tuple[StreamEvent, ...]:
     """Normalise the stream shape keyed on ``type`` with ``message.content``.
 
@@ -157,7 +164,7 @@ def content_block_events(event: Mapping[str, Any]) -> tuple[StreamEvent, ...]:
 
 
 def format_live(event: StreamEvent) -> list[str]:
-    return _rows(event, limit=_MAX_SUMMARY, include_body=False)
+    return _rows(event, limit=_MAX_SUMMARY, body_rows=_LIVE_BODY_ROWS)
 
 
 def format_log(event: StreamEvent) -> list[str]:
@@ -167,7 +174,7 @@ def format_log(event: StreamEvent) -> list[str]:
     the fact, by a person reconstructing why a worker failed and by
     ``okstra log-report``.
     """
-    return _rows(event, limit=None, include_body=True)
+    return _rows(event, limit=None, body_rows=None)
 
 
 def final_text(event: StreamEvent) -> str | None:
@@ -175,17 +182,24 @@ def final_text(event: StreamEvent) -> str | None:
     return event.text if isinstance(event, Result) else None
 
 
-def _rows(event: StreamEvent, *, limit: int | None, include_body: bool) -> list[str]:
+def _rows(event: StreamEvent, *, limit: int | None, body_rows: int | None) -> list[str]:
     if isinstance(event, Text):
         return _body_rows(event.body)
     if isinstance(event, ToolCall):
         head = f"→ {event.name}: {event.detail}" if event.detail else f"→ {event.name}"
         return [_truncate(head, limit)]
     if isinstance(event, ToolResult):
-        rows = [f"  ← {_outcome(event.failed)} ({event.size_bytes} bytes)"]
-        if include_body:
-            rows.extend(_body_rows(event.body))
-        return rows
+        if event.body_describes_result:
+            # 크기를 싣지 않는다. 이 이벤트가 가진 숫자는 보고 문자열의 길이일
+            # 뿐이고(보고조차 없으면 0), 그것을 payload 자리에 놓는 것이 오독의
+            # 출처였다.
+            report = " ".join(event.body.split())
+            tail = (
+                f"the tool reported: {report}" if report else "the tool reported nothing"
+            )
+            return [_truncate(f"  ← {_outcome(event.failed)} — no body returned; {tail}", limit)]
+        head = f"  ← {_outcome(event.failed)} ({event.size_bytes} bytes)"
+        return [head, *_result_body(event.body, limit=limit, keep=body_rows)]
     if isinstance(event, Denial):
         return [_truncate(f"!! PERMISSION DENIED — {event.tool}: {event.reason}", limit)]
     # A Result is printed by the runner at the point the run ends, not woven
@@ -193,6 +207,23 @@ def _rows(event: StreamEvent, *, limit: int | None, include_body: bool) -> list[
     return []
 
 
+def _result_body(body: str, *, limit: int | None, keep: int | None) -> list[str]:
+    """결과 본문을 몇 줄 보여줄지 정한다.
+
+    `keep is None` 이 기록의 몫이다 — 전부 남긴다. 화면은 앞 몇 줄만 받고,
+    생략한 줄 수를 밝힌다. 밝히지 않으면 짧은 출력과 잘린 출력이 같은 모양이
+    되어, 읽는 사람이 로그를 열 이유를 알 수 없다.
+    """
+    rows = _body_rows(body)
+    if keep is None:
+        return rows
+    shown = [_truncate(_BODY_INDENT + row, limit) for row in rows[:keep]]
+    dropped = len(rows) - keep
+    if dropped > 0:
+        shown.append(f"{_BODY_INDENT}… +{dropped} more line(s) — full body in the log")
+    return shown
+
+
 def _outcome(failed: bool | None) -> str:
     if failed is None:
         return "done"

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

@@ -0,0 +1,219 @@
+"""쓰기 정책 값 타입 · 직렬화 · 검증.
+
+`..write_policy`(623줄) 안에 있던 값 코어를 도메인으로 내렸다. 그 모듈은
+git 을 실행하고 run manifest 를 읽는 응용 로직인데, `domain/worker_exec.py` 가
+`WritePolicy` / `WriteEnforcement` 타입 하나 때문에 그 응용 모듈을 최상위
+import 하고 있었다 — 도메인이 응용을 부르는 역전이고, 그 탓에
+`write_policy → path_hints` 가 함수 본문 지연 import 로 밀려나 있었다.
+
+값과 그 값의 정합성(직렬화·다이제스트·payload 검증)까지가 여기다.
+정책을 **만들거나**(build_*) **유도하는**(derive_*) 일은 응용에 남는다.
+`..write_policy` 가 이 이름들을 재노출하므로 기존 호출부는 바뀌지 않는다.
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass
+from pathlib import Path, PurePosixPath
+from typing import Any, Literal
+
+
+BoundaryPrecision = Literal["exact-path", "directory-boundary", "none"]
+
+_PRECISION_RANK = {"none": 0, "directory-boundary": 1, "exact-path": 2}
+
+_POLICY_KEYS = {
+    "artifactPolicy",
+    "sourcePolicy",
+    "gitPolicy",
+    "auxiliaryPolicy",
+}
+
+_ENFORCEMENT_KEYS = {
+    "boundaryPrecision",
+    "mutationAudit",
+    "attribution",
+    "auditedRoots",
+    "observationCoverage",
+    "unobservedWriteSurfaces",
+}
+
+class WritePolicyError(ValueError):
+    """Raised when a write policy cannot be made canonical or trustworthy."""
+
+@dataclass(frozen=True)
+class WritePolicy:
+    artifact_policy: Mapping[str, Any]
+    source_policy: Mapping[str, Any]
+    git_policy: Mapping[str, Any]
+    auxiliary_policy: Mapping[str, Any]
+    maximum_boundary_precision: BoundaryPrecision = "none"
+
+    def to_payload(self) -> dict[str, Any]:
+        return {
+            "artifactPolicy": dict(self.artifact_policy),
+            "sourcePolicy": dict(self.source_policy),
+            "gitPolicy": dict(self.git_policy),
+            "auxiliaryPolicy": dict(self.auxiliary_policy),
+        }
+
+    @property
+    def digest(self) -> str:
+        return write_policy_digest(self.to_payload())
+
+    @property
+    def source_mode(self) -> str:
+        return str(self.source_policy["mode"])
+
+@dataclass(frozen=True)
+class WriteEnforcement:
+    boundary_precision: BoundaryPrecision
+    mutation_audit: Literal["none", "batch"]
+    attribution: Literal["call", "batch-unattributed"]
+    audited_roots: tuple[Path, ...]
+    observation_coverage: Literal["complete", "scoped", "partial"]
+    unobserved_write_surfaces: tuple[str, ...]
+
+    def to_payload(self) -> dict[str, Any]:
+        return {
+            "boundaryPrecision": self.boundary_precision,
+            "mutationAudit": self.mutation_audit,
+            "attribution": self.attribution,
+            "auditedRoots": [str(path) for path in self.audited_roots],
+            "observationCoverage": self.observation_coverage,
+            "unobservedWriteSurfaces": list(self.unobserved_write_surfaces),
+        }
+
+def write_policy_from_payload(payload: Mapping[str, Any]) -> WritePolicy:
+    validate_write_policy_payload(payload)
+    return WritePolicy(
+        artifact_policy=dict(payload["artifactPolicy"]),
+        source_policy=dict(payload["sourcePolicy"]),
+        git_policy=dict(payload["gitPolicy"]),
+        auxiliary_policy=dict(payload["auxiliaryPolicy"]),
+    )
+
+def write_enforcement_from_payload(
+    payload: Mapping[str, Any],
+) -> WriteEnforcement:
+    validate_write_enforcement_payload(payload)
+    return WriteEnforcement(
+        boundary_precision=payload["boundaryPrecision"],
+        mutation_audit=payload["mutationAudit"],
+        attribution=payload["attribution"],
+        audited_roots=tuple(Path(value) for value in payload["auditedRoots"]),
+        observation_coverage=payload["observationCoverage"],
+        unobserved_write_surfaces=tuple(payload["unobservedWriteSurfaces"]),
+    )
+
+def write_policy_digest(payload: Mapping[str, Any]) -> str:
+    validate_write_policy_payload(payload)
+    encoded = json.dumps(
+        payload,
+        sort_keys=True,
+        separators=(",", ":"),
+        ensure_ascii=False,
+    ).encode("utf-8")
+    return "sha256:" + hashlib.sha256(encoded).hexdigest()
+
+def validate_write_policy_payload(payload: Mapping[str, Any]) -> None:
+    if set(payload) != _POLICY_KEYS:
+        raise WritePolicyError("writePolicy must contain four canonical policy sections")
+    artifact = _mapping(payload.get("artifactPolicy"), "artifactPolicy")
+    source = _mapping(payload.get("sourcePolicy"), "sourcePolicy")
+    git = _mapping(payload.get("gitPolicy"), "gitPolicy")
+    auxiliary = _mapping(payload.get("auxiliaryPolicy"), "auxiliaryPolicy")
+    if set(artifact) != {"allowedRoot", "allowedPaths"}:
+        raise WritePolicyError("artifactPolicy is incomplete")
+    _absolute_text(artifact.get("allowedRoot"), "artifactPolicy.allowedRoot")
+    _relative_paths(artifact.get("allowedPaths", ()))
+    if source.get("mode") not in {"source-readonly", "project-mutation"}:
+        raise WritePolicyError("sourcePolicy mode is invalid")
+    if set(source) != {"mode", "allowedRoot", "plannedPaths", "protectedPaths"}:
+        raise WritePolicyError("sourcePolicy is incomplete")
+    _absolute_text(source.get("allowedRoot"), "sourcePolicy.allowedRoot")
+    _relative_paths(source.get("plannedPaths", ()))
+    _relative_paths(source.get("protectedPaths", ()))
+    if git.get("mode") not in {"disabled", "fast-forward-descendant-chain"}:
+        raise WritePolicyError("gitPolicy mode is invalid")
+    if git.get("mode") == "disabled" and set(git) != {"mode"}:
+        raise WritePolicyError("disabled gitPolicy must not grant Git paths")
+    required_git = {
+        "mode", "worktreeGitDir", "gitCommonDir", "expectedBaseCommit",
+        "allowedBranchRef", "commitMode",
+    }
+    if git.get("mode") != "disabled" and set(git) != required_git:
+        raise WritePolicyError("project mutation gitPolicy is incomplete")
+    if set(auxiliary) != {"scratchRoots", "generatedPaths", "externalRoots"}:
+        raise WritePolicyError("auxiliaryPolicy is incomplete")
+    _relative_paths(auxiliary.get("generatedPaths", ()))
+    for key in ("scratchRoots", "externalRoots"):
+        for value in _text_sequence(auxiliary.get(key), f"auxiliaryPolicy.{key}"):
+            _absolute_text(value, f"auxiliaryPolicy.{key}")
+
+def validate_write_enforcement_payload(payload: Mapping[str, Any]) -> None:
+    if set(payload) != _ENFORCEMENT_KEYS:
+        raise WritePolicyError("writeEnforcement is incomplete")
+    boundary = payload.get("boundaryPrecision")
+    mutation_audit = payload.get("mutationAudit")
+    attribution = payload.get("attribution")
+    coverage = payload.get("observationCoverage")
+    if boundary not in _PRECISION_RANK:
+        raise WritePolicyError("writeEnforcement boundaryPrecision is invalid")
+    if mutation_audit not in {"none", "batch"}:
+        raise WritePolicyError("writeEnforcement mutationAudit is invalid")
+    if attribution not in {"call", "batch-unattributed"}:
+        raise WritePolicyError("writeEnforcement attribution is invalid")
+    if coverage not in {"complete", "scoped", "partial"}:
+        raise WritePolicyError("writeEnforcement observationCoverage is invalid")
+    if (boundary, mutation_audit, attribution) == ("exact-path", "none", "call"):
+        if coverage != "complete":
+            raise WritePolicyError("exact enforcement must have complete coverage")
+    elif (boundary, mutation_audit, attribution) == (
+        "none",
+        "none",
+        "batch-unattributed",
+    ):
+        if coverage != "partial":
+            raise WritePolicyError("host-session enforcement must be partial")
+    elif mutation_audit != "batch" or attribution != "batch-unattributed":
+        raise WritePolicyError("non-exact enforcement must use batch attribution")
+    elif boundary == "exact-path" or coverage == "complete":
+        raise WritePolicyError("batch enforcement cannot claim exact coverage")
+    for root in _text_sequence(payload.get("auditedRoots"), "auditedRoots"):
+        _absolute_text(root, "auditedRoots")
+    _text_sequence(payload.get("unobservedWriteSurfaces"), "unobservedWriteSurfaces")
+
+def _relative_paths(value: object) -> tuple[str, ...]:
+    paths: list[str] = []
+    for raw in _text_sequence(value, "relative paths"):
+        candidate = PurePosixPath(raw)
+        if candidate.is_absolute() or not candidate.parts or ".." in candidate.parts:
+            raise WritePolicyError("policy paths must be normalized relative paths")
+        normalized = candidate.as_posix()
+        if normalized in {"", "."} or normalized != raw:
+            raise WritePolicyError("policy paths must be normalized relative paths")
+        paths.append(normalized)
+    if len(set(paths)) != len(paths):
+        raise WritePolicyError("policy paths must be unique")
+    return tuple(paths)
+
+def _mapping(value: object, label: str) -> Mapping[str, Any]:
+    if not isinstance(value, Mapping):
+        raise WritePolicyError(f"{label} must be an object")
+    return value
+
+def _text_sequence(value: object, label: str) -> tuple[str, ...]:
+    if not isinstance(value, Sequence) or isinstance(value, (str, bytes)):
+        raise WritePolicyError(f"{label} must be an array")
+    rows = tuple(value)
+    if any(not isinstance(row, str) or not row for row in rows):
+        raise WritePolicyError(f"{label} must contain non-empty strings")
+    return rows
+
+def _absolute_text(value: object, label: str) -> str:
+    if not isinstance(value, str) or not value or not Path(value).is_absolute():
+        raise WritePolicyError(f"{label} must be an absolute path")
+    return value

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

@@ -9,7 +9,7 @@ from contextlib import contextmanager
 from dataclasses import asdict
 from pathlib import Path
 
-from ..agent_invocation import (
+from ..agent.invocation import (
     AgentInvocationError,
     AgentModelAssignment,
     agent_model_assignment_from_payload,
@@ -113,7 +113,7 @@ def _build_parser() -> argparse.ArgumentParser:
     resolve.add_argument(
         "--capability",
         action="append",
-        choices=("claude-skill-handoff", "tmux"),
+        choices=("claude-skill-handoff",),
         default=[],
     )
     launch = commands.add_parser("launch-plan")
@@ -200,9 +200,16 @@ def _probe_payload(
     status = "unknown" if "unavailable" in statuses else (
         "ready" if readiness.ok else "blocked"
     )
+    # A check may report that this session cannot host the lead while the run
+    # itself is fine. The caller needs the mode it must actually launch in, not
+    # the mode it asked about, so the probe answers with the resolved one.
+    entry_mode = (
+        "spawn-process" if "lead-must-spawn" in statuses else args.entry_mode
+    )
     return {
         "runtime": adapter.descriptor.id,
         "status": status,
+        "entryMode": entry_mode,
         "checks": list(readiness.checks),
         "relayContract": adapter.descriptor.relay_contract,
     }

package/runtime/python/okstra_ctl/error_log_core.py

@@ -37,7 +37,7 @@ def parse_records(paths: list[Path]) -> tuple[list[dict], int]:
                 continue
             try:
                 rec = json.loads(line)
-            except Exception:
+            except (ValueError, TypeError):
                 skipped += 1
                 continue
             if isinstance(rec, dict):

package/runtime/python/okstra_ctl/error_report.py

@@ -210,8 +210,22 @@ def render_result_text(result: dict) -> str:
     return "".join(parts)
 
 
+_CLI_EPILOG = r"""Usage:
+  okstra error-report <task-root>
+  okstra error-report <task-key> --project-root <dir>
+  okstra error-report <task-key> --cwd <dir>
+
+Writes a timestamped markdown report under <task-root>/error-reports/ and
+prints a JSON summary (counts by errorType / source / phase / agent) to stdout.
+This is read-only against task state; it never mutates task artifacts.
+"""
+
+
 def main(argv: list[str] | None = None) -> int:
     parser = argparse.ArgumentParser(
+        prog="okstra error-report",
+        epilog=_CLI_EPILOG,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
         description="Aggregate okstra-run error logs into a task-level report."
     )
     parser.add_argument("target", help="task root path or task-key")

package/runtime/python/okstra_ctl/error_zip.py

@@ -19,7 +19,11 @@ 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
+from okstra_ctl.json_boundary import (
+    JsonBoundaryError,
+    load_owned_object,
+    write_owned_object_atomic,
+)
 
 
 def run_dirs(home: Path) -> list[tuple[str, Path, dict]]:
@@ -282,7 +286,7 @@ def last_output_path(home: Path) -> str:
                 "lastOutputPath", ""
             )
         )
-    except Exception:
+    except JsonBoundaryError:
         return ""
 
 
@@ -335,8 +339,20 @@ def render_result_text(result: dict) -> str:
     return "".join(lines)
 
 
+_CLI_EPILOG = r"""Usage:
+  okstra error-zip --out <path>
+
+Walks the global run-index (~/.okstra/recent.jsonl + active.jsonl), collects
+every target project's runs/*/logs/errors-*.jsonl, anonymizes records, and
+writes a .zip (report.md + errors/anonymized.jsonl) to <path>. Read-only
+against every target's .okstra/. Prints a JSON summary to stdout.
+"""
+
+
 def main(argv: list[str] | None = None) -> int:
     parser = argparse.ArgumentParser(
+        epilog=_CLI_EPILOG,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
         prog="okstra error-zip",
         description="cross-project okstra 에러를 수집·익명화해 zip 으로 묶는다.",
     )

package/runtime/python/okstra_ctl/exact_coverage.py

@@ -7,6 +7,11 @@ from dataclasses import dataclass
 from typing import Literal
 
 
+# 판정 우선순위 — 여러 조건이 동시에 성립할 때 앞선 것이 이긴다. 저작 계약이
+# 이 순서를 작성자에게 말하므로 `calculate_exact_coverage` 의 분기와 함께 간다.
+COVERAGE_VERDICT_PRECEDENCE = ("contradicted", "under", "over", "exact")
+
+
 class ExactCoverageError(ValueError):
     """Raised when coverage input cannot define a valid comparison."""