okstra 0.186.7 → 0.187.0

package/runtime/python/okstra_ctl/worktree/provision.py

@@ -0,0 +1,385 @@
+"""worktree 를 실제로 만든다 — task 하나에 하나, stage 하나에 하나.
+
+이 파일만 부수 효과를 낸다: 레지스트리 예약, worktree 추가, sync 링크 설치,
+실패 시 되감기. 나머지 층은 전부 이 두 함수가 쓰려고 나뉘어 있다.
+`provision_task_worktree` 는 같은 task-key 로 다시 들어오면 기존 worktree 를
+그대로 돌려주고, `provision_stage_worktree` 는 base_commit 을 반드시 요구한다.
+"""
+from __future__ import annotations
+
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+
+from .. import worktree_registry
+from .decisions import preview_worktree_decision, resolve_stage_worktree_decision
+from .git_ops import (
+    _branch_exists,
+    _branch_exists_message,
+    _git,
+    _head_sha,
+    _resolve_commit_sha,
+    main_worktree_path,
+    remove_worktree_force,
+)
+from .linking import (
+    _copy_snapshot_files,
+    _link_sync_dirs,
+    _link_sync_files,
+    describe_sync_key_drift,
+    sync_file_key_names,
+    _seed_worktree_settings_symlink,
+)
+from .naming import _safe_segment
+
+
+@dataclass
+class WorktreeProvision:
+    """Result of `provision_task_worktree`.
+
+    status:
+      - "created": fresh worktree at `path` on `branch`
+      - "reused": registry already had this task-key; same path/branch
+        returned and no new `git worktree add` was executed
+      - "skipped-in-worktree": project_root is itself a non-main
+        worktree; the run reuses `project_root` and no new worktree is
+        materialised (registry NOT updated — that caller is already
+        isolated by virtue of its own worktree)
+      - "skipped-not-git": project_root has no `.git` (worktree path
+        cannot be provisioned; degrade gracefully)
+    """
+    status: str
+    path: str = ""          # absolute path of the task worktree (or project_root when reused)
+    branch: str = ""        # branch checked out in the worktree (empty when reused / not-git)
+    base_ref: str = ""      # commit SHA the worktree was branched from (empty when not created)
+    note: str = ""          # human-readable explanation, surfaced in team-state / manifests
+
+
+def _sync_key_drift_note(main_root: Path, entry) -> str:
+    """재사용되는 worktree 에 붙일 공유 sync 파일 키 드리프트 한 줄.
+
+    앞에 `; ` 를 붙인 형태로 돌려주므로 note 문자열에 그대로 이어 붙일 수 있고,
+    드리프트가 없으면 빈 문자열이라 종전 note 와 바이트가 같다.
+    """
+    if entry is None:
+        return ""
+    message = describe_sync_key_drift(
+        entry.sync_file_keys, sync_file_key_names(main_root)
+    )
+    if not message:
+        return ""
+    print(f"okstra-worktree: {message}", file=sys.stderr)
+    return f"; {message}"
+
+
+def provision_task_worktree(
+    *,
+    task_type: str,
+    project_root: Path,
+    project_id: str,
+    task_group_segment: str,
+    task_id_segment: str,
+    work_category: str,
+    base_ref: str = "",
+    require_base_ref: bool = False,
+) -> WorktreeProvision:
+    """Materialise (or reuse) the task worktree for this run.
+
+    First phase of a task-key creates the worktree on a new branch.
+    Subsequent phases of the same task-key look up the registry and
+    return the existing path + branch unchanged.
+
+    ``base_ref`` is the ref (branch name, tag, or commit SHA) to branch
+    the new worktree from on first phase. When empty, the main worktree's
+    current ``HEAD`` is used (legacy default; the CLI enforces a
+    non-empty value on first phase so callers go through the
+    AskUserQuestion menu in the okstra-run skill). Subsequent phases
+    ignore ``base_ref`` — the registered entry's base is reused.
+
+    Concurrency: callers must hold ``locks.worktree_provision_mutex`` for
+    this task-key (run.py's prepare flow does). The exists/branch pre-checks
+    and ``git worktree add`` here are not internally locked — only the
+    registry reserve row is — so unlocked concurrent calls race (TOCTOU).
+    flock is non-reentrant, hence the lock lives at the caller.
+
+    Raises:
+        RuntimeError when worktree creation fails (path clash on disk
+        that the registry does not know about, branch clash with a
+        different task-key, `git worktree add` non-zero). The caller
+        (`run.py`) catches and re-raises as PrepareError to keep a
+        single error surface.
+    """
+    decision = preview_worktree_decision(
+        project_root=project_root, project_id=project_id,
+        task_group_segment=task_group_segment, task_id_segment=task_id_segment,
+        work_category=work_category, base_ref=base_ref,
+    )
+
+    if decision.status == "skipped-not-git":
+        return WorktreeProvision(
+            status="skipped-not-git",
+            path=decision.path,
+            note=(
+                "worktree provisioning skipped: project_root is not inside a git "
+                "repository; task will operate directly on project_root"
+            ),
+        )
+
+    if decision.status == "skipped-in-worktree":
+        return WorktreeProvision(
+            status="skipped-in-worktree",
+            path=decision.path,
+            note=(
+                "worktree provisioning skipped: project_root is already inside a "
+                "non-main git worktree; task reuses the caller's worktree"
+            ),
+        )
+
+    safe_project = _safe_segment(project_id)
+    safe_group = _safe_segment(task_group_segment)
+    safe_task = _safe_segment(task_id_segment)
+
+    if decision.status == "reused":
+        worktree_registry.touch_phase(safe_project, safe_group, safe_task, task_type)
+        _seed_worktree_settings_symlink(Path(decision.path))
+        drift = _sync_key_drift_note(
+            main_worktree_path(project_root),
+            worktree_registry.lookup(safe_project, safe_group, safe_task),
+        )
+        return WorktreeProvision(
+            status="reused",
+            path=decision.path,
+            branch=decision.branch,
+            base_ref=decision.base_ref,
+            note=(
+                f"task worktree reused at {decision.path} on branch "
+                f"{decision.branch} (base {decision.base_ref[:12]}); phase {task_type}"
+                f"{drift}"
+            ),
+        )
+
+    # decision.status == "new" — proceed with creation
+    worktree_path = Path(decision.path)
+    branch = decision.branch
+
+    if worktree_path.exists():
+        raise RuntimeError(
+            f"task worktree path already exists but is not in the registry: "
+            f"{worktree_path}. Remove it with `git worktree remove <path>` "
+            "(or `rm -rf` if it is not a registered worktree) before retrying."
+        )
+    if _branch_exists(project_root, branch):
+        raise RuntimeError(_branch_exists_message(project_root, branch, "task"))
+
+    main_root = main_worktree_path(project_root)
+    requested_base = (base_ref or "").strip()
+    if not requested_base and require_base_ref:
+        raise RuntimeError(
+            "first-phase task worktree requires an explicit base ref; "
+            "pass `--base-ref <branch|tag|sha>` (or invoke through the "
+            "okstra-run skill which collects this interactively)"
+        )
+    if requested_base:
+        resolved_sha = _resolve_commit_sha(main_root, requested_base)
+        if not resolved_sha:
+            raise RuntimeError(
+                f"could not resolve base ref `{requested_base}` in main worktree "
+                f"({main_root}); ensure the branch/tag/SHA exists locally"
+            )
+        resolved_base_ref = resolved_sha
+        base_origin = requested_base
+    else:
+        resolved_base_ref = _head_sha(main_root)
+        if not resolved_base_ref:
+            raise RuntimeError(
+                "could not resolve HEAD sha in main worktree; cannot create task worktree"
+            )
+        base_origin = "HEAD"
+
+    worktree_path.parent.mkdir(parents=True, exist_ok=True)
+    res = _git(
+        main_root,
+        "worktree", "add", "-b", branch, str(worktree_path), resolved_base_ref,
+    )
+    if res.returncode != 0:
+        raise RuntimeError(
+            f"`git worktree add` failed (exit={res.returncode}): "
+            f"{(res.stderr or res.stdout).strip()}"
+        )
+
+    # Sync dirs sourced from the MAIN worktree so every task sees the
+    # same shared state regardless of which checkout invoked okstra.
+    linked = _link_sync_dirs(main_root, worktree_path)
+    linked_files = _link_sync_files(main_root, worktree_path)
+    sync_file_keys = sync_file_key_names(main_root)
+    snapshot_files = _copy_snapshot_files(main_root, worktree_path)
+    linked_parts: list[str] = []
+    if linked:
+        linked_parts.append(f"linked {', '.join(linked)}")
+    if linked_files:
+        linked_parts.append(f"linked-files {', '.join(linked_files)}")
+    if snapshot_files:
+        linked_parts.append(f"snapshot {', '.join(snapshot_files)}")
+    linked_suffix = ("; " + "; ".join(linked_parts)) if linked_parts else ""
+
+    try:
+        worktree_registry.reserve(
+            project_id=safe_project,
+            task_group=safe_group,
+            task_id=safe_task,
+            worktree_path=str(worktree_path),
+            branch=branch,
+            base_ref=resolved_base_ref,
+            phase=task_type,
+            sync_file_keys=sync_file_keys,
+        )
+    except RuntimeError:
+        # Roll back the on-disk worktree so the next attempt is not
+        # blocked by the lingering directory / branch.
+        remove_worktree_force(main_root, worktree_path)
+        _git(main_root, "branch", "-D", branch)
+        raise
+
+    _seed_worktree_settings_symlink(worktree_path)
+
+    base_label = (
+        f"{base_origin} @ {resolved_base_ref[:12]}"
+        if base_origin != "HEAD"
+        else f"HEAD @ {resolved_base_ref[:12]}"
+    )
+    return WorktreeProvision(
+        status="created",
+        path=str(worktree_path),
+        branch=branch,
+        base_ref=resolved_base_ref,
+        note=(
+            f"task worktree created at {worktree_path} on branch {branch} "
+            f"(base {base_label}; phase {task_type}){linked_suffix}"
+        ),
+    )
+
+
+def provision_stage_worktree(
+    *,
+    project_root: Path,
+    project_id: str,
+    task_group_segment: str,
+    task_id_segment: str,
+    work_category: str,
+    stage_number: int,
+    base_commit: str,
+) -> WorktreeProvision:
+    """Materialise an isolated worktree for one implementation stage.
+
+    Unlike `provision_task_worktree` (one worktree per task-key shared
+    across phases), this provisions a per-stage worktree branched from
+    `base_commit` at `<task-key>/stage-<N>/` on branch `<prefix>-<task>-s<N>`.
+    The stage-key (`<task-key>#stage-<N>`) is reserved atomically through
+    `worktree_registry`; re-entry of the same stage-key returns the
+    existing entry. Branch / on-disk conflicts roll back the worktree
+    before re-raising so a retry is not blocked.
+
+    Concurrency: callers must hold ``locks.worktree_provision_mutex`` for
+    the task-key, acquired BEFORE the Stage Run Claim reads the registry
+    (run.py does) — otherwise two `--stage auto` runs can select the same
+    stage and the loser silently enters the winner's worktree via the
+    "reused" path. flock is non-reentrant, hence the lock lives at the
+    caller.
+    """
+    if not base_commit:
+        raise RuntimeError("provision_stage_worktree requires a base_commit")
+
+    decision = resolve_stage_worktree_decision(
+        project_id=project_id,
+        task_group_segment=task_group_segment,
+        task_id_segment=task_id_segment,
+        work_category=work_category,
+        stage_number=stage_number,
+    )
+    if decision.status == "reused":
+        drift = _sync_key_drift_note(
+            main_worktree_path(project_root),
+            worktree_registry.lookup(
+                _safe_segment(project_id),
+                _safe_segment(task_group_segment),
+                _safe_segment(task_id_segment),
+                stage_number=stage_number,
+            ),
+        )
+        return WorktreeProvision(
+            status="reused",
+            path=decision.path,
+            branch=decision.branch,
+            base_ref=decision.base_ref,
+            note=(
+                f"stage {stage_number} worktree reused at "
+                f"{decision.path} on branch {decision.branch} "
+                f"(base {decision.base_ref[:12]}){drift}"
+            ),
+        )
+
+    safe_project = _safe_segment(project_id)
+    safe_group = _safe_segment(task_group_segment)
+    safe_task = _safe_segment(task_id_segment)
+    worktree_path = Path(decision.path)
+    branch = decision.branch
+
+    if worktree_path.exists():
+        raise RuntimeError(
+            f"stage worktree path already exists but is not in the registry: "
+            f"{worktree_path}. Remove it before retrying."
+        )
+    if _branch_exists(project_root, branch):
+        raise RuntimeError(_branch_exists_message(project_root, branch, "stage"))
+
+    main_root = main_worktree_path(project_root)
+    resolved_sha = _resolve_commit_sha(main_root, base_commit)
+    if not resolved_sha:
+        raise RuntimeError(
+            f"could not resolve base_commit `{base_commit}` in main worktree "
+            f"({main_root}); ensure the commit exists locally"
+        )
+
+    worktree_path.parent.mkdir(parents=True, exist_ok=True)
+    res = _git(
+        main_root,
+        "worktree", "add", "-b", branch, str(worktree_path), resolved_sha,
+    )
+    if res.returncode != 0:
+        raise RuntimeError(
+            f"`git worktree add` failed (exit={res.returncode}): "
+            f"{(res.stderr or res.stdout).strip()}"
+        )
+
+    _link_sync_dirs(main_root, worktree_path)
+    _link_sync_files(main_root, worktree_path)
+    _copy_snapshot_files(main_root, worktree_path)
+    sync_file_keys = sync_file_key_names(main_root)
+
+    try:
+        worktree_registry.reserve(
+            project_id=safe_project,
+            task_group=safe_group,
+            task_id=safe_task,
+            worktree_path=str(worktree_path),
+            branch=branch,
+            base_ref=resolved_sha,
+            phase="implementation",
+            stage_number=stage_number,
+            sync_file_keys=sync_file_keys,
+        )
+    except RuntimeError:
+        remove_worktree_force(main_root, worktree_path)
+        _git(main_root, "branch", "-D", branch)
+        raise
+
+    _seed_worktree_settings_symlink(worktree_path)
+
+    return WorktreeProvision(
+        status="created", path=str(worktree_path),
+        branch=branch, base_ref=resolved_sha,
+        note=(
+            f"stage {stage_number} worktree created at {worktree_path} "
+            f"on branch {branch} (base {resolved_sha[:12]})"
+        ),
+    )

