okstra 0.97.1 → 0.98.0

package/runtime/python/okstra_ctl/container_registry.py

@@ -0,0 +1,93 @@
+"""Per-task container registry — flock 보조 인덱스.
+
+docker 라벨은 컨테이너 존재 여부의 기준값(SSOT)이지만 tmux session/pane id 나
+findings 파일 경로 같은 운영 메타데이터는 추적하지 못한다. 이 모듈은 task root
+하위 ``container/registry.json`` 에 그런 보조 정보를 가벼운 dict 로 보관한다.
+
+flock + tmp+``os.replace`` 원자 쓰기 idiom 은 ``worktree_registry`` 의
+``_registry_lock``/``_load``/``_save`` 를 그대로 복제했고, lock/registry 경로만
+``paths.container_paths()`` 로 해소해 전역 ``~/.okstra/worktrees/registry.json``
+과 분리한다. dict 구조는 ``{"services": {<svc>: {session_name, pane_id,
+findings_path}}}`` 한 가지뿐 — worktree_registry 의 dataclass 는 복제하지 않는다.
+"""
+from __future__ import annotations
+
+import contextlib
+import fcntl
+import json
+import os
+from pathlib import Path
+
+from . import paths
+
+
+@contextlib.contextmanager
+def _registry_lock(lock_path: Path):
+    """``container/registry.json.lock`` 에 대한 배타 flock. worktree_registry 의
+    ``_registry_lock`` 과 동일한 패턴이되 경로를 인자로 받는다(전역 lock 과 분리)."""
+    lock_path.parent.mkdir(parents=True, exist_ok=True)
+    if not lock_path.exists():
+        lock_path.touch()
+    f = lock_path.open("r+")
+    try:
+        fcntl.flock(f.fileno(), fcntl.LOCK_EX)
+        yield
+    finally:
+        f.close()
+
+
+def _load(registry_path: Path) -> dict:
+    if not registry_path.exists():
+        return {"services": {}}
+    try:
+        data = json.loads(registry_path.read_text())
+    except (OSError, json.JSONDecodeError):
+        return {"services": {}}
+    data.setdefault("services", {})
+    return data
+
+
+def _save(registry_path: Path, data: dict) -> None:
+    registry_path.parent.mkdir(parents=True, exist_ok=True)
+    tmp = registry_path.with_suffix(".json.tmp")
+    tmp.write_text(json.dumps(data, indent=2, ensure_ascii=False) + "\n")
+    os.replace(tmp, registry_path)
+
+
+def reserve(
+    project_root: Path, group: str, task_id: str, service: str,
+    *, session_name: str, pane_id: str, findings_path: str,
+) -> None:
+    """``service`` 의 tmux session/pane/findings 메타데이터를 등록한다."""
+    cp = paths.container_paths(project_root, group, task_id)
+    with _registry_lock(cp["registry_lock"]):
+        data = _load(cp["registry"])
+        data["services"][service] = {
+            "session_name": session_name,
+            "pane_id": pane_id,
+            "findings_path": findings_path,
+        }
+        _save(cp["registry"], data)
+
+
+def lookup(project_root: Path, group: str, task_id: str) -> dict:
+    """현재 registry dict 를 돌려준다. 파일 부재 시 ``{"services": {}}``."""
+    cp = paths.container_paths(project_root, group, task_id)
+    with _registry_lock(cp["registry_lock"]):
+        return _load(cp["registry"])
+
+
+def release(project_root: Path, group: str, task_id: str, service: str) -> None:
+    """``service`` 항목 하나만 제거한다(없으면 no-op)."""
+    cp = paths.container_paths(project_root, group, task_id)
+    with _registry_lock(cp["registry_lock"]):
+        data = _load(cp["registry"])
+        data["services"].pop(service, None)
+        _save(cp["registry"], data)
+
+
+def clear(project_root: Path, group: str, task_id: str) -> None:
+    """모든 service 항목을 비운다."""
+    cp = paths.container_paths(project_root, group, task_id)
+    with _registry_lock(cp["registry_lock"]):
+        _save(cp["registry"], {"services": {}})

package/runtime/python/okstra_ctl/error_zip.py

@@ -16,7 +16,7 @@ from pathlib import Path
 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
+from okstra_ctl.paths import okstra_home, resolve_under_root
 
 
 def _run_dirs(home: Path) -> list[tuple[str, Path]]:
