okstra 0.186.7 → 0.187.0

package/runtime/python/okstra_ctl/container.py

@@ -17,9 +17,7 @@ from __future__ import annotations
 
 import argparse
 import json
-import os
 import re
-import shlex
 import subprocess
 import sys
 import time
@@ -35,34 +33,6 @@ OKSTRA_LABEL_KEYS = ("okstra.task-key", "okstra.project-name", "okstra.run-trace
 
 COMPOSE_FILENAME = "docker-compose.yml"
 
-# spec §5/§10 — 에러 트리거 화이트리스트. 이 정규식 중 하나라도 라인에 걸려야
-# 2단계(LLM analyze)로 넘어간다. 건강한 컨테이너는 어느 것도 안 걸려 토큰 0.
-ERROR_PATTERNS = (
-    re.compile(r"\bERROR\b"),
-    re.compile(r"\bFATAL\b"),
-    re.compile(r"\bCRITICAL\b"),
-    re.compile(r"\bPANIC\b"),
-    re.compile(r"\b\w+(?:Error|Exception)\b"),
-    re.compile(r"^Traceback \(most recent call last\):"),
-    re.compile(r"\b(?:exit(?:ed)?|exit code|status)\s+(?:code\s+)?[1-9]\d*\b", re.I),
-    re.compile(r"\bUnhandled\b", re.I),
-)
-
-# error_signature 정규화: 변동성 노이즈(타임스탬프/pid/라인참조/hex 주소)만 깎고,
-# ERROR_PATTERNS 가 *탐지하는* 의미 있는 코드(HTTP status, exit/signal code)는 보존한다.
-# 블랭킷 `\d+` 치환은 distinct 에러(500 vs 404, exit 1 vs 137)를 한 시그니처로
-# collapse 시켜 디바운스가 영영 분석을 막으므로 쓰지 않는다(spec §10 signal vs noise).
-_NOISE_SUBS = (
-    (re.compile(
-        r"\d{4}-\d{2}-\d{2}[ T]\d{2}:\d{2}:\d{2}(?:[.,]\d+)?(?:Z|[+-]\d{2}:?\d{2})?"
-    ), "<ts>"),
-    (re.compile(r"\b0x[0-9a-fA-F]+\b"), "<hex>"),
-    (re.compile(r"\b(pid|tid|ppid)=\d+", re.I), r"\1=<n>"),
-    (re.compile(r":\d+:"), ":<n>:"),
-)
-_WS_RE = re.compile(r"\s+")
-
-
 def merge_env(base_env: dict, override: dict) -> dict:
     """base_env 위에 override 를 얹는다. 동일 키는 override 가 이긴다."""
     return {**base_env, **override}
@@ -126,179 +96,6 @@ def build_compose_up_argv(
     return argv
 
 
-def scan_log_chunk(text: str, patterns: Iterable[re.Pattern]) -> list[str]:
-    """ERROR_PATTERNS 중 하나라도 걸리는 라인만 순서대로 반환(순수, docker 무의존)."""
-    return [
-        line
-        for line in text.splitlines()
-        if line and any(p.search(line) for p in patterns)
-    ]
-
-
-def error_signature(line: str) -> str:
-    """디바운스 키: 변동성 노이즈만 깎고 의미 있는 코드는 보존한 라인.
-
-    타임스탬프/pid/라인참조/hex 주소는 placeholder 로 정규화하지만 HTTP status·
-    exit/signal code 같은 판별자는 그대로 둔다. 같은 에러가 timestamp·pid 만
-    달리해 반복되면 동일 키 → analyze 1회(spec §10 디바운스), 그러나 500 vs 404
-    처럼 의미가 다르면 별도 키 → 각각 분석된다.
-    """
-    s = line
-    for pattern, repl in _NOISE_SUBS:
-        s = pattern.sub(repl, s)
-    return _WS_RE.sub(" ", s).strip()
-
-
-def watcher_step(
-    *,
-    log_chunk: str,
-    seen_signatures: set,
-    findings_path: Path,
-    analyze: Callable[[str], object],
-) -> int:
-    """log_chunk 를 1단계 스캔 → 새 시그니처마다 analyze 호출 + findings append.
-
-    이미 본 시그니처는 디바운스(skip). 새 분석 건수를 반환한다. analyze 는 주입이라
-    유닛 테스트는 스텁으로 LLM 없이 행위를 검증한다.
-    """
-    new_count = 0
-    for line in scan_log_chunk(log_chunk, ERROR_PATTERNS):
-        sig = error_signature(line)
-        if sig in seen_signatures:
-            continue
-        seen_signatures.add(sig)
-        # 탐지 자체를 analyze 보다 먼저 영속화한다 — analyze(=pane spawn) 가 실패해도
-        # 에러 라인은 findings 에 남는다. analyze 예외가 장기 watcher 루프를 죽이지
-        # 않도록 격리하고, 실패 사실도 findings 에 기록한다(silent 중단 방지).
-        _append_finding(Path(findings_path), sig, line)
-        try:
-            analyze(line)
-        except Exception as exc:  # noqa: BLE001 — best-effort 외부 spawn, 루프 보존이 우선
-            _append_finding(Path(findings_path), sig, f"[analyze 실패] {exc}")
-        new_count += 1
-    return new_count
-
-
-def _append_finding(findings_path: Path, signature: str, line: str) -> None:
-    findings_path.parent.mkdir(parents=True, exist_ok=True)
-    block = f"## {signature}\n\n```\n{line}\n```\n\n"
-    with findings_path.open("a", encoding="utf-8") as fh:
-        fh.write(block)
-
-
-# spec §9 — watcher AI 는 "탐지·보고만, 자동 치유 제외". 기본 analyze 가 기동하는
-# 에이전트는 findings 파일 append 외 어떤 코드/설정 Edit/Write 도 금지한다. 이
-# 계약 문구를 에이전트 프롬프트에 그대로 넣어 enforcement 를 명시한다.
-WATCHER_READONLY_CONTRACT = (
-    "You are a READ-ONLY container log watcher. You MUST NOT Edit or Write any "
-    "code or config file. Your ONLY permitted write is appending an analysis "
-    "note to the findings file. Detect and report; never auto-fix."
-)
-
-
-def default_analyze(findings_path: Path, *, session_pane: str | None = None):
-    """프로덕션 기본 analyze 팩토리: read-only 계약을 건 에이전트를 pane 으로 기동.
-
-    codex/antigravity-worker 와 동일한 split_container_pane 메커니즘을 쓰되
-    WATCHER_READONLY_CONTRACT 를 프롬프트에 박아 코드/설정 수정 권한을 차단한다.
-    라이브 spawn 세부(에이전트 CLI·모델·권한 스코프)는 아직 미구현이라 e2e 영역으로
-    둔다 — session_pane 이 없으면 split_container_pane 이 guard 로 None 을 돌려주어
-    실제 spawn 없이 no-op 이 된다(에러 탐지·findings 기록은 watcher_step 이 담당).
-    프롬프트를 셸 명령으로 그대로 실행하지 않도록, 자동 `$TMUX_PANE` fallback 은
-    두지 않는다 — 자연어 프롬프트가 pane 명령으로 새지 않게 하는 안전장치다.
-    """
-    from okstra_ctl import tmux
-
-    def analyze(window: str) -> str | None:
-        prompt = f"{WATCHER_READONLY_CONTRACT}\n\nError window:\n{window}\n"
-        return tmux.split_container_pane(
-            session_pane=session_pane,
-            cwd=str(Path(findings_path).parent),
-            command=prompt,
-            title="okstra-watcher",
-            scope_value=str(findings_path),
-            kind="watcher",
-        )
-
-    return analyze
-
-
-def build_watcher_pane_command(
-    *, python_exe: str, module_root: str, project_name: str,
-    service: str, findings_path: str, scan_interval_seconds: float,
-) -> str:
-    """watcher pane 이 실행할 셸 명령 문자열.
-
-    `python -m okstra_ctl.container watch` 를 PYTHONPATH 와 함께 박는다 — tmux pane
-    의 환경 상속에 의존하면 PYTHONPATH 가 비어 import 가 깨지므로, 현재 프로세스의
-    module-root 를 명시적으로 넘긴다. 모든 인자는 shlex 로 인용해 경로에 공백/메타
-    문자가 있어도 안전하다."""
-    return " ".join([
-        f"PYTHONPATH={shlex.quote(module_root)}",
-        shlex.quote(python_exe), "-m", "okstra_ctl.container", "watch",
-        "--project-name", shlex.quote(project_name),
-        "--service", shlex.quote(service),
-        "--findings", shlex.quote(findings_path),
-        "--scan-interval", str(scan_interval_seconds),
-    ])
-
-
-def run_service_watcher(
-    *, project_name: str, service: str, findings_path: str,
-    scan_interval_seconds: float,
-) -> None:
-    """`container watch` 서브커맨드 본체 — 한 서비스의 감시 루프를 돈다.
-
-    stage ① 경량 스캔(ERROR 패턴) → 매칭 시 findings append + stage ② analyze.
-    사용자가 pane/세션을 종료(stop-watcher/down)할 때까지 지속한다."""
-    analyze = default_analyze(Path(findings_path))
-    run_watcher_loop(
-        service=service, project_name=project_name,
-        findings_path=Path(findings_path),
-        scan_interval_seconds=scan_interval_seconds, analyze=analyze,
-    )
-
-
-def run_watcher_loop(
-    *,
-    service: str,
-    project_name: str,
-    findings_path: Path,
-    scan_interval_seconds: float,
-    analyze: Callable[[str], object],
-) -> None:
-    """`docker compose -p <project> logs --since <last>` 증분 fetch + sleep 루프.
-
-    사용자 종료(stop-watcher/down) 까지 지속. 토큰은 ERROR_PATTERNS 가 걸릴 때만
-    쓴다. 루프는 얇게 — 매 tick 의 판단은 watcher_step 에 위임한다.
-    """
-    seen: set = set()
-    # 첫 tick 은 --since 없이 컨테이너 기동 이후 backlog 전체를 본다. `--since 0s`
-    # 는 'now 이후'를 의미해 기동 중 찍힌 startup-failure 에러를 영구히 놓친다.
-    since: str | None = None
-    while True:
-        tick_start = time.monotonic()
-        chunk = _fetch_log_chunk(service=service, project_name=project_name, since=since)
-        watcher_step(
-            log_chunk=chunk, seen_signatures=seen,
-            findings_path=Path(findings_path), analyze=analyze,
-        )
-        time.sleep(scan_interval_seconds)
-        # 다음 윈도우는 '직전 fetch 이후 실제 경과시간'(sleep + analyze 포함)을
-        # 덮는다. 고정 interval 윈도우는 analyze 가 interval 보다 오래 걸리면 그
-        # 사이 찍힌 에러 라인을 영구히 놓친다. +1s 오버랩의 중복은 디바운스가 흡수.
-        since = f"{int(time.monotonic() - tick_start) + 1}s"
-
-
-def _fetch_log_chunk(*, service: str, project_name: str, since: str | None) -> str:
-    argv = ["docker", "compose", "-p", project_name, "logs", "--no-color"]
-    if since:  # 첫 tick(None)은 --since 생략 → 기동 backlog 전체
-        argv += ["--since", since]
-    argv.append(service)
-    result = subprocess.run(argv, capture_output=True, text=True, check=False)
-    return result.stdout or ""
-
-
 # --------------------------------------------------------------------------- #
 # compose 파싱 — docker 가 정본(canonical). 손수 정규식 파서는 라벨 SSOT 를
 # silent 하게 깨므로 쓰지 않는다(inline comment / quoted name / 4-space 들여쓰기
@@ -600,11 +397,10 @@ def provision_container_group(
     *, project_root, task_key: str,
     healthcheck_timeout_seconds: int = 120,
     healthcheck_interval_seconds: int = 3,
-    scan_interval_seconds: float = 5.0,
 ) -> dict:
     """skill / bin okstra / okstra.sh 가 수렴하는 container up 단일 진입점."""
     from . import paths
-    from .ids import compose_project_name, build_container_session_name
+    from .ids import compose_project_name, build_container_run_trace
 
     project_root = Path(project_root)
     inputs = _resolve_up_inputs(project_root, task_key)
@@ -613,7 +409,7 @@ def provision_container_group(
     cp = paths.container_paths(project_root, inputs["task_group"], inputs["task_id"])
     project_name = compose_project_name(
         inputs["project_id"], inputs["task_group"], inputs["task_id"])
-    session_name = build_container_session_name(
+    run_trace = build_container_run_trace(
         inputs["project_id"], inputs["task_group"], inputs["task_id"])
     worktree_env, override_env = _synthesize_env_override(worktree, cp)
     env_files = [p for p in (worktree_env, override_env) if p]
@@ -621,7 +417,7 @@ def provision_container_group(
     services = resolve_compose_services(compose, env_files, str(worktree))
     started = _compose_up(
         cp=cp, worktree=worktree, compose=compose, project_name=project_name,
-        task_key=task_key, session_name=session_name, services=services,
+        task_key=task_key, run_trace=run_trace, services=services,
         worktree_env=worktree_env, override_env=override_env)
     if not started:
         # ps 가 빈 출력(데몬 일시 오류)이거나 모든 서비스가 미생성이면 started 가
@@ -631,7 +427,7 @@ def provision_container_group(
         # 가능하게 한다 — 실제 기동분을 모르니 full services 를 best-effort 로 기록.
         _write_deploy_state(
             cp, project_name=project_name, task_key=task_key, services=services,
-            warnings=warnings, watch={"enabled": False, "note": "기동 컨테이너 없음"})
+            warnings=warnings)
         raise PrepareError(
             f"container up: `up -d` 후 기동된 컨테이너가 없습니다(`docker compose -p "
             f"{project_name} ps -a` 로 확인). compose 정의·활성 profile 을 점검한 뒤 "
@@ -645,24 +441,18 @@ def provision_container_group(
         # `down --all` 스윕(deploy-state.json 있는 task 만 발견)이 회수할 수 있다.
         _write_deploy_state(
             cp, project_name=project_name, task_key=task_key, services=started,
-            warnings=warnings, watch={"enabled": False, "note": "healthcheck 미통과"},
-            healthcheckFailed=failed)
+            warnings=warnings, healthcheckFailed=failed)
         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}` 로 정리하세요.")
-    # watcher/deploy-state 는 실제 기동된 started 만 대상으로 한다 — full services
-    # 를 쓰면 profiles 미기동 서비스에 컨테이너 없는 tail/watcher pane 과 registry
-    # 항목이 phantom 으로 생겨 배포 수명 동안 누수된다.
-    watch = _spawn_watchers(cp=cp, worktree=worktree, project_name=project_name,
-                            services=started, session_name=session_name,
-                            project_root=project_root, inputs=inputs,
-                            scan_interval_seconds=scan_interval_seconds)
+    # deploy-state 는 실제 기동된 started 만 기록한다 — full services 를 쓰면
+    # profiles 로 안 뜬 서비스가 `down --all` 스윕의 대상으로 남는다.
     _write_deploy_state(cp, project_name=project_name, task_key=task_key,
-                        services=started, warnings=warnings, watch=watch)
+                        services=started, warnings=warnings)
     return {"projectName": project_name, "services": started,
-            "warnings": warnings, "watch": watch}
+            "warnings": warnings}
 
 
 def _integrate_source_tree(inputs: dict) -> str:
@@ -679,7 +469,7 @@ def _integrate_source_tree(inputs: dict) -> str:
 
 def _compose_up(
     *, cp: dict, worktree: Path, compose: Path, project_name: str, task_key: str,
-    session_name: str, services: list[str], worktree_env: str, override_env: str,
+    run_trace: str, services: list[str], worktree_env: str, override_env: str,
 ) -> list[str]:
     """label override 주입 → compose up → 실제 기동된 서비스명 반환.
 
@@ -689,9 +479,9 @@ def _compose_up(
     labels = {
         "okstra.task-key": task_key,
         "okstra.project-name": project_name,
-        # run-trace 는 이 기능의 trace 식별자(container session name)로 채워
-        # project-name 과 distinct 하게 둔다(M1).
-        "okstra.run-trace": session_name,
+        # run-trace 는 이 기능의 trace 식별자로 채워 project-name 과
+        # distinct 하게 둔다(M1).
+        "okstra.run-trace": run_trace,
     }
     label_path = _write_label_override(cp, services, labels)
     argv = build_compose_up_argv(
@@ -719,117 +509,27 @@ def _started_services(project_name: str, cwd: str, services: list[str]) -> list[
     return [s for s in services if s in created]
 
 
-def _spawn_watchers(
-    *, cp: dict, worktree: Path, project_name: str, services: list[str],
-    session_name: str, project_root: Path, inputs: dict, scan_interval_seconds: float,
-) -> dict:
-    """tmux 가 있으면 detached 세션 + 서비스별 tail/watcher pane. 없으면 skip.
-
-    pane split 실패(pane 한도/세션 외부 종료 등)는 watcher 만 degrade 시키고 raise
-    하지 않는다 — 컨테이너는 이미 떠 있으므로 호출자가 deploy-state 를 반드시 써서
-    `down --all` 스윕에서 보이게 해야 한다."""
-    from . import tmux
-
-    if not tmux.tmux_available():
-        return {"enabled": False, "note": "감시 비활성(tmux 없음)"}
-    cp["watchers_dir"].mkdir(parents=True, exist_ok=True)
-    started: list[str] = []
-    try:
-        # holder pane 은 기본 셸로 띄워 오래 살린다(`true` 는 split 전에 세션을
-        # 무너뜨림). container 태그를 붙여 down/stop-watcher 의 스코프 reap 로
-        # tail/watcher pane 과 함께 회수되게 한다(마지막 pane 회수 시 세션 종료).
-        pane = tmux.new_detached_session(session_name, str(worktree))
-        tmux.tag_container_pane(pane, str(cp["container_dir"]))
-        for svc in services:
-            _spawn_service_panes(
-                pane=pane, cp=cp, worktree=worktree, project_name=project_name,
-                svc=svc, session_name=session_name, project_root=project_root,
-                inputs=inputs, scan_interval_seconds=scan_interval_seconds)
-            started.append(svc)
-    except (RuntimeError, OSError, subprocess.SubprocessError) as exc:
-        # watcher spawn 실패(tmux split/RuntimeError, registry flock/디스크 OSError,
-        # tmux timeout/SubprocessError)는 watcher 만 degrade 시키고 raise 하지
-        # 않는다 — 호출자가 deploy-state 를 반드시 써 컨테이너 leak 을 막는다.
-        return {"enabled": True, "session": session_name, "services": started,
-                "partial": True, "note": f"watcher 부분 실패: {exc}"}
-    return {"enabled": True, "session": session_name, "services": started}
-
-
-def _spawn_service_panes(
-    *, pane: str, cp: dict, worktree: Path, project_name: str, svc: str,
-    session_name: str, project_root: Path, inputs: dict, scan_interval_seconds: float,
-) -> None:
-    """한 서비스의 tail pane + watcher loop pane 을 split 하고 registry 에 등록."""
-    from . import tmux, container_registry
-
-    findings = cp["watchers_dir"] / f"{svc}.findings.md"
-    tmux.split_container_pane(
-        session_pane=pane, cwd=str(worktree),
-        command=f"docker compose -p {project_name} logs -f {svc}",
-        title=f"tail:{svc}", scope_value=str(cp["container_dir"]), kind="tail")
-    wpane = tmux.split_container_pane(
-        session_pane=pane, cwd=str(worktree),
-        command=build_watcher_pane_command(
-            python_exe=sys.executable,
-            module_root=str(Path(__file__).resolve().parent.parent),
-            project_name=project_name, service=svc, findings_path=str(findings),
-            scan_interval_seconds=scan_interval_seconds),
-        title=f"watch:{svc}", scope_value=str(cp["container_dir"]), kind="watcher")
-    container_registry.reserve(
-        project_root, inputs["task_group"], inputs["task_id"], svc,
-        session_name=session_name, pane_id=wpane or "", findings_path=str(findings))
-
-
 def _write_deploy_state(cp: dict, **state) -> None:
     cp["container_dir"].mkdir(parents=True, exist_ok=True)
     write_owned_object_atomic(cp["deploy_state"], state, artifact="container deploy state")
 
 
 # --------------------------------------------------------------------------- #
-# status / logs / stop-watcher / down
+# status / down
 # --------------------------------------------------------------------------- #
 
 def status_container_group(*, project_root, task_key: str) -> dict:
-    """라벨 쿼리(컨테이너 존재 SSOT) + registry(보조 watcher 메타) 합본."""
-    from . import container_registry
+    """라벨 쿼리 — 컨테이너 존재 여부의 기준값(SSOT)."""
     from .ids import compose_project_name
 
     project_id, group, task_id = _split_task_key(task_key)
     project_name = compose_project_name(project_id, group, task_id)
-    containers = query_containers_by_label(project_name)
-    registry = container_registry.lookup(Path(project_root), group, task_id)
-    return {"projectName": project_name, "containers": containers,
-            "watchers": registry.get("services", {})}
-
-
-def logs_container_group(*, project_root, task_key: str, service: str = "") -> dict:
-    """deploy-state + watcher findings 경로를 안내(로그 자체는 tmux pane 에 있음)."""
-    from . import paths, container_registry
-
-    project_id, group, task_id = _split_task_key(task_key)
-    cp = paths.container_paths(Path(project_root), group, task_id)
-    services = container_registry.lookup(Path(project_root), group, task_id).get(
-        "services", {})
-    if service:
-        services = {service: services[service]} if service in services else {}
-    return {"watchersDir": str(cp["watchers_dir"]), "watchers": services}
-
-
-def stop_watcher_group(*, project_root, task_key: str) -> dict:
-    """watcher/tail pane(@okstra_container_run) 만 회수하고 컨테이너는 살려둔다."""
-    project_id, group, task_id = _split_task_key(task_key)
-    reaped = _reap_container_panes(Path(project_root), group, task_id)
-    return {"reapedPanes": reaped, "note": "컨테이너는 유지됨(감시만 종료)"}
+    return {"projectName": project_name,
+            "containers": query_containers_by_label(project_name)}
 
 
 def down_container_group(*, project_root, task_key: str = "", all_groups: bool = False) -> dict:
-    """라벨 쿼리로 컨테이너 down + tmux 실측으로 orphan watcher 회수.
-
-    registry 는 보조 인덱스라 누락돼도 'watcher 없음'을 의미하지 않는다 — tmux 를
-    직접 스캔(@okstra_container_run)해 orphan pane 까지 reap 한다(spec §11).
-    pane 회수는 항상 현재 project-root 스코프로 한정한다 — 동시 세션이 흔한
-    레포라 다른 task/프로젝트의 watcher pane 을 절대 죽이지 않는다(I2)."""
-    from . import paths
+    """라벨 쿼리로 컨테이너를 down 한다."""
     from .ids import compose_project_name
 
     project_root = Path(project_root)
@@ -843,19 +543,8 @@ def down_container_group(*, project_root, task_key: str = "", all_groups: bool =
         # 영속 데이터를 파괴하지 않는다.
         _docker_run(["docker", "compose", "-p", project_name, "down",
                      "--remove-orphans"])
-        reaped = _reap_container_panes(project_root, group, task_id)
-        results.append({"projectName": project_name, "reapedPanes": reaped})
-    # registry drift 로 등록 안 된 orphan pane 회수는 `--all`(이 프로젝트 전체)
-    # 때만, 그것도 **이 project-root 의 .okstra/ prefix** 로만 스코프한다. 단일
-    # down 은 위 per-task 회수로 끝낸다(글로벌 sweep 금지 — 동시 세션 간섭 차단).
-    orphans = _reap_project_orphan_panes(project_root) if all_groups else []
-    return {"downed": results, "orphanPanesReaped": orphans}
-
-
-def _reap_project_orphan_panes(project_root: Path) -> list[str]:
-    prefix = str((project_root / ".okstra").resolve())
-    return _kill_panes_by_tag(
-        lambda tag: tag == prefix or tag.startswith(prefix + os.sep))
+        results.append({"projectName": project_name})
+    return {"downed": results}
 
 
 def _down_targets(project_root, task_key: str, all_groups: bool) -> list[tuple[str, str, str]]:
@@ -893,66 +582,33 @@ def _read_project_id(project_json: Path) -> str:
         return ""
 
 
-def _reap_container_panes(project_root: Path, group: str, task_id: str) -> list[str]:
-    """이 task 의 container_dir 태그를 가진 pane 만 회수한다(task 스코프)."""
-    from . import paths, container_registry
-    cp = paths.container_paths(project_root, group, task_id)
-    container_dir = str(cp["container_dir"].resolve())
-    container_registry.clear(project_root, group, task_id)
-    # tail/watcher pane 은 container_dir 로, analyze pane 은 그 하위 findings 경로로
-    # 태그된다 — 둘 다 회수하되 prefix 가 task 의 container_dir 라 스코프는 유지된다.
-    return _kill_panes_by_tag(
-        lambda tag: tag == container_dir or tag.startswith(container_dir + os.sep))
-
-
-def _kill_panes_by_tag(match: Callable[[str], bool]) -> list[str]:
-    """`@okstra_container_run` 태그값이 ``match`` 를 통과하는 pane 만 tmux 로 kill.
-
-    태그값은 해당 task 의 container_dir 절대경로다. 무조건 글로벌 sweep 은 동시
-    세션 간섭을 일으키므로 호출자가 항상 스코프 predicate 를 준다(I2)."""
-    from . import tmux
-    if not tmux.tmux_available():
-        return []
-    result = tmux.run_tmux(
-        ["list-panes", "-a", "-F", "#{pane_id}\t#{@okstra_container_run}"])
-    if result.returncode != 0:
-        return []
-    killed: list[str] = []
-    for line in result.stdout.splitlines():
-        parts = line.split("\t")
-        if len(parts) == 2 and parts[0] and parts[1] and match(parts[1]):
-            tmux.kill_pane(parts[0])
-            killed.append(parts[0])
-    return killed
-
-
 # --------------------------------------------------------------------------- #
 # argparse 디스패치(recap.py 패턴)
 # --------------------------------------------------------------------------- #
 
+_CLI_EPILOG = r"""Usage:
+  okstra container up [options]
+  okstra container status [options]
+  okstra container down [options]
+"""
+_CLI_DESCRIPTION = "Manage the okstra container runtime."
+
+
 def main(argv: list[str] | None = None) -> int:
-    parser = argparse.ArgumentParser(prog="okstra container")
+    parser = argparse.ArgumentParser(
+        description=_CLI_DESCRIPTION,
+        epilog=_CLI_EPILOG,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        prog="okstra container")
     sub = parser.add_subparsers(dest="command", required=True)
-    for name in ("up", "status", "logs", "stop-watcher", "down"):
+    for name in ("up", "status", "down"):
         sp = sub.add_parser(name)
         sp.add_argument("--project-root", required=True)
         sp.add_argument("--task-key", default="")
         sp.add_argument("--text", action="store_true")
         if name == "down":
             sp.add_argument("--all", action="store_true")
-        if name == "logs":
-            sp.add_argument("--service", default="")
-    watch = sub.add_parser("watch")  # watcher pane 내부에서 도는 장기 루프
-    watch.add_argument("--project-name", required=True)
-    watch.add_argument("--service", required=True)
-    watch.add_argument("--findings", required=True)
-    watch.add_argument("--scan-interval", type=float, default=5.0)
     args = parser.parse_args(argv)
-    if args.command == "watch":
-        run_service_watcher(
-            project_name=args.project_name, service=args.service,
-            findings_path=args.findings, scan_interval_seconds=args.scan_interval)
-        return 0
     result = _dispatch(args)
     print(
         render_container_text(args.command, result)
@@ -964,21 +620,16 @@ def main(argv: list[str] | None = None) -> int:
 
 def render_container_text(command: str, payload: dict) -> str:
     """container 명령별 승인된 상태만 고정 순서로 투영한다."""
-    if command not in {"up", "status", "logs", "stop-watcher", "down"}:
+    if command not in {"up", "status", "down"}:
         raise ValueError("unknown container text purpose")
     rows = [f"Okstra container {command}\n", line("Status", "ready")]
-    for label, key in (("Project name", "projectName"), ("Watchers dir", "watchersDir"),
-                       ("Note", "note")):
+    for label, key in (("Project name", "projectName"), ("Note", "note")):
         if key in payload:
             rows.append(line(label, payload.get(key)))
     if command == "up":
         rows.extend(_render_container_up(payload))
-    elif command in {"status", "logs"}:
-        rows.extend(_render_container_watchers(payload))
-        if command == "status":
-            rows.extend(_render_container_status(payload))
-    elif command == "stop-watcher":
-        rows.extend(_render_reaped_panes("Reaped pane", payload.get("reapedPanes")))
+    elif command == "status":
+        rows.extend(_render_container_status(payload))
     else:
         rows.extend(_render_container_down(payload))
     return "".join(rows)
@@ -990,26 +641,6 @@ def _render_container_up(payload: dict) -> list[str]:
         rows.append(line(f"Service {index} name", service))
     for index, warning in enumerate(payload.get("warnings") or [], 1):
         rows.append(line(f"Warning {index} text", warning))
-    watch = payload.get("watch") if isinstance(payload.get("watch"), dict) else {}
-    for label, key in (("Watcher enabled", "enabled"), ("Watcher session", "session"),
-                       ("Watcher note", "note")):
-        if key in watch:
-            rows.append(line(label, watch.get(key)))
-    for index, service in enumerate(watch.get("services") or [], 1):
-        rows.append(line(f"Watcher service {index} name", service))
-    return rows
-
-
-def _render_container_watchers(payload: dict) -> list[str]:
-    watchers = payload.get("watchers") if isinstance(payload.get("watchers"), dict) else {}
-    rows: list[str] = []
-    for index, (service, metadata) in enumerate(sorted(watchers.items()), 1):
-        rows.append(line(f"Watcher {index} service", service))
-        values = metadata if isinstance(metadata, dict) else {}
-        for label, key in (("pane ID", "paneId"), ("session", "sessionName"),
-                           ("findings path", "findingsPath")):
-            if key in values:
-                rows.append(line(f"Watcher {index} {label}", values.get(key)))
     return rows
 
 
@@ -1025,21 +656,12 @@ def _render_container_status(payload: dict) -> list[str]:
     return rows
 
 
-def _render_reaped_panes(prefix: str, raw_panes: object) -> list[str]:
-    panes = raw_panes if isinstance(raw_panes, list) else []
-    return [line(f"{prefix} {index}", pane) for index, pane in enumerate(panes, 1)]
-
-
 def _render_container_down(payload: dict) -> list[str]:
     downed = payload.get("downed") if isinstance(payload.get("downed"), list) else []
     rows: list[str] = []
     for index, item in enumerate(downed, 1):
         values = item if isinstance(item, dict) else {}
         rows.append(line(f"Downed {index} project name", values.get("projectName")))
-        rows.extend(_render_reaped_panes(
-            f"Downed {index} reaped pane", values.get("reapedPanes")
-        ))
-    rows.extend(_render_reaped_panes("Orphan pane", payload.get("orphanPanesReaped")))
     return rows
 
 
@@ -1049,11 +671,6 @@ def _dispatch(args) -> dict:
         return provision_container_group(project_root=pr, task_key=args.task_key)
     if args.command == "status":
         return status_container_group(project_root=pr, task_key=args.task_key)
-    if args.command == "logs":
-        return logs_container_group(
-            project_root=pr, task_key=args.task_key, service=args.service)
-    if args.command == "stop-watcher":
-        return stop_watcher_group(project_root=pr, task_key=args.task_key)
     return down_container_group(
         project_root=pr, task_key=args.task_key, all_groups=args.all)
 

package/runtime/python/okstra_ctl/context_cost.py

@@ -15,7 +15,7 @@ from typing import Iterable
 
 from okstra_ctl.paths import RunRef, runs_dir_of, task_manifest_file
 from okstra_ctl.task_target import resolve_task_root, project_rel
-from okstra_ctl.json_boundary import load_owned_object
+from okstra_ctl.json_boundary import JsonBoundaryError, load_owned_object
 
 
 INPUT_FILES = (
@@ -85,7 +85,7 @@ def _load_json(path: Path) -> dict:
         return {}
     try:
         data = load_owned_object(path, artifact="context cost input")
-    except Exception:
+    except JsonBoundaryError:
         return {}
     return data if isinstance(data, dict) else {}
 
@@ -481,8 +481,22 @@ def analyze_task_bundle(task_root: Path, project_root: Path) -> dict:
     }
 
 
+_CLI_EPILOG = r"""Usage:
+  okstra context-cost <task-root>
+  okstra context-cost <task-key> --project-root <dir>
+  okstra context-cost <task-key> --cwd <dir>
+
+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.
+"""
+
+
 def main(argv: list[str] | None = None) -> int:
     parser = argparse.ArgumentParser(
+        prog="okstra context-cost",
+        epilog=_CLI_EPILOG,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
         description="Estimate context/file-read cost for an okstra task bundle."
     )
     parser.add_argument("target", help="task root path or task-key")