package/runtime/python/okstra_ctl/worktree/sync_config.py

@@ -0,0 +1,181 @@
+"""worktree 로 옮겨 갈 경로 목록을 결정한다 — 그 목록을 쓰지는 않는다.
+
+`git worktree add` 는 추적되지 않는 최상위 항목을 가져오지 않는다. 어떤
+디렉터리·파일이 메인 체크아웃에서 새 worktree 로 따라와야 하는지가 여기서
+정해진다. 우선순위는 세 단계 — 환경 변수, `project.json`, 내장 기본값 — 이고
+앞의 것이 뒤를 REPLACE 한다(병합이 아니다).
+
+이 층은 git 을 부르지 않고 심링크도 걸지 않는다. 목록만 답한다.
+"""
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Optional
+
+from okstra_project.dirs import project_json_path
+
+from ..json_boundary import JsonBoundaryError, load_owned_object
+
+
+# Project-root directories that hold okstra task state, ignored by git, or
+# otherwise required for the executor to operate but NOT carried across by
+# `git worktree add`. Each is symlinked from the MAIN worktree into the new
+# worktree at provision time. Symlinks (not copies) so every task sees the
+# live shared state and disk/CPU cost stays near zero; the trade-off is
+# that any write through the link reaches the main worktree, which is
+# acceptable because okstra writes only to paths it owns: its task-scoped
+# subdirectory (e.g. `.okstra/tasks/<task-id>/runs/...`) and, for a
+# branch-mode code review, `.project-docs/code-reviews/<branch>/`.
+#
+# Override precedence (most-specific first):
+#   1. `OKSTRA_WORKTREE_SYNC_DIRS` env var — colon-separated list, REPLACES
+#      defaults. Empty string disables the feature entirely. One-off
+#      operator override.
+#   2. `worktreeSyncDirs` array in `.okstra/project.json` —
+#      project-level config, persists across runs. Same semantics: array
+#      REPLACES defaults, empty array disables.
+#   3. The built-in `DEFAULT_WORKTREE_SYNC_DIRS` below.
+DEFAULT_WORKTREE_SYNC_DIRS: tuple[str, ...] = (
+    ".project-docs",
+    ".scratch",
+    "graphify-out",
+    ".claude",
+)
+
+
+# Sync dirs materialised as a REAL directory whose children are symlinked one
+# by one, instead of a single symlink standing in for the whole directory.
+#
+# Why the split exists: git does not follow a symlink, so a symlinked directory
+# is one *file* to it. A project that ignores host config by its contents
+# (`.claude/*`) matches every child but never the bare `.claude` path, so the
+# symlink lands in `git status` as
+# `?? .claude` while the same directory is invisible in the main checkout. Any
+# plan step asserting a clean worktree then fails on okstra's own provisioning.
+# Linking the children instead reproduces the main checkout's shape, so
+# whatever the project's ignore rules do there, they do here too.
+#
+# Only `.claude` qualifies. The other sync dirs are shared okstra state that
+# okstra WRITES into, and a directory symlink is what makes a newly created
+# top-level entry land in the main checkout rather than diverging inside the
+# worktree. `.claude` is host configuration okstra reads; its one okstra write
+# is the fixed `settings.local.json` child seeded by
+# `_seed_worktree_settings_symlink`.
+CHILD_LINKED_SYNC_DIRS: tuple[str, ...] = (".claude",)
+
+
+# Project-root-relative FILES (not dirs) symlinked from MAIN → task worktree
+# at provision time. Same symlink semantics as `DEFAULT_WORKTREE_SYNC_DIRS`:
+# every task sees the live shared file. The split exists because the original
+# `_link_sync_dirs` helper only walked directories — a `.env` (or any
+# top-level file outside `.git`'s tracking) would otherwise be lost on every
+# new worktree, blocking verifier dispatches that depend on environment-
+# resolved secrets.
+#
+# Override precedence mirrors `DEFAULT_WORKTREE_SYNC_DIRS`:
+#   1. `OKSTRA_WORKTREE_SYNC_FILES` env var (colon-separated, REPLACES).
+#   2. `worktreeSyncFiles` array in `.okstra/project.json`.
+#   3. The built-in `DEFAULT_WORKTREE_SYNC_FILES` below.
+DEFAULT_WORKTREE_SYNC_FILES: tuple[str, ...] = (
+    ".env",
+)
+
+
+# Project-root-relative files COPIED (not symlinked) from MAIN → task worktree
+# at provision time, then `chmod 0o444` so the task cannot mutate the
+# snapshot. Used for live-mutating fixtures (e.g. `classifications.db`)
+# where the verifier needs to reproduce accuracy SQL against the same rows
+# the executor saw, without sharing the writable handle that would corrupt
+# the main worktree's copy. Default is empty — okstra has no opinion about
+# which fixtures any given project relies on; opt in per-project via
+# `worktreeSnapshotFiles` in `project.json` (or `OKSTRA_WORKTREE_SNAPSHOT_FILES`
+# for one-off operator override).
+DEFAULT_WORKTREE_SNAPSHOT_FILES: tuple[str, ...] = ()
+
+
+def _read_project_json_field(project_root: Path, field: str) -> Optional[tuple[str, ...]]:
+    """Read a string-array field from the project's okstra project.json.
+
+    Returns None if the field is absent or the file cannot be parsed (so
+    the caller falls back to defaults). Returns an empty tuple if the
+    field is explicitly an empty array (caller treats this as "disable").
+    A non-list value is treated as missing — we do not raise here because
+    field resolution must never block worktree provisioning.
+    """
+    target = project_json_path(project_root)
+    if not target.is_file():
+        return None
+    try:
+        data = load_owned_object(target, artifact="project config")
+    except (OSError, JsonBoundaryError):
+        return None
+    if not isinstance(data, dict):
+        return None
+    value = data.get(field)
+    if not isinstance(value, list):
+        return None
+    cleaned = tuple(
+        item.strip() for item in value
+        if isinstance(item, str) and item.strip()
+    )
+    return cleaned
+
+
+def _resolve_entries(
+    *,
+    env_var: str,
+    project_field: str,
+    default: tuple[str, ...],
+    project_root: Optional[Path],
+) -> tuple[str, ...]:
+    """Generic resolver shared by sync-dirs / sync-files / snapshot-files.
+
+    Precedence: env var (colon-separated, REPLACES) → project.json field →
+    built-in default. An empty env value or empty JSON array disables the
+    feature (returns `()`).
+    """
+    raw = os.environ.get(env_var)
+    if raw is not None:
+        raw = raw.strip()
+        if not raw:
+            return ()
+        return tuple(part for part in (p.strip() for p in raw.split(":")) if part)
+    if project_root is not None:
+        from_project = _read_project_json_field(project_root, project_field)
+        if from_project is not None:
+            return from_project
+    return default
+
+
+def _resolve_sync_dirs(project_root: Optional[Path] = None) -> tuple[str, ...]:
+    """Return the list of project-root-relative dirs to symlink into the
+    new worktree. Precedence: env var → project.json → built-in default.
+    See the comment above `DEFAULT_WORKTREE_SYNC_DIRS` for full semantics.
+    """
+    return _resolve_entries(
+        env_var="OKSTRA_WORKTREE_SYNC_DIRS",
+        project_field="worktreeSyncDirs",
+        default=DEFAULT_WORKTREE_SYNC_DIRS,
+        project_root=project_root,
+    )
+
+
+def _resolve_sync_files(project_root: Optional[Path] = None) -> tuple[str, ...]:
+    """File-level counterpart to `_resolve_sync_dirs` (FU-V2)."""
+    return _resolve_entries(
+        env_var="OKSTRA_WORKTREE_SYNC_FILES",
+        project_field="worktreeSyncFiles",
+        default=DEFAULT_WORKTREE_SYNC_FILES,
+        project_root=project_root,
+    )
+
+
+def _resolve_snapshot_files(project_root: Optional[Path] = None) -> tuple[str, ...]:
+    """Read-only snapshot file list (FU-V3)."""
+    return _resolve_entries(
+        env_var="OKSTRA_WORKTREE_SNAPSHOT_FILES",
+        project_field="worktreeSnapshotFiles",
+        default=DEFAULT_WORKTREE_SNAPSHOT_FILES,
+        project_root=project_root,
+    )