@@ -26,13 +26,13 @@ def _run_dirs(home: Path) -> list[tuple[str, Path]]:
     for row in rows:
         project_root = str(row.get("projectRoot", ""))
         run_dir_rel = str(row.get("runDirRel", ""))
-        if not project_root or not run_dir_rel:
-            continue
         key = (project_root, run_dir_rel)
         if key in seen:
             continue
         seen.add(key)
-        out.append((project_root, Path(project_root) / run_dir_rel))
+        run_dir = resolve_under_root(project_root, run_dir_rel)
+        if run_dir is not None:
+            out.append((project_root, run_dir))
     return out
 
 

package/runtime/python/okstra_ctl/handoff.py

@@ -388,7 +388,7 @@ def _parse_stages_csv(raw: str) -> List[int]:
 def main(argv: Optional[list] = None) -> int:
     import argparse
 
-    from .run import _parse_stage_map_into_ctx
+    from .run import _parse_stage_map_into_ctx, PrepareError
 
     p = argparse.ArgumentParser(prog="okstra handoff")
     sub = p.add_subparsers(dest="cmd", required=True)
@@ -466,6 +466,12 @@ def main(argv: Optional[list] = None) -> int:
     except HandoffError as exc:
         print(json.dumps({"error": str(exc)}, ensure_ascii=False))
         return 1
+    except PrepareError as exc:
+        # _parse_stage_map_into_ctx 가 빈/손상 Stage Map 을 거부하면 PrepareError 가
+        # 오른다(HandoffError 의 형제 — 위 except 로 안 잡힘). JSON 계약을 깨고
+        # traceback 으로 죽지 않도록 error envelope + exit 1 로 처리한다.
+        print(json.dumps({"error": str(exc)}, ensure_ascii=False))
+        return 1
     print(json.dumps(out, ensure_ascii=False, indent=2))
     return 0
 

package/runtime/python/okstra_ctl/ids.py

@@ -1,9 +1,15 @@
-"""runId 빌드/파싱/세그먼트 escape, 세션명. 외부 모듈 의존 없음."""
+"""runId 빌드/파싱/세그먼트 escape, 세션명, container compose 라벨."""
 from __future__ import annotations
 
+import hashlib as _hashlib
 import re as _re
 from typing import Dict
 
+from okstra_project.state import slugify as _slugify
+
+# docker compose project name 길이 상한. compose 는 [a-z0-9][a-z0-9_-]* 만 허용한다.
+CONTAINER_PROJECT_NAME_MAX = 60
+
 
 # runId 형식: "<project-id>/<task-group>/<task-id>/<task-type>/r<run-seq>"
 # task-type 이 포함되는 이유: okstra.sh 의 RUN_DIR 은 task-type 단위 하위 디렉터리이고
@@ -82,3 +88,36 @@ def run_id_to_session_name(run_id: str) -> str:
 def slugify_task_segment(value: str) -> str:
     """Match okstra.sh slugify_value for task directory segments."""
     return _re.sub(r"[^a-z0-9]+", "-", value.lower()).strip("-")
+
+
+def build_container_session_name(project_id: str, group: str, task_id: str) -> str:
+    """container detached tmux 세션명을 합친다 → 'okstra-container-<slug>'.
+
+    세그먼트는 task_dir 가 쓰는 slugify_task_segment 와 동일 규칙으로 정규화해
+    세션명 slug 가 프로젝트 디스크 경로 slug 와 분기하지 않게 한다.
+    """
+    seg = slugify_task_segment
+    return f"okstra-container-{seg(project_id)}-{seg(group)}-{seg(task_id)}"
+
+
+def compose_project_name(project_id: str, task_group: str, task_id: str) -> str:
+    """docker compose project name 을 합친다(순수 계산).
+
+    세그먼트 정규화는 ``paths.task_dir`` 가 쓰는 slug 함수(okstra_project.state.
+    slugify)와 동일 함수를 써서 라벨(이 이름이 SSOT)↔디스크 경로의 slug 가
+    분기하지 않게 한다. 상한(``CONTAINER_PROJECT_NAME_MAX``) 초과 시 읽기 좋은
+    본문을 앞에서 자르고 끝에 전체 이름의 해시 8자리를 붙인다 — 단순 prefix-cut 은
+    task_group 만 다른 두 task-key 를 같은 이름으로 collapse 시켜(라벨 SSOT 충돌로
+    한 task 의 down 이 형제 task 컨테이너까지 회수) 위험하므로, 해시로 distinct 를
+    보장하고 상한도 항상 만족시킨다."""
+    def seg(v: str) -> str:
+        return _slugify(v) or "x"  # 빈 슬러그 방지(compose 는 [a-z0-9] 시작 요구)
+
+    proj, grp, task = seg(project_id), seg(task_group), seg(task_id)
+    name = f"okstra-{proj}-{grp}-{task}"
+    if len(name) <= CONTAINER_PROJECT_NAME_MAX:
+        return name
+    digest = _hashlib.sha1(name.encode("utf-8")).hexdigest()[:8]
+    body_budget = CONTAINER_PROJECT_NAME_MAX - len("okstra-") - 1 - len(digest)
+    body = f"{proj}-{grp}-{task}"[:body_budget].rstrip("-")
+    return f"okstra-{body}-{digest}"

