okstra 0.202.0 → 0.204.0

package/runtime/python/okstra_ctl/agent/prompt_cli/run_identity.py

@@ -58,56 +58,7 @@ def _validate_run_identity(
             ).duty_audience
         except ValueError as exc:
             raise AgentPromptCliError(str(exc)) from exc
-        if audience != expected and _manifest_issued_role_execution(
-            manifest, audience=audience, assignment_ref=assignment_ref
-        ):
-            # The prompt plan names a worker's role by worker id, so on an
-            # implementation run the executor's provider resolves to the
-            # executor role no matter which role execution is being targeted.
-            # But the manifest issues one role execution per role, and a
-            # provider serving as both executor and verifier gets two — a
-            # normal roster, since the verifier contract accepts reusing the
-            # executor's model behind its own session. Refusing the second
-            # audience made a role execution okstra had itself issued
-            # undispatchable, which costs the run an independent verifier.
-            expected = audience
     if audience != expected:
         raise AgentPromptCliError(
             f"audience {audience!r} does not match required audience {expected!r}"
         )
-
-
-def _manifest_issued_role_execution(
-    manifest: Mapping[str, Any],
-    *,
-    audience: str,
-    assignment_ref: str,
-) -> bool:
-    """Whether this run issued a role execution for that audience's role.
-
-    Keyed on the manifest's own rows, not on what the prompt plan infers from
-    a worker id: the question is whether okstra created the execution being
-    targeted, and only the manifest answers that.
-    """
-    from ...domain.role import RoleCatalogError, role_for_duty
-
-    try:
-        role = role_for_duty(audience)
-    except RoleCatalogError:
-        return False
-    assignments = manifest.get("invocationAssignments")
-    assignment = (
-        assignments.get(assignment_ref) if isinstance(assignments, Mapping) else None
-    )
-    provider = (
-        assignment.get("provider") if isinstance(assignment, Mapping) else None
-    )
-    if not provider:
-        return False
-    executions = manifest.get("roleExecutions")
-    return any(
-        isinstance(row, Mapping)
-        and row.get("role") == role
-        and row.get("provider") == provider
-        for row in (executions if isinstance(executions, list) else [])
-    )

package/runtime/python/okstra_ctl/analysis_packet.py

@@ -500,7 +500,10 @@ def _stage_ledger_block(stage_ledger_json: str) -> list[str]:
         "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",
+        "in place. The new plan declares every stage listed here as well as the",
+        "ones it adds — its rows run 1..N with no gap — because a plan whose",
+        "rows start above 1 is refused by every consumer that parses a Stage",
+        "Map. `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.",

package/runtime/python/okstra_ctl/application/open_worker.py

@@ -2,6 +2,7 @@
 from __future__ import annotations
 
 from collections.abc import Callable, Sequence