package/runtime/python/okstra_ctl/worktree_cli.py

@@ -0,0 +1,75 @@
+"""`okstra worktree-lookup` / `okstra worktree-status` 의 핸들러.
+
+원래 `src/commands/execute/worktree-{lookup,status}.mts` 의 문자열 리터럴 안에
+있던 코드다(docs/coding-rules.md R1 위반). 로직은 그대로 옮겼다.
+"""
+from __future__ import annotations
+
+import json
+from dataclasses import asdict
+from pathlib import Path
+
+from . import worktree_registry
+from .ids import _safe_fs_segment
+from .worktree import (
+    dirty_entries_excluding_okstra,
+    is_git_work_tree,
+    nested_worktree_excludes,
+    okstra_clean_gate_excludes,
+)
+
+
+def _entry_payload(entry) -> dict:
+    """registry 의 snake_case dataclass 를 CLI 의 camelCase 계약으로 옮긴다."""
+    d = asdict(entry)
+    return {
+        "taskKey": d.get("task_key"),
+        "projectId": d.get("project_id"),
+        "taskGroup": d.get("task_group"),
+        "taskId": d.get("task_id"),
+        "worktreePath": d.get("worktree_path"),
+        "branch": d.get("branch"),
+        "baseRef": d.get("base_ref"),
+        "createdAt": d.get("created_at"),
+        "lastPhase": d.get("last_phase"),
+        "status": d.get("status"),
+    }
+
+
+def lookup(args: argparse.Namespace) -> int:
+    entry = worktree_registry.lookup(
+        _safe_fs_segment(args.project_id),
+        _safe_fs_segment(args.task_group),
+        _safe_fs_segment(args.task_id),
+    )
+    if entry is None:
+        print(json.dumps({"ok": True, "entry": None}))
+        return 0
+    print(json.dumps(
+        {"ok": True, "entry": _entry_payload(entry)},
+        ensure_ascii=False, default=str, indent=2,
+    ))
+    return 0
+
+
+def status(args: argparse.Namespace) -> int:
+    path = Path(args.path).resolve()
+    if not path.is_dir():
+        print(json.dumps({"ok": False, "stage": "input",
+                          "reason": f"not a directory: {path}"}))
+        return 2
+    if not is_git_work_tree(path):
+        print(json.dumps({"ok": False, "stage": "input",
+                          "reason": f"not inside a git work tree: {path}"}))
+        return 2
+
+    entries = dirty_entries_excluding_okstra(path)
+    excluded = [*okstra_clean_gate_excludes(path), *nested_worktree_excludes(path)]
+    print(json.dumps({
+        "ok": True,
+        "path": str(path),
+        "clean": not entries,
+        "entries": entries,
+        "excluded": excluded,
+    }, ensure_ascii=False, indent=2))
+    return 1 if (args.check_clean and entries) else 0