package/runtime/python/okstra_ctl/listing.py

@@ -7,6 +7,7 @@ from datetime import datetime, timedelta, timezone
 from pathlib import Path
 from typing import List, Optional
 
+from .paths import resolve_under_root
 from .reconcile import _parse_iso
 from .run_index_row import read_run_index
 
@@ -174,8 +175,5 @@ def format_show(row: dict) -> str:
 
 
 def absolute_final_report_path(row: dict) -> Optional[Path]:
-    project_root = row.get("projectRoot", "")
-    rel = row.get("finalReportRel", "")
-    if not project_root or not rel:
-        return None
-    return (Path(project_root) / rel).resolve()
+    target = resolve_under_root(row.get("projectRoot", ""), row.get("finalReportRel", ""))
+    return target.resolve() if target is not None else None

package/runtime/python/okstra_ctl/log_report.py

@@ -0,0 +1,102 @@
+"""Read-side inventory of wrapper sidecar logs.
+
+`<project-root>/.okstra/tasks/**/runs/*/prompts/*.log` 를 스캔해 크기·mtime 을
+수집하고 task-type/worker/seq 를 path 에서 파싱한 뒤, top-largest 목록과 per-task
+합계를 만든다. skill markdown 이 raw `find`(OS별 분기) + 손-집계로 하던 일을 코드
+SSOT 로 옮긴 것 — read-only(삭제하지 않는다). cleanup 명령 제시는 호출자(skill)에
+남긴다.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from okstra_project import resolve_project_root
+
+
+def _project_id(project_root: Path) -> str:
+    try:
+        return json.loads((project_root / ".okstra" / "project.json").read_text(encoding="utf-8")).get("projectId", "")
+    except (OSError, ValueError):
+        return ""
+
+
+def _parse(parts: tuple, stem: str) -> dict:
+    group = parts[0] if len(parts) > 0 else ""
+    task_id = parts[1] if len(parts) > 1 else ""
+    phase = ""
+    if "runs" in parts:
+        i = parts.index("runs")
+        if i + 1 < len(parts):
+            phase = parts[i + 1]
+    worker = stem.split("-worker-prompt-")[0] if "-worker-prompt-" in stem else ""
+    seq = stem.rsplit("-", 1)[-1] if "-" in stem else ""
+    return {"taskGroup": group, "taskId": task_id, "phase": phase, "worker": worker, "seq": seq}
+
+
+def _per_task(files: list[dict]) -> list[dict]:
+    acc: dict[str, dict] = {}
+    for f in files:
+        tk = f["taskKey"]
+        if not tk:
+            continue
+        a = acc.get(tk)
+        if a is None:
+            a = acc[tk] = {"taskKey": tk, "fileCount": 0, "totalBytes": 0,
+                           "oldestEpoch": f["mtimeEpoch"], "newestEpoch": f["mtimeEpoch"]}
+        a["fileCount"] += 1
+        a["totalBytes"] += f["sizeBytes"]
+        a["oldestEpoch"] = min(a["oldestEpoch"], f["mtimeEpoch"])
+        a["newestEpoch"] = max(a["newestEpoch"], f["mtimeEpoch"])
+    return sorted(acc.values(), key=lambda a: a["totalBytes"], reverse=True)
+
+
+def scan_logs(logs_root: Path, project_root: Path, top: int = 20) -> dict:
+    project_id = _project_id(project_root)
+    files: list[dict] = []
+    if logs_root.is_dir():
+        for p in logs_root.rglob("*.log"):
+            parts = p.relative_to(logs_root).parts
+            if "runs" not in parts or "prompts" not in parts:
+                continue
+            try:
+                size = p.stat().st_size
+                mtime = int(p.stat().st_mtime)
+            except OSError:
+                continue
+            meta = _parse(parts, p.stem)
+            tk = f"{project_id}:{meta['taskGroup']}:{meta['taskId']}" if meta["taskGroup"] else ""
+            files.append({"path": str(p), "sizeBytes": size, "mtimeEpoch": mtime,
+                          "taskKey": tk, **meta})
+    files.sort(key=lambda f: f["sizeBytes"], reverse=True)
+    return {
+        "logsRoot": str(logs_root),
+        "topLargest": files[:top],
+        "perTask": _per_task(files),
+        "totals": {"fileCount": len(files),
+                   "totalBytes": sum(f["sizeBytes"] for f in files),
+                   "taskCount": len({f["taskKey"] for f in files if f["taskKey"]})},
+    }
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="okstra log-report",
+        description="Inventory wrapper sidecar logs by size and task (read-only).")
+    parser.add_argument("--project-root", default="")
+    parser.add_argument("--cwd", default=".")
+    parser.add_argument("--top", type=int, default=20, help="topLargest entry count")
+    parser.add_argument("--json", action="store_true", help="emit JSON (always on)")
+    args = parser.parse_args(argv)
+
+    project_root = resolve_project_root(explicit_root=args.project_root, cwd=args.cwd)
+    result = {"ok": True, "projectRoot": str(project_root)}
+    result.update(scan_logs(project_root / ".okstra" / "tasks", project_root, top=args.top))
+    print(json.dumps(result, ensure_ascii=False, indent=2))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))

package/runtime/python/okstra_ctl/pane_reclaim.py

@@ -6,6 +6,7 @@ import json
 import sys
 from pathlib import Path
 
+from .paths import resolve_under_root
 from .reconcile import NON_TERMINAL_RECENT_STATUSES
 from .wrapper_status import read_wrapper_status
 
@@ -30,14 +31,14 @@ def active_run_dirs(home: Path) -> list[Path]:
             row = json.loads(line)
         except json.JSONDecodeError:
             continue
-        rel = row.get("runDirRel")
-        root = row.get("projectRoot")
         # 회수 대상(진행 중) 집합은 reconcile 의 NON_TERMINAL_RECENT_STATUSES 가
         # SSOT. reserving 은 아직 run-dir 산출물이 없어(= 회수할 pane 이 없어) 이
         # 집합에 들어있지 않으므로 자연히 제외된다(allowlist).
-        if not rel or not root or row.get("status") not in NON_TERMINAL_RECENT_STATUSES:
+        if row.get("status") not in NON_TERMINAL_RECENT_STATUSES:
             continue
-        dirs.append(Path(root) / rel)
+        run_dir = resolve_under_root(row.get("projectRoot"), row.get("runDirRel"))
+        if run_dir is not None:
+            dirs.append(run_dir)
     return dirs
 
 

package/runtime/python/okstra_ctl/paths.py

@@ -31,8 +31,10 @@ __all__ = [
     "DISCOVERY_RELATIVE",
     "compute_run_paths",
     "next_run_seq",
+    "resolve_under_root",
     "task_dir",
     "task_runs_dir",
+    "container_paths",
     "okstra_home",
 ]
 
@@ -56,6 +58,23 @@ def task_runs_dir(project_root: Path, task_group: str, task_id: str) -> Path:
     return task_dir(project_root, task_group, task_id) / "runs"
 
 
+def container_paths(project_root: Path, task_group: str, task_id: str) -> dict:
+    """container 산출물 경로 묶음(순수 계산, mkdir 금지).
+
+    task root 하위 ``container/`` 디렉터리에 deploy 산출물을 모은다. base 가
+    ``task_dir`` 에서 파생되므로 라벨(compose project name)↔디스크 경로의 slug
+    규칙이 자동으로 일치한다."""
+    base = task_dir(project_root, task_group, task_id) / "container"
+    return {
+        "container_dir": base,
+        "env_override": base / "env.override",
+        "registry": base / "registry.json",
+        "registry_lock": base / "registry.json.lock",
+        "deploy_state": base / "deploy-state.json",
+        "watchers_dir": base / "watchers",
+    }
+
+
 def next_run_seq(run_seq_dir: Path, task_type_segment: str) -> int:
     """run_seq_dir 안에서 `*-<task-type>-NNN.<ext>` 파일을 스캔해 다음 seq 번호를
     돌려준다. 디렉터리 부재 시 1.