+from dataclasses import replace
 
 from ..domain.worker_runtime import (
     EnvironmentBlocked,
@@ -19,11 +20,15 @@ def open_worker(
     last_unavailable: SurfaceUnavailable | None = None
     for port in chain:
         try:
-            return port.spawn(request_for(port.surface))
+            handle = port.spawn(request_for(port.surface))
         except EnvironmentBlocked:
             raise
         except SurfaceUnavailable as exc:
             last_unavailable = exc
+            continue
+        if last_unavailable is None:
+            return handle
+        return replace(handle, fallback_reason=str(last_unavailable))
     if last_unavailable is None:
         raise SurfaceUnavailable("runtime chain is empty")
     raise last_unavailable

package/runtime/python/okstra_ctl/assignment_resolver.py

@@ -30,7 +30,7 @@ from .ports.host_model import (
     HostModelBindingPort,
     HostModelBindingRequest,
 )
-from .role_requirements import RoleProfile, RoleRequirement
+from .role_requirements import RoleProfile, RoleRequirement, StaticRoleRequirement
 
 
 TerminalBackend = Literal[
@@ -239,8 +239,17 @@ def resolve_model_assignment(
     host: HostSessionContext,
     environment: AssignmentEnvironment,
     entry_mode: Literal["current-session", "new-session"] = "new-session",
+    require_selectable: bool = True,
 ) -> ResolvedAssignment:
-    """Resolve one canonical model through the selected host execution path."""
+    """Resolve one canonical model through the selected host execution path.
+
+    `require_selectable=False` re-resolves a binding a run already recorded.
+    Selectability decides what a user may pick now; a run that picked a model
+    before it left the picker still has to finish. 실측 2026-09-23
+    (fontradar-v2-api dev-10860 implementation-planning-002): `gpt-5.6-sol` 이
+    카탈로그에서 목록 제외로 바뀌자, 그 모델로 이미 세 라운드를 돈 run 의 다음
+    디스패치가 `model binding changed: ... not-selectable` 로 막혔다.
+    """
     _validate_environment(host, environment)
     model = pool.resolve(model_ref)
     availability = pool.availability(
@@ -249,7 +258,9 @@ def resolve_model_assignment(
         host.host_id,
         entry_mode,
     )
-    if not availability.available:
+    if not availability.available and (
+        require_selectable or availability.reason != "not-selectable"
+    ):
         raise AssignmentResolutionError(
             f"model {model_ref!r} is unavailable: {availability.reason}"
         )
@@ -326,8 +337,8 @@ def resolve_model_selection(
     return selected
 
 
-def _static_requirements(profile: RoleProfile) -> tuple[RoleRequirement, ...]:
-    leader = RoleRequirement("leader", 1, 1, 1, "lead")
+def _static_requirements(profile: RoleProfile) -> tuple[StaticRoleRequirement, ...]:
+    leader = StaticRoleRequirement("leader", 1, 1, 1, "lead")
     return (leader, *(row for row in profile.roles if not row.dynamic))
 
 

package/runtime/python/okstra_ctl/cmux.py

@@ -7,6 +7,7 @@ from __future__ import annotations
 
 import json
 import os
+import re
 import shlex
 import shutil
 import socket
@@ -72,6 +73,10 @@ SOCKET_UNREACHABLE = "unreachable"
 
 SOCKET_PROBE_TIMEOUT_SECONDS = 2
 
+# cmux 가 돌려주는 식별자가 UUID 인지 ref 인지 가리는 자리. ref 는 번호가 다시
+# 매겨지므로 원장에 남길 수 없다.
+_UUID_PATTERN = re.compile(r"[0-9A-Fa-f]{8}(?:-[0-9A-Fa-f]{4}){3}-[0-9A-Fa-f]{12}")
+
 
 def cmux_cli_path() -> str:
     """Absolute path to the cmux CLI, or "" when cmux is not installed.
@@ -455,7 +460,11 @@ def spawn_worker_surface(
         owned_surface_ids=owned_surface_ids,
     )
     target = _pane_by_id(panes, placement.pane_id)
-    surface_uuid = _open_worker_surface(workspace, placement, target)
+    try:
+        surface_uuid = _create_surface(workspace, placement, target)
+    except (RuntimeError, OSError, subprocess.SubprocessError):
+        _restore_lead_after_failed_spawn(workspace, owned_surface_ids)
+        raise
     try:
         renamed = rename_surface(surface_uuid, title)
         if renamed.returncode != 0:
@@ -475,10 +484,35 @@ def spawn_worker_surface(
             raise RuntimeError(
                 f"{exc}; cleanup failed for cmux surface {surface_uuid}: {cleanup_error}"
             ) from exc
+        finally:
+            _restore_lead_after_failed_spawn(workspace, owned_surface_ids)
         raise
     return surface_uuid
 
 
+def _restore_lead_after_failed_spawn(
+    workspace: str, owned_surface_ids: Collection[str]
+) -> None:
+    """실패한 분할이 리드에서 떼어 간 폭을 돌려준다.
+
+    폭을 되돌리는 자리는 창이 열린 뒤의 `_size_lead_pane` 하나뿐이었다. 실패한
+    시도는 리드에서 폭만 떼어 가고 끝났고, 실패가 반복되면 축소가 누적된다 —
+    실측 2026-09-21, jobs dev-10860: 강등 7건 뒤 리드가 64칼럼에서 14칼럼.
+
+    닫지 못한 창의 폭까지 되찾지는 않는다. 그 창은 `lead_target_width` 에서
+    남의 창으로 셈해져 usable 에서 빠지고, 리드는 남은 공간에서 제 몫을 가져
+    간다. 되찾으려면 okstra 가 자기 것이라 증명하지 못한 창의 경계를 미는
+    셈이라 그쪽이 더 나쁘다.
+
+    크기 조정이 실패해도 삼킨다: 호출자는 창을 열지 못한 사유를 들고 올라가는
+    중이고, 원장에 남아야 할 문장은 그쪽이다.
+    """
+    try:
+        _size_lead_pane(workspace, owned_surface_ids)
+    except (RuntimeError, OSError, subprocess.SubprocessError):
+        return
+
+
 def rename_surface(surface: str, title: str) -> subprocess.CompletedProcess[str]:
     """Set the tab title cmux shows for one surface.
 
@@ -686,27 +720,14 @@ def rpc(method: str, params: dict[str, Any]) -> dict[str, Any]:
     return payload if isinstance(payload, dict) else {}
 
 
-def _open_worker_surface(
-    workspace: str, placement: Placement, target: PaneGeometry
-) -> str:
-    before = open_surface_ids(workspace)
-    _create_surface(workspace, placement, target)
-    new_ids = open_surface_ids(workspace) - before
-    if len(new_ids) != 1:
-        raise RuntimeError(
-            f"cmux opened {len(new_ids)} surfaces where exactly one was expected"
-        )
-    return new_ids.pop()
-
-
 def open_surface_ids(workspace: str) -> set[str]:
     """Every surface UUID the workspace currently holds.
 
-    Dispatch diffs this set across a create to identify the new surface, rather
-    than translating the `OK surface:N` echo, because `list-pane-surfaces`
-    reports only the focused pane unless given a `--pane`, and the new pane is
-    not focused. Teardown intersects its recorded ids with it to tell a surface
-    that is still open from one that closed earlier in the run.
+    Teardown intersects its recorded ids with this set to tell a surface that is
+    still open from one that closed earlier in the run. It is teardown's only
+    caller: dispatch used to diff this set across a create to name the surface
+    it had just opened, and that is now `new-split --id-format uuids`, which
+    says the uuid outright.
     """
     return {
         surface_id
@@ -717,9 +738,22 @@ def open_surface_ids(workspace: str) -> set[str]:
 
 def _create_surface(
     workspace: str, placement: Placement, target: PaneGeometry
-) -> None:
+) -> str:
+    """새 창을 열고 그 표면의 UUID 를 준다.
+
+    UUID 는 cmux 가 스스로 말해 준다. `--id-format uuids` 를 주면 이 명령의 출력이
+    `OK <surface-uuid> <workspace-uuid>` 가 되고, 그 첫 UUID 가 새 창의 표면이다
+    (실측 2026-09-21, 폐기용 워크스페이스 1회 분할: echo 의 UUID 가 직후
+    `pane.list` 가 보여 준 새 창의 `surface_ids[0]` 과 같았다).
+
+    앞서는 분할 전후의 표면 목록 차집합으로 알아냈는데, 그 차집합이 실제 run 에서
+    여덟 번 중 여덟 번 비어 워커가 창에 붙지 못하고 빈 창만 남았다. 자기가 만든 것의
+    이름을 만든 쪽에 묻는 편이 두 번 읽어 비교하는 것보다 틀릴 자리가 적다.
+    """
     created = run_cmux(
         [
+            "--id-format",
+            "uuids",
             "new-split",
             placement.direction,
             "--workspace",
@@ -730,6 +764,21 @@ def _create_surface(
     )
     if created.returncode != 0:
         raise RuntimeError(created.stderr.strip() or "cmux could not open a pane")
+    return _surface_from_split_echo(created.stdout)
+
+
+def _surface_from_split_echo(stdout: str) -> str:
+    """`new-split` 의 출력에서 새 표면 UUID 만 꺼낸다.
+
+    ref(`surface:2`)는 받지 않는다. okstra 가 기록하고 나중에 닫는 이름이라, cmux 가
+    창을 여닫을 때마다 번호를 다시 매기는 ref 로는 엉뚱한 창을 닫게 된다.
+    """
+    parts = stdout.split()
+    if len(parts) >= 2 and parts[0] == "OK" and _UUID_PATTERN.fullmatch(parts[1]):
+        return parts[1]
+    raise RuntimeError(
+        f"cmux did not name the pane it opened: {stdout.strip()!r}"
+    )
 
 
 def _exec_worker(surface_uuid: str, *, cwd: Path, command: Sequence[str]) -> None:

package/runtime/python/okstra_ctl/code_review_target.py

@@ -99,13 +99,13 @@ def _branch_snapshot(repo: Path, branch: str, base: str, review_date: str) -> di
 
 
 _CLI_EPILOG = r"""Usage:
-  okstra code-review target --task-key <k> --stage <N> [--project-root <dir>] [--cwd <dir>] --json
+  okstra code-review target --task-key <k> --stage <N> [--base <ref>] [--project-root <dir>] [--cwd <dir>] --json
   okstra code-review target --branch <name> [--base <ref>] [--date <YYYY-MM-DD>] [--project-root <dir>] --json
 
 Output: JSON { ok, mode, worktreePath, branch, baseCommit, headCommit,
-reviewPath, round }. Stage mode reads the base commit from the stage
-registry row; branch mode falls back to the merge-base with the default
-branch. An empty worktreePath means the review reads the branch ref
+reviewPath, round }. `--base` sets the base in either mode. Without it, stage
+mode reads the base commit from the stage registry row and branch mode falls
+back to the merge-base with the default branch. An empty worktreePath means the review reads the branch ref
 instead of a checked-out tree. This is read-only — it never creates
 directories or files.
 """
@@ -124,7 +124,10 @@ def _build_parser() -> argparse.ArgumentParser:
     parser.add_argument("--task-key", default="", help="project-id:task-group:task-id")
     parser.add_argument("--stage", type=int, default=0, help="stage number to review")
     parser.add_argument("--branch", default="", help="branch to review")
-    parser.add_argument("--base", default="", help="explicit base ref for branch mode")
+    parser.add_argument(
+        "--base", default="",
+        help="explicit base ref; overrides the stage registry base or the branch merge-base",
+    )
     parser.add_argument("--date", default="", help="YYYY-MM-DD for branch result naming")
     parser.add_argument("--project-root", default="", help="explicit project root")
     parser.add_argument("--cwd", default=".", help="cwd for project root resolution")
@@ -138,7 +141,9 @@ def _resolve(args: argparse.Namespace, project_root: Path) -> dict:
     if args.task_key:
         if args.stage < 1:
             raise StateError("--task-key needs --stage <N>, N >= 1", stage="args")
-        return code_review_target_snapshot(project_root, args.task_key, args.stage)
+        return code_review_target_snapshot(
+            project_root, args.task_key, args.stage, base=args.base
+        )
     if args.branch:
         return _branch_snapshot(
             project_root, args.branch, args.base, _review_date(args.date)
@@ -204,7 +209,7 @@ def main(argv: list[str] | None = None) -> int:
 # 것으로 합쳐진다.
 
 def code_review_target_snapshot(
-    project_root: Path, task_key: str, stage: int
+    project_root: Path, task_key: str, stage: int, *, base: str = ""
 ) -> dict:
     """stage 코드 리뷰가 무엇을 읽고 결과를 어디에 쓰는지 해소한다.
 
@@ -218,6 +223,9 @@ def code_review_target_snapshot(
     표류한다: 다중의존 stage 는 오늘의 task-key worktree HEAD 를 받게 되어
     whole-task final-verification 이 stage 들을 병합한 뒤에는 base..head 구간이
     비거나 뒤집히고, 단일의존 stage 는 선행 stage 가 재실행되면 어긋난다.
+
+    `base` 가 주어지면 그 값을 쓴다 — 스킬이 기록된 base 를 보여 주고 사용자가
+    다른 ref 를 고른 경우다. 무시하면 사용자가 거부한 범위로 리뷰가 진행된다.
     """
     identity = resolve_task_identity(project_root, task_key)
     task_root = Path(identity["taskRoot"])
@@ -241,7 +249,7 @@ def code_review_target_snapshot(
     coords = (identity["projectId"], identity["taskGroup"], identity["taskId"])
     stage_row = worktree_registry.get_stage_row(*coords, stage) or {}
     worktree_view = _stage_worktree_view(project_root, stage_row, stage)
-    base_commit = stage_row.get("base_ref") or _legacy_stage_base_commit(
+    base_commit = base or stage_row.get("base_ref") or _legacy_stage_base_commit(
         identity, stages, selected
     )
     review_path, round_no = code_review_paths.next_stage_review(

package/runtime/python/okstra_ctl/conformance.py

@@ -219,6 +219,49 @@ def exempt_stage_surface_conflicts(
     return conflicts
 
 
+def declared_stage_surface_gaps(
+    data: object, patterns: object = None,
+) -> list[dict[str, object]]:
+    """`Conformance tests:` 의 `requires` 가 계획된 경로의 표면을 다 덮지 못한 stage.
+
+    구현 게이트는 두 가지를 동시에 요구한다 — diff 가 건드린 표면을 `requires`
+    가 덮을 것(`_validate_conformance_surfaces`), 그리고 선언된 stage 의
+    `requires` 가 계획 선언과 같을 것(`_declared_conformance_errors`). 계획이
+    `requires` 를 좁게 적었는데 그 stage 가 계획한 경로가 다른 표면을 건드리면
+    구현은 둘 중 하나에 반드시 걸린다. 실측(2026-09-22, fontradar-v2-api dev-10860
+    Stage 1~3): `requires=[io]` 로 선언하고 `catalog.controller.ts`(http)를
+    계획해, 구현 run 이 "undeclared surface" 와 "requires mismatch" 를 번갈아 냈다.
+    면제 stage 와 같은 판별을 선언 stage 에도 승인 전에 한다.
+
+    반환 행: `{"stage": <int>, "surfaces": [빠진 표면..], "paths": [..],
+    "requires": [선언된 것..]}`.
+    """
+    planning = data.get("implementationPlanning") if isinstance(data, dict) else None
+    stages = planning.get("stages") if isinstance(planning, dict) else None
+    gaps: list[dict[str, object]] = []
+    for stage in stages if isinstance(stages, list) else []:
+        if not isinstance(stage, dict):
+            continue
+        parsed = parse_conformance_tests(stage.get("conformanceTests"))
+        number = stage.get("stage")
+        if parsed is None or not isinstance(number, int) or isinstance(number, bool):
+            continue
+        _script, requires = parsed
+        touching = sorted(
+            path for path in _stage_planned_paths(stage)
+            if detect_surfaces([path], patterns) - requires
+        )
+        missing = detect_surfaces(touching, patterns) - requires
+        if missing:
+            gaps.append({
+                "stage": number,
+                "surfaces": sorted(missing),
+                "paths": touching,
+                "requires": sorted(requires),
+            })
+    return gaps
+
+
 def _stage_planned_paths(stage: dict) -> list[str]:
     """stage 의 step 들이 계획한 경로 — 경로 모양인 문자열만.
 

package/runtime/python/okstra_ctl/consumers.py

@@ -244,15 +244,18 @@ def append_verified(plan_run_root: Path, *, impl_task_key: str, stage: int,
 
 
 def append_pr(plan_run_root: Path, *, impl_task_key: str, stages: List[int],
-              branch: str, url: str) -> None:
-    """handoff 의 PR 생성/재사용 기록. 같은 branch 의 pr 행이 이미 있으면 멱등."""
+              branch: str, url: str, base: str = "") -> None:
+    """handoff 의 PR 생성/재사용 기록. 같은 branch 의 pr 행이 이미 있으면 멱등.
+
+    `base` 는 그 PR 이 올라앉은 브랜치다. stage PR 은 스택이라 base 가 릴리스
+    브랜치가 아닐 수 있고, 어느 순서로 머지해야 하는지는 이 값에만 남는다."""
     with consumers_mutex(plan_run_root):
         for row in read_consumers(plan_run_root):
             if row.get("status") == "pr" and row.get("branch") == branch:
                 return
         _append_row(plan_run_root, {
             "impl_task_key": impl_task_key, "stages": sorted(stages),
-            "status": "pr", "branch": branch, "url": url,
+            "status": "pr", "branch": branch, "base": base, "url": url,
         })
 
 

package/runtime/python/okstra_ctl/container.py

@@ -213,8 +213,18 @@ def _compose_ps(project_name: str, cwd: str, include_stopped: bool = False) -> l
     return rows
 
 
-def _docker_run(argv: list[str], cwd: str | None = None) -> str:
+def _docker_run(argv: list[str], cwd: str | None = None, *, check: bool = False) -> str:
+    """docker 명령을 돌려 stdout 을 돌려준다.
+
+    `check=True` 면 0 이 아닌 종료를 PrepareError 로 올린다. status 가 빈 목록을,
+    down 이 성공을 보고하는데 실제로는 docker 가 실패한 경우를 막는다. config 계열
+    조회는 실패해도 진행하도록 설계돼 있어 기본값은 그대로 둔다."""
     result = subprocess.run(argv, capture_output=True, text=True, check=False, cwd=cwd)
+    if check and result.returncode != 0:
+        detail = (result.stderr or result.stdout or "").strip().splitlines()
+        raise PrepareError(
+            f"`{' '.join(argv[:4])}` 가 exit {result.returncode} 로 실패했습니다: "
+            f"{detail[-1] if detail else '출력 없음'}")
     return result.stdout or ""
 
 
@@ -222,7 +232,7 @@ def query_containers_by_label(project_name: str) -> list[dict]:
     """라벨 SSOT(spec §11): `okstra.project-name` 으로 컨테이너를 질의한다.
 
     registry 가 아니라 docker 라벨이 컨테이너 존재의 기준값이다."""
-    out = _docker_run([
+    out = _docker_run(check=True, argv=[
         "docker", "ps", "-a", "--filter",
         f"label=okstra.project-name={project_name}",
         "--format", (
@@ -431,7 +441,7 @@ def provision_container_group(
         raise PrepareError(
             f"container up: `up -d` 후 기동된 컨테이너가 없습니다(`docker compose -p "
             f"{project_name} ps -a` 로 확인). compose 정의·활성 profile 을 점검한 뒤 "
-            f"`okstra container down --task-key {task_key}` 로 정리하고 다시 시도하세요.")
+            f"`{_down_hint(project_root, task_key)}` 로 정리하고 다시 시도하세요.")
     failed = poll_healthcheck(
         project_name=project_name, cwd=str(worktree), services=started,
         healthcheck_timeout_seconds=healthcheck_timeout_seconds,
@@ -445,8 +455,8 @@ def provision_container_group(
         raise PrepareError(
             f"container up: 다음 서비스가 시간 내 기동하지 못했습니다: {', '.join(failed)} "
             f"(timeout={healthcheck_timeout_seconds}s). `docker compose -p "
-            f"{project_name} logs` 로 원인을 확인한 뒤 `okstra container down "
-            f"--task-key {task_key}` 로 정리하세요.")
+            f"{project_name} logs` 로 원인을 확인한 뒤 "
+            f"`{_down_hint(project_root, task_key)}` 로 정리하세요.")
     # deploy-state 는 실제 기동된 started 만 기록한다 — full services 를 쓰면
     # profiles 로 안 뜬 서비스가 `down --all` 스윕의 대상으로 남는다.
     _write_deploy_state(cp, project_name=project_name, task_key=task_key,
@@ -528,12 +538,18 @@ def status_container_group(*, project_root, task_key: str) -> dict:
             "containers": query_containers_by_label(project_name)}
 
 
+def _down_hint(project_root, task_key: str) -> str:
+    """실패 메시지가 안내하는 정리 명령. 파서가 요구하는 인자를 모두 싣는다."""
+    return f"okstra container down --project-root {project_root} --task-key {task_key}"
+
+
 def down_container_group(*, project_root, task_key: str = "", all_groups: bool = False) -> dict:
-    """라벨 쿼리로 컨테이너를 down 한다."""
+    """compose 프로젝트 이름으로 task 의 컨테이너 그룹을 down 한다."""
     from .ids import compose_project_name
 
     project_root = Path(project_root)
     results = []
+    failures: list[str] = []
     for project_id, group, task_id in _down_targets(project_root, task_key, all_groups):
         project_name = compose_project_name(project_id, group, task_id)
         # `docker rm -f` 는 컨테이너만 지우고 compose 가 만든 네트워크를 누수시킨다.
@@ -541,9 +557,16 @@ def down_container_group(*, project_root, task_key: str = "", all_groups: bool =
         # 단위 컨테이너+네트워크를 회수한다. `-v` 는 의도적으로 빼서 compose 에
         # 선언된 named volume(예: DB 데이터)을 보존한다 — down 한 번에 사용자
         # 영속 데이터를 파괴하지 않는다.
-        _docker_run(["docker", "compose", "-p", project_name, "down",
-                     "--remove-orphans"])
+        try:
+            _docker_run(["docker", "compose", "-p", project_name, "down",
+                         "--remove-orphans"], check=True)
+        except PrepareError as exc:
+            failures.append(f"{project_name}: {exc}")
+            continue
         results.append({"projectName": project_name})
+    if failures:
+        # 나머지 대상은 끝까지 내리고, 실패한 것만 모아 알린다.
+        raise PrepareError("container down 실패 — " + "; ".join(failures))
     return {"downed": results}
 
 

package/runtime/python/okstra_ctl/context_cost.py

@@ -2,7 +2,8 @@
 
 The estimator answers a narrow operational question: how much file/context
 surface does the current task bundle ask the lead, analysis workers, and
-report-writer to absorb? It does not mutate task artifacts.
+report-writer to absorb? It writes no report or run artifact; resolving the task
+may record a finished implementation outcome (see `find_task_root`).
 """
 from __future__ import annotations
 
@@ -38,11 +39,9 @@ HOT_PATH_LEAD_RESOURCES = (
     "convergence",
     "report-writer",
 )
-WORKER_AGENT_FILES = (
-    "claude-worker.md",
-    "report-writer-worker.md",
-    "translator-worker.md",
-)
+# 모든 디스패치 프롬프트 앞머리에 실리는 계약. 종전에는 `~/.claude/agents` 의
+# 에이전트 정의를 셌는데, 그 정의는 더 이상 설치되지 않는다(ADR-0017).
+HOT_PATH_AGENT_CONTRACTS = ("agents/common.json",)
 TIMESTAMPED_ARTIFACT_RE = re.compile(r"\d{4}-\d{2}-\d{2}[_T]\d{2}-\d{2}-\d{2}")
 
 
@@ -136,7 +135,7 @@ def _duty_contract_files(
     if not isinstance(duty_root_value, str) or not duty_root_value:
         return []
     duty_root = project_root / duty_root_value
-    files = [duty_root / "common.md", duty_root / f"{audience}.md"]
+    files = [duty_root / "common.json", duty_root / f"{audience}.json"]
     return [path for path in files if path.is_file()]
 
 
@@ -239,19 +238,15 @@ def _skill_assets_metric() -> dict:
     instruction footprint and are the prompt-diet ranking input."""
     entries = []
     okstra_home = _okstra_asset_home()
-    claude_home = Path.home() / ".claude"
     for name in HOT_PATH_LEAD_RESOURCES:
         path = _installed_or_dev(
             okstra_home / "prompts" / "lead" / f"{name}.md",
             f"prompts/lead/{name}.md",
         )
         entries.append((f"resource:{name}", path))
-    for fname in WORKER_AGENT_FILES:
-        path = _installed_or_dev(
-            claude_home / "agents" / fname,
-            f"runtime/agents/workers/{fname}",
-        )
-        entries.append((f"agent:{fname}", path))
+    for relative in HOT_PATH_AGENT_CONTRACTS:
+        path = _installed_or_dev(okstra_home / relative, relative)
+        entries.append((f"contract:{relative}", path))
 
     files = []
     for label, path in entries:
@@ -512,7 +507,8 @@ _CLI_EPILOG = r"""Usage:
 
 Output: JSON with task file counts, current-run counts, lead Phase 1 read
 surface, analysis-worker initial read surface, and report-writer synthesis
-surface. This is read-only; it never mutates task artifacts.
+surface. Resolving a task may record a finished implementation outcome in its task
+manifest, the task catalog, and consumers.jsonl; nothing else is written.
 """