package/runtime/python/okstra_ctl/worktree_lookup_cli.py

@@ -0,0 +1,39 @@
+"""`okstra worktree-lookup` 의 진입점.
+
+핸들러는 [worktree_cli.lookup] 에 있다. 이 모듈은 자기 이름의 파서만 갖는다 —
+`python3 -m` 대상 하나가 `okstra` 명령 하나에 대응해야 `--help` 의 prog 와
+사용법이 사용자가 실제로 치는 명령과 같아진다.
+"""
+from __future__ import annotations
+
+import argparse
+
+from .worktree_cli import lookup
+
+_CLI_EPILOG = r"""Usage:
+  okstra worktree-lookup <project-id> <task-group> <task-id>
+
+The three identifiers are slugified by the runtime before lookup, so
+case/whitespace variants are tolerated.
+
+Output: JSON with the registry entry (worktreePath, branch, baseRef,
+status, lastPhase, createdAt). Emits {"ok": true, "entry": null} when
+the task-key has no active worktree.
+"""
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="okstra worktree-lookup",
+        description="Look up the registered worktree for a task-key.",
+        epilog=_CLI_EPILOG,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument("project_id", metavar="project-id")
+    parser.add_argument("task_group", metavar="task-group")
+    parser.add_argument("task_id", metavar="task-id")
+    return lookup(parser.parse_args(argv))
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())