@@ -84,6 +103,27 @@ def _rel(project_root: Path, target: Path) -> str:
         return str(target)
 
 
+def resolve_under_root(
+    project_root: str | Path | None, rel: str | None
+) -> Path | None:
+    """글로벌 인덱스의 신뢰 불가 상대경로 필드(runDirRel/finalReportRel/
+    teamStatePath 등)를 project_root 기준 절대경로로 푼다(_rel 의 역).
+
+    이 필드들은 신뢰할 수 없어 절대경로나 '..' 가 들어오면 결합 결과가
+    project_root 밖을 가리킬 수 있다(`Path('/p') / '/etc'` → `/etc`). 루트 하위로
+    떨어지지 않거나 입력이 비면 None 을 돌려준다. 결합 결과 자체는 resolve 하지
+    않고 그대로 돌려준다 — pane 태그 매칭이 compute_run_paths 의 un-resolved
+    RUN_DIR 문자열에 의존하므로 containment 검사에만 resolve 를 쓴다(절대경로가
+    필요한 호출자는 반환값에 직접 .resolve() 한다)."""
+    if not project_root or not rel:
+        return None
+    root = Path(project_root)
+    target = root / rel
+    if not target.resolve().is_relative_to(root.resolve()):
+        return None
+    return target
+
+
 def compute_run_paths(
     *,
     project_root: Path,

package/runtime/python/okstra_ctl/plan_run_root.py

@@ -0,0 +1,78 @@
+"""implementation-planning run-root 해소 규칙의 단일 참조점.
+
+`plan_run_root` 는 한 planning run 의 산출물 루트다. consumers.jsonl(stage 완료
+원장) 과 approved-plan(final-report) 이 모두 이 루트 기준으로 놓인다.
+
+두 진입점이 같은 layout 규칙을 공유한다:
+- final-verification 은 사용자가 넘긴 approved-plan 파일 경로에서 역산한다
+  (``<plan_run_root>/reports/final-report-...md`` → ``parents[1]``).
+- container 는 approved-plan 입력이 없으므로 task-key 로 planning run 디렉터리를
+  스캔해 latest done run 을 고른다.
+"""
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import NamedTuple
+
+from .stage_targets import PrepareError
+
+_FINAL_REPORT_RE = re.compile(r"final-report-implementation-planning-(\d+)\.md$")
+
+
+class PlanRun(NamedTuple):
+    """task-key 로 역추적한 planning run: 산출물 루트 + approved-plan(final-report) 경로."""
+    run_root: Path
+    approved_plan_path: str
+
+
+def plan_run_root_from_approved_plan(approved_plan_path: str | Path) -> Path:
+    """approved-plan(final-report) 경로에서 plan_run_root 를 역산한다.
+
+    final-report 는 ``<plan_run_root>/reports/final-report-...md`` 에 놓이므로
+    ``parents[1]`` 이 run-root 다. run.py(final-verification) 와 container 가
+    이 한 규칙을 공유한다."""
+    return Path(approved_plan_path).resolve().parents[1]
+
+
+def resolve_plan_run_root_by_task_key(
+    *, project_root: Path, task_group: str, task_id: str,
+) -> PlanRun:
+    """task-key 로 implementation-planning run 을 역추적한다.
+
+    container 는 approved-plan 입력이 없어 디스크에서 planning run 을 찾아야 한다.
+    ``<task_dir>/runs/implementation-planning/reports/`` 의 final-report 들을
+    스캔해 done consumers 를 가진 run 중 seq 가 가장 큰(latest) run 의 run-root 와
+    그 final-report 경로를 돌려준다. done run 이 없거나 모호하면 PrepareError.
+    """
+    from . import paths
+    from .consumers import read_consumers
+
+    reports_dir = (
+        paths.task_dir(project_root, task_group, task_id)
+        / "runs" / "implementation-planning" / "reports"
+    )
+    if not reports_dir.is_dir():
+        raise PrepareError(
+            "container up: implementation-planning run 을 찾을 수 없습니다 "
+            f"({reports_dir} 없음). 먼저 implementation-planning 을 완료하거나 "
+            "approved-plan 경로를 직접 지정하세요."
+        )
+    candidates: list[tuple[int, Path, Path]] = []
+    for report in reports_dir.glob("final-report-implementation-planning-*.md"):
+        m = _FINAL_REPORT_RE.search(report.name)
+        if not m:
+            continue
+        run_root = plan_run_root_from_approved_plan(report)
+        done = [r for r in read_consumers(run_root) if r.get("status") == "done"]
+        if done:
+            candidates.append((int(m.group(1)), run_root, report))
+    if not candidates:
+        raise PrepareError(
+            "container up: done 상태의 implementation-planning run 이 없습니다. "
+            "stage 를 완료(implementation done)한 뒤 다시 시도하거나 approved-plan "
+            "경로를 직접 지정하세요."
+        )
+    candidates.sort(key=lambda c: c[0])
+    _, run_root, report = candidates[-1]
+    return PlanRun(run_root=run_root, approved_plan_path=str(report))

package/runtime/python/okstra_ctl/reconcile.py

@@ -9,6 +9,7 @@ from typing import Optional
 
 from .jsonl import append_jsonl, rotate_recent_if_needed
 from .locks import central_lock
+from .paths import resolve_under_root
 from .project_meta import upsert_project_meta
 from .run_index_row import read_run_index, slim_run_row
 
@@ -61,10 +62,11 @@ def _read_run_manifest_validation(project_root: Path, run_dir_rel: str,
     완료/실패 여부를 정확히 반영하기 위함 — 단순히 final-report 존재만으로
     'passed' 로 판정하면 contract-violation/failed 를 잘못 기록한다.
     """
-    if not run_dir_rel:
+    run_dir = resolve_under_root(project_root, run_dir_rel)
+    if run_dir is None:
         return "not-run"
     suffix = f"-{task_type}-{run_seq:03d}"
-    manifest = project_root / run_dir_rel / "manifests" / f"run-manifest{suffix}.json"
+    manifest = run_dir / "manifests" / f"run-manifest{suffix}.json"
     if not manifest.is_file():
         return "not-run"
     try:

package/runtime/python/okstra_ctl/resolve_task_key.py

@@ -0,0 +1,54 @@
+"""bare task-id → task-catalog.json 후보 entry 목록(skill 공용 해석기).
+
+skill markdown 이 복제하던 "catalog 를 읽어 taskId 를 case-insensitive 매칭 →
+0/1/N 분기" 를 단일 CLI 진입점으로 수렴시킨다. okstra_project.resolve_task_id
+가 SSOT 이고, 이 모듈은 project-root 해석 + JSON 정형화만 한다.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+from okstra_project import (
+    ResolverError,
+    StateError,
+    resolve_project_root,
+    resolve_task_id,
+)
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        description="Resolve a bare task-id to candidate task-keys from the catalog."
+    )
+    parser.add_argument("task_id", help="bare task-id (case-insensitive)")
+    parser.add_argument("--task-group", default="", help="scope match to this task-group")
+    parser.add_argument("--project-root", default="", help="project root for catalog lookup")
+    parser.add_argument("--cwd", default=".", help="cwd for project root resolution")
+    parser.add_argument("--json", action="store_true", help="emit JSON (always on)")
+    args = parser.parse_args(argv)
+
+    try:
+        project_root = resolve_project_root(explicit_root=args.project_root, cwd=args.cwd)
+    except ResolverError as exc:
+        print(json.dumps({"ok": False, "stage": "resolve", "reason": str(exc)}))
+        return 2
+
+    try:
+        matches = resolve_task_id(
+            project_root, args.task_id, task_group=args.task_group or None
+        )
+    except StateError as exc:
+        print(json.dumps({"ok": False, "stage": "catalog", "reason": str(exc)}))
+        return 2
+
+    print(json.dumps(
+        {"ok": True, "projectRoot": str(project_root), "matches": matches},
+        ensure_ascii=False, indent=2,
+    ))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))