okstra 0.96.1 → 0.97.0

package/runtime/python/okstra_ctl/error_zip.py

@@ -0,0 +1,319 @@
+"""cross-project errors-*.jsonl 수집·집계·익명화·zip 생성 (read-only).
+
+글로벌 run-index(recent/active)를 순회해 모든 타겟의 에러 로그를 모은다.
+errorType 값에 분기하지 않는 data-driven 처리.
+"""
+from __future__ import annotations
+
+import argparse
+import datetime as dt
+import json
+import re
+import sys
+import zipfile
+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
+
+
+def _run_dirs(home: Path) -> list[tuple[str, Path]]:
+    rows = read_jsonl(home / "recent.jsonl") + read_jsonl(home / "active.jsonl")
+    seen: set[tuple[str, str]] = set()
+    out: 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))
+    return out
+
+
+def _logs_in_run_dir(run_dir: Path) -> list[Path]:
+    flat = run_dir.glob("logs/errors-*.jsonl")
+    # stage-*/logs: 정상 index 에선 비활성, 비정형 트리(과거 stage-isolated 잔재) 방어용.
+    staged = run_dir.glob("stage-*/logs/errors-*.jsonl")
+    return sorted(set(flat) | set(staged))
+
+
+def collect_records(home: Path) -> tuple[list[dict], dict]:
+    records: list[dict] = []
+    project_roots: set[str] = set()
+    reachable = 0
+    unreachable = 0
+    for project_root, run_dir in _run_dirs(home):
+        if not run_dir.exists():
+            unreachable += 1
+            continue
+        logs = _logs_in_run_dir(run_dir)
+        if not logs:
+            continue
+        reachable += 1
+        recs, _ = parse_records(logs)
+        for rec in recs:
+            rec["_projectRoot"] = project_root
+            records.append(rec)
+        project_roots.add(project_root)
+    stats = {
+        "runCount": reachable,
+        "unreachableRuns": unreachable,
+        "projectRoots": sorted(project_roots),
+    }
+    return records, stats
+
+
+KEEP_FIELDS = (
+    "ts", "taskKey", "phase", "agent", "agentRole", "source",
+    "errorType", "command", "exitCode", "message", "stderrExcerpt",
+)
+
+
+def _token_map(records: list[dict]) -> dict:
+    roots = sorted({str(r.get("_projectRoot", "")) for r in records if r.get("_projectRoot")})
+    return {root: f"proj-{i}" for i, root in enumerate(roots, start=1)}
+
+
+_HOME_USER = re.compile(r"/Users/[^/\s]+")
+_LINUX_USER = re.compile(r"/home/[^/\s]+")
+# zip 은 프로젝트 간 공유되므로 자유 텍스트의 잔여 절대경로·이메일·IP·토큰을 일괄 마스킹한다.
+# token_map 치환을 먼저 돌려 알려진 프로젝트 루트는 proj-N 신호로 보존한 뒤 나머지 경로만 붕괴시킨다.
+_PATHISH = re.compile(r"[/\\][^\s]+")
+_EMAIL = re.compile(r"[\w.+-]+@[\w-]+\.[\w.-]+")
+_IPV4 = re.compile(r"\b\d{1,3}(?:\.\d{1,3}){3}\b")
+# sk-... / 20자 이상 연속 hex·base64 런 → 토큰/시크릿 추정.
+_SECRET = re.compile(r"\b(?:sk-[A-Za-z0-9_-]{8,}|[A-Za-z0-9+/=_-]{20,})\b")
+# 알려진 자격증명 패턴 — 20자 미만이거나 :@ 인접으로 위 일반 규칙의 \b 런이
+# 끊겨 놓치는 짧은 비밀을 명시적으로 잡는다.
+_KNOWN_SECRETS = re.compile(
+    r"(?:AKIA|ASIA)[0-9A-Z]{16}"            # AWS access key id
+    r"|gh[pousr]_[A-Za-z0-9_]{8,}"          # GitHub token (PAT/OAuth/server/refresh)
+    r"|github_pat_[A-Za-z0-9_]{8,}"
+    r"|xox[abprs]-[A-Za-z0-9-]{8,}"         # Slack token
+)
+# URL basic-auth(scheme://user:pass@host) 의 비밀번호. _PATHISH 보다 먼저 돌린다.
+_URL_CRED = re.compile(r"([\w.+-]+://[^\s:/@]+:)[^\s@/]+(@)")
+# 자격증명을 가리키는 키워드(부분일치). 긴 플래그는 철자 열거(denylist) 대신
+# 이 키워드를 품은 모든 플래그를 잡아 --api-key/--access-token/--db-password 등
+# 새 도구의 플래그도 자동 포함한다. 공유 zip 이라 과마스킹이 누출보다 안전.
+_CRED_KEYWORD = (
+    r"user(?:name)?|pass(?:wd|word)?|pwd|token|secret"
+    r"|api[-_]?key|key|auth|cred(?:ential)?|access[-_]?key"
+)
+# 자격증명 플래그 뒤 값. 긴 플래그는 키워드 부분일치, 짧은 플래그는 -u/-p/-a
+# (mysql/redis). 따옴표로 감싼 값은 공백을 포함할 수 있으므로 닫는 따옴표까지
+# 먹는다 — `--password 'my pass'` 의 공백 뒤 잔여(pass')가 새지 않도록. 비-따옴표
+# 값은 다른 플래그(-) 로 시작하면 마스킹하지 않는다 — `-a -m msg` 같은
+# 비-자격증명 조합(예: git commit -a)을 잘못 먹지 않도록.
+_FLAG_CRED = re.compile(
+    rf"((?:--[\w-]*(?:{_CRED_KEYWORD})[\w-]*|(?<![\w-])-[upa])[ =])"
+    r"(?:'[^']*'|\"[^\"]*\"|(?!-)\S+)",
+    re.IGNORECASE,
+)
+# 단문자 플래그 붙여쓰기형(-uroot -ppassw0rd 같은 MySQL/psql 스타일) — 위 규칙은
+# 구분자를 요구해 놓치므로, 토큰 경계의 -u/-p 에 붙은 값도 잡는다.
+_FLAG_CRED_ATTACHED = re.compile(r"(?<![\w-])(-[up])\S+")
+# HTTP Authorization 스킴 토큰(Authorization: Bearer <jwt> / Basic <base64>).
+_AUTH_SCHEME = re.compile(r"\b(Bearer|Basic) +\S+", re.IGNORECASE)
+
+# 자유 텍스트(메시지·stderr·command)는 경로 붕괴까지, 구조 필드(taskKey 등)는 token_map 만.
+_FREETEXT_FIELDS = ("message", "stderrExcerpt", "command")
+
+
+def _scrub(value: object, token_map: dict) -> object:
+    if not isinstance(value, str):
+        return value
+    out = value
+    # 긴 루트부터 치환 — 한 루트가 다른 루트의 prefix 일 때(예: /w/app vs
+    # /w/app-v2) 짧은 쪽이 먼저 박혀 긴 쪽이 부분치환되는 오귀속을 막는다.
+    for root, token in sorted(token_map.items(), key=lambda kv: -len(kv[0])):
+        if root:
+            out = out.replace(root, token)
+    out = _HOME_USER.sub("/Users/<user>", out)
+    out = _LINUX_USER.sub("/home/<user>", out)
+    return out
+
+
+def _scrub_freetext(value: object, token_map: dict) -> object:
+    if not isinstance(value, str):
+        return value
+    out = _scrub(value, token_map)
+    out = _EMAIL.sub("<email>", out)
+    out = _IPV4.sub("<ip>", out)
+    out = _KNOWN_SECRETS.sub("<token>", out)
+    out = _URL_CRED.sub(r"\1<secret>\2", out)
+    out = _AUTH_SCHEME.sub(r"\1 <secret>", out)
+    out = _FLAG_CRED.sub(r"\1<secret>", out)
+    out = _FLAG_CRED_ATTACHED.sub(r"\1<secret>", out)
+    out = _SECRET.sub("<token>", out)
+    # 경로 붕괴는 마지막에: 위 마스킹 토큰(<email> 등)은 경로 모양이 아니므로 안전.
+    out = _PATHISH.sub("<path>", out)
+    return out
+
+
+def anonymize(records: list[dict]) -> tuple[list[dict], dict]:
+    token_map = _token_map(records)
+    clean: list[dict] = []
+    for rec in records:
+        root = str(rec.get("_projectRoot", ""))
+        token = token_map.get(root, "proj-?")
+        item = {}
+        for k in KEEP_FIELDS:
+            if k not in rec:
+                continue
+            scrub = _scrub_freetext if k in _FREETEXT_FIELDS else _scrub
+            item[k] = scrub(rec.get(k), token_map)
+        task_key = str(rec.get("taskKey", ""))
+        if ":" in task_key:
+            item["taskKey"] = token + task_key[task_key.index(":"):]
+        item["sourceProject"] = token
+        clean.append(item)
+    return clean, token_map
+
+
+_NUM = re.compile(r"\d+")
+
+
+def cluster_key(rec: dict) -> str:
+    msg = str(rec.get("message", ""))
+    msg = _PATHISH.sub("<path>", msg)
+    msg = _NUM.sub("<n>", msg)
+    msg = msg.strip()[:80]
+    return "|".join([
+        str(rec.get("errorType", "")),
+        str(rec.get("phase", "")),
+        str(rec.get("agent", "")),
+        msg,
+    ])
+
+
+def build_clusters(records: list[dict]) -> tuple[list[dict], list[str]]:
+    """클러스터 목록과, records 와 같은 순서의 레코드별 cluster_key 를 함께 반환.
+    호출자가 직렬화 시 키를 재계산(정규식 중복)하지 않도록 키를 노출한다."""
+    buckets: dict[str, dict] = {}
+    keys: list[str] = []
+    for rec in records:
+        key = cluster_key(rec)
+        keys.append(key)
+        b = buckets.setdefault(key, {
+            "key": key, "errorType": str(rec.get("errorType", "")),
+            "phase": str(rec.get("phase", "")), "agent": str(rec.get("agent", "")),
+            "count": 0, "projects": set(), "sample": str(rec.get("message", "")),
+        })
+        b["count"] += 1
+        b["projects"].add(str(rec.get("sourceProject", "")))
+    clusters = []
+    for b in buckets.values():
+        b["projects"] = sorted(p for p in b["projects"] if p)
+        clusters.append(b)
+    clusters.sort(key=lambda c: (-c["count"], c["key"]))
+    return clusters, keys
+
+
+def cluster_id_map(clusters: list[dict]) -> dict:
+    """cluster_key → report 표의 # (1-based, build_clusters 정렬 순서)."""
+    return {c["key"]: i for i, c in enumerate(clusters, start=1)}
+
+
+def render_report(*, agg, clusters, stats, generated_at) -> str:
+    lines = [
+        "# okstra cross-project 에러 환류 리포트",
+        "",
+        f"- 생성 시각: {generated_at}",
+        f"- 총 에러: {agg['errorCount']} (에러 로그 보유 run {stats['runCount']}개)",
+        f"- 도달 불가 run: {stats['unreachableRuns']}",
+        f"- errorType 분포: {agg['byErrorType']}",
+        "",
+        "## 빈발 클러스터 (brief 분할 단위)",
+        "",
+        "| # | errorType | phase | agent | count | projects | 대표 메시지 |",
+        "|---|---|---|---|---:|---|---|",
+    ]
+    for i, c in enumerate(clusters, start=1):
+        sample = c["sample"].replace("|", "\\|").replace("\n", " ")[:60]
+        lines.append(
+            f"| {i} | {c['errorType']} | {c['phase']} | {c['agent']} "
+            f"| {c['count']} | {len(c['projects'])} | {sample} |"
+        )
+    return "\n".join(lines) + "\n"
+
+
+_CONFIG_NAME = "error-zip.json"
+
+
+def remember_output_path(home: Path, out_path: Path) -> None:
+    cfg = home / _CONFIG_NAME
+    cfg.write_text(
+        json.dumps({"lastOutputPath": str(out_path)}, ensure_ascii=False, indent=2),
+        encoding="utf-8",
+    )
+
+
+def last_output_path(home: Path) -> str:
+    cfg = home / _CONFIG_NAME
+    if not cfg.is_file():
+        return ""
+    try:
+        return str(json.loads(cfg.read_text(encoding="utf-8")).get("lastOutputPath", ""))
+    except Exception:
+        return ""
+
+
+def _write_zip(out_path: Path, report: str, serialized: list[dict]) -> None:
+    out_path.parent.mkdir(parents=True, exist_ok=True)
+    with zipfile.ZipFile(out_path, "w", zipfile.ZIP_DEFLATED) as zf:
+        zf.writestr("report.md", report)
+        payload = "\n".join(json.dumps(r, ensure_ascii=False) for r in serialized)
+        zf.writestr("errors/anonymized.jsonl", payload + ("\n" if payload else ""))
+
+
+def build_zip(home: Path, out_path: Path, now: dt.datetime) -> dict:
+    records, stats = collect_records(home)
+    # 집계는 _sourceLog 가 살아있는 raw 레코드에서 한다 — 익명화 레코드는
+    # _sourceLog 가 KEEP_FIELDS 밖이라 runCount 가 무너진다.
+    agg = aggregate(records)
+    clean, _ = anonymize(records)
+    clusters, keys = build_clusters(clean)
+    report = render_report(
+        agg=agg, clusters=clusters, stats=stats,
+        generated_at=now.isoformat(),
+    )
+    id_map = cluster_id_map(clusters)
+    serialized = [{**r, "clusterId": id_map.get(k)} for r, k in zip(clean, keys)]
+    # 출력 zip 과 공유 error-zip.json 쓰기를 중앙 락으로 직렬화한다 — 동시 error-zip
+    # 두 개가 같은 경로에 쓰면 한쪽이 다른 쪽의 부분 기록 zip 을 절단하고
+    # lastOutputPath 가 last-writer-wins 로 덮인다.
+    with central_lock(home):
+        _write_zip(out_path, report, serialized)
+        remember_output_path(home, out_path)
+    return {
+        "outPath": str(out_path),
+        "errorCount": len(clean),
+        "runCount": stats["runCount"],
+        "unreachableRuns": stats["unreachableRuns"],
+        "clusterCount": len(clusters),
+        "projectCount": len(stats["projectRoots"]),
+    }
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="okstra error-zip",
+        description="cross-project okstra 에러를 수집·익명화해 zip 으로 묶는다.",
+    )
+    parser.add_argument("--out", required=True, help="출력 .zip 절대/상대 경로")
+    args = parser.parse_args(argv)
+    home = okstra_home()
+    result = build_zip(home, Path(args.out), dt.datetime.now(dt.timezone.utc))
+    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/fanout.py

@@ -12,8 +12,11 @@ def topological_order(units: dict[str, list[str]]) -> list[str]:
     units: unit-id -> 그 unit 이 의존하는 unit-id 목록.
     순환이면 CycleError, 알 수 없는 의존이면 ValueError.
     """
+    # 같은 의존을 두 번 적으면(`depends-on: a, a`) indegree 와 감소 횟수가 어긋나
+    # 순환이 없는데도 CycleError 가 난다. unit 별 의존을 dedupe 해 일치시킨다.
+    dep_sets = {u: set(deps) for u, deps in units.items()}
     indeg = {u: 0 for u in units}
-    for u, deps in units.items():
+    for u, deps in dep_sets.items():
         for d in deps:
             if d not in units:
                 raise ValueError(f"unit {u!r} depends on unknown unit {d!r}")
@@ -23,7 +26,7 @@ def topological_order(units: dict[str, list[str]]) -> list[str]:
     while queue:
         u = queue.pop(0)
         order.append(u)
-        for v, deps in units.items():
+        for v, deps in dep_sets.items():
             if u in deps:
                 indeg[v] -= 1
                 if indeg[v] == 0:

package/runtime/python/okstra_ctl/fix_cycles.py

@@ -35,14 +35,26 @@ def fix_cycles_path(task_root: Path) -> Path:
 
 
 def read_rows(task_root: Path) -> List[Dict[str, Any]]:
+    """fix-cycles.jsonl 의 유효 행만 반환.
+
+    append-only SSOT 의 손상 내성 경계: 중단된 writer 가 남긴 깨진 줄과
+    `cycle` 키가 없는(스키마 드리프트) 행은 여기서 걸러, downstream
+    open_cycle/summarize/packet_summary 의 r["cycle"] 접근이 항상 안전하다.
+    """
     p = fix_cycles_path(task_root)
     if not p.exists():
         return []
     out: List[Dict[str, Any]] = []
     for line in p.read_text(encoding="utf-8").splitlines():
         line = line.strip()
-        if line:
-            out.append(json.loads(line))
+        if not line:
+            continue
+        try:
+            row = json.loads(line)
+        except json.JSONDecodeError:
+            continue
+        if isinstance(row, dict) and "cycle" in row:
+            out.append(row)
     return out
 
 

package/runtime/python/okstra_ctl/git_reconcile.py

@@ -72,7 +72,13 @@ def content_merged(project_root: Path, commit: str, candidate: str,
     if not mb:
         return MatchResult("not-merged")
     range_base = _resolve_commit_sha(project_root, base) or mb
-    cand_ids: Dict[str, str] = dict(_patch_ids_of_range(project_root, mb, cand))
+    # git log 는 최신 커밋부터 출력 → patch-id 가 후보에 중복(revert·재적용,
+    # cross-branch cherry-pick)되면 가장 최신(tip 쪽) SHA 를 재기록 대상으로
+    # 골라야 한다. dict() 는 나중 항목이 이기므로 오래된 SHA 가 남는다 → 역순 적재.
+    cand_ids: Dict[str, str] = {
+        pid: sha
+        for pid, sha in reversed(_patch_ids_of_range(project_root, mb, cand))
+    }
     stage_ids = _patch_ids_of_range(project_root, range_base, resolved)
     if stage_ids and all(pid in cand_ids for pid, _ in stage_ids):
         # git log 는 최신 커밋부터 출력 → stage_ids[0] 이 tip. matched_commit

package/runtime/python/okstra_ctl/handoff.py

@@ -13,7 +13,10 @@ from pathlib import Path
 from typing import Any, Callable, Dict, List, Optional, Tuple
 
 from . import consumers, worktree_registry
-from .worktree import compute_branch_name, compute_worktree_path
+from .worktree import (compute_branch_name, compute_worktree_path,
+                       main_worktree_path, is_dirty_excluding_okstra,
+                       nested_worktree_excludes, is_ancestor, merge_branch,
+                       remove_worktree_force, MergeError, _git)
 
 
 class HandoffError(Exception):
@@ -23,11 +26,13 @@ class HandoffError(Exception):
 class HandoffConflict(Exception):
     """stage 간 merge 충돌 — exit 2, 충돌 경로 동봉."""
 
-    def __init__(self, stage: int, paths: List[str]):
+    def __init__(self, stage: int, branch: str, paths: List[str]):
         self.stage = stage
+        self.branch = branch
         self.paths = paths
         super().__init__(
-            f"merge conflict while merging stage {stage}: {', '.join(paths)}")
+            f"merge conflict while merging stage {stage} ({branch}): "
+            f"{', '.join(paths)}")
 
 
 def group_id_for(stages: List[int]) -> str:
@@ -113,8 +118,8 @@ def check_dependency_closure(
 
 
 def _run_git(args: List[str], cwd, check: bool = True) -> subprocess.CompletedProcess:
-    r = subprocess.run(["git", *args], cwd=str(cwd),
-                       capture_output=True, text=True)
+    """worktree._git(공용 러너) 위에 check=True 시 HandoffError 변환만 얹는다."""
+    r = _git(Path(cwd), *args)
     if check and r.returncode != 0:
         raise HandoffError(f"git {' '.join(args)} failed: {r.stderr.strip()}")
     return r
@@ -133,9 +138,7 @@ def _require_eligible(stage_map, rows, stages) -> Dict[int, Dict[str, Any]]:
 
 def _require_closure(stages, stage_map, done, project_root, base_branch) -> None:
     def merged(commit: str) -> bool:
-        return _run_git(["merge-base", "--is-ancestor", commit,
-                         f"origin/{base_branch}"], project_root,
-                        check=False).returncode == 0
+        return is_ancestor(project_root, commit, f"origin/{base_branch}")
     violations = check_dependency_closure(stages, stage_map, done, merged)
     if violations:
         lines = [
@@ -151,8 +154,7 @@ def _reuse_existing(entry, stages, done, project_root) -> Dict[str, Any]:
     head = _run_git(["rev-parse", entry.branch], project_root).stdout.strip()
     for n in stages:
         h = (done.get(n) or {}).get("head_commit", "")
-        if _run_git(["merge-base", "--is-ancestor", h, head], project_root,
-                    check=False).returncode != 0:
+        if not is_ancestor(project_root, h, head):
             raise HandoffError(
                 f"collector branch {entry.branch} exists but stage {n} head "
                 f"{h} is not merged into it — remove the branch/worktree and "
@@ -164,27 +166,37 @@ def _reuse_existing(entry, stages, done, project_root) -> Dict[str, Any]:
 
 def _cleanup_group(project_root, wt_path, branch, project_id, task_group,
                    task_id, gid) -> None:
-    _run_git(["worktree", "remove", "--force", str(wt_path)], project_root,
-             check=False)
+    remove_worktree_force(project_root, wt_path)
     _run_git(["branch", "-D", branch], project_root, check=False)
     worktree_registry.release(project_id, task_group, task_id, group_id=gid)
 
 
 def _merge_stages(wt_path, stages, work_category, task_id, project_root,
-                  project_id, task_group, gid, branch) -> List[str]:
+                  project_id, task_group, gid, branch, done) -> List[str]:
+    """선택 stage 들을 수집 브랜치에 위상순 --no-ff 머지한다.
+
+    머지 대상은 `-sN` 브랜치 tip 이 아니라 기록된 done.head_commit 이다 —
+    consumers 의 done.head_commit 은 git-reconcile 로 브랜치 tip 과 다른 commit
+    일 수 있어, 브랜치 tip 을 머지하면 done 시점 이후의 갈라진 변경을 끌어들인다.
+    stage_branch 는 충돌 식별용으로만 산출한다(머지 대상 아님)."""
     merge_commits = []
     for n in sorted(stages):
         stage_branch = compute_branch_name(
             work_category=work_category, task_id_segment=task_id,
             stage_number=n)
-        r = _run_git(["merge", "--no-edit", stage_branch], wt_path, check=False)
-        if r.returncode != 0:
-            paths = _run_git(["diff", "--name-only", "--diff-filter=U"],
-                             wt_path).stdout.split()
-            _run_git(["merge", "--abort"], wt_path, check=False)
+        done_commit = (done.get(n) or {}).get("head_commit", "")
+        try:
+            conflicts = merge_branch(wt_path, done_commit, no_ff=False)
+        except MergeError as exc:
+            # cleanup 은 assemble 의 except Exception 이 수행한다(worktree-add
+            # 실패 경로와 동일 처리) — 여기서 직접 정리하지 않는다.
+            raise HandoffError(
+                f"stage {n} ({stage_branch}) 머지 실패(내용 충돌 아님): {exc}"
+            ) from exc
+        if conflicts is not None:
             _cleanup_group(project_root, wt_path, branch, project_id,
                            task_group, task_id, gid)
-            raise HandoffConflict(stage=n, paths=paths)
+            raise HandoffConflict(stage=n, branch=stage_branch, paths=conflicts)
         merge_commits.append(
             _run_git(["rev-parse", "HEAD"], wt_path).stdout.strip())
     return merge_commits
@@ -218,16 +230,23 @@ def assemble(*, project_root, plan_run_root, stage_map, stages, base_branch,
     wt_path = compute_worktree_path(
         project_id=project_id, task_group_segment=task_group,
         task_id_segment=task_id, group_id=gid)
-    worktree_registry.reserve(
-        project_id=project_id, task_group=task_group, task_id=task_id,
-        worktree_path=str(wt_path), branch=branch, base_ref=base_commit,
-        phase="release-handoff", group_id=gid, stages=stages)
+    # reserve 충돌(이미 등록된 task-key/branch)은 RuntimeError 로 오는데, 이를
+    # HandoffError 로 감싸 main 의 envelope(JSON+exit1)로 흘려보낸다. 감싸지
+    # 않으면 raw traceback 으로 빠진다. cleanup 을 거는 worktree-add try 와
+    # 분리해 두어, 예약 생성 실패 시 자신이 만들지도 않은 예약을 되돌리지 않는다.
+    try:
+        worktree_registry.reserve(
+            project_id=project_id, task_group=task_group, task_id=task_id,
+            worktree_path=str(wt_path), branch=branch, base_ref=base_commit,
+            phase="release-handoff", group_id=gid, stages=stages)
+    except RuntimeError as exc:
+        raise HandoffError(str(exc))
     try:
         _run_git(["worktree", "add", "-b", branch, str(wt_path), base_commit],
                  project_root)
         merge_commits = _merge_stages(wt_path, stages, work_category, task_id,
                                       project_root, project_id, task_group, gid,
-                                      branch)
+                                      branch, done)
     except HandoffConflict:
         raise  # _merge_stages 가 이미 _cleanup_group 으로 예약·worktree 를 되돌림
     except Exception:
@@ -241,6 +260,59 @@ def assemble(*, project_root, plan_run_root, stage_map, stages, base_branch,
             "merge_commits": merge_commits}
 
 
+def _remove_task_worktree(main_wt, target: str) -> Optional[str]:
+    """clean 으로 확인된 task-key 워크트리를 제거. 이미 없으면 no-op.
+    실패하면 사람이 읽을 detail 문자열, 성공/부재면 None.
+    nested stage 워크트리가 남아있으면 제거하지 않는다 — --force 로 지우면 물리
+    디렉터리만 사라지고 git/registry 의 stage-key admin 엔트리가 고아로 남는다.
+    통합/teardown 이 끝나 nested 가 없을 때만 제거한다."""
+    if not Path(target).exists():
+        return None  # 이미 teardown 됨 — checkout 으로 진행
+    nested = nested_worktree_excludes(target)
+    if nested:
+        return f"nested 워크트리가 남아있습니다: {', '.join(nested)}"
+    rm = remove_worktree_force(main_wt, target)
+    if rm.returncode != 0:
+        return rm.stderr.strip()
+    return None
+
+
+def local_checkout(*, project_root, project_id, task_group, task_id) -> Dict[str, Any]:
+    """whole-task: okstra task-key 워크트리를 제거하고 task 브랜치를 메인
+    워크트리에 checkout 한다(브랜치 보존). 메인·대상 워크트리가 dirty 면 거부.
+    base 브랜치는 건드리지 않는다."""
+    entry = worktree_registry.lookup(project_id, task_group, task_id)
+    if not entry or not entry.branch or not entry.worktree_path:
+        raise HandoffError(
+            "task-key worktree registry 엔트리가 없습니다 — local checkout 대상 없음")
+    main_wt = main_worktree_path(Path(project_root))
+    if is_dirty_excluding_okstra(main_wt):
+        raise HandoffError(
+            f"메인 워크트리에 미커밋 변경이 있습니다 ({main_wt}) — "
+            "커밋/스태시 후 다시 시도하세요")
+    # 제거 게이트는 파괴 대상인 task-key 워크트리를 검사해야 한다 (메인 아님).
+    if (Path(entry.worktree_path).exists()
+            and is_dirty_excluding_okstra(entry.worktree_path)):
+        raise HandoffError(
+            f"task 워크트리에 미커밋 변경이 있습니다 ({entry.worktree_path}) — "
+            "해당 워크트리에서 커밋/스태시 후 다시 시도하세요")
+    detail = _remove_task_worktree(main_wt, entry.worktree_path)
+    if detail is not None:
+        raise HandoffError(
+            f"task 워크트리 제거 실패 ({entry.worktree_path}): {detail} — "
+            "nested stage 워크트리가 남아있거나 통합이 미완료일 수 있습니다. "
+            "먼저 stage 통합/teardown 하거나 수동으로 "
+            f"`git worktree remove {entry.worktree_path}` 후 다시 시도하세요")
+    worktree_registry.release_status(project_id, task_group, task_id)
+    co = _git(Path(main_wt), "checkout", entry.branch)
+    if co.returncode != 0:
+        raise HandoffError(
+            f"git checkout {entry.branch} 실패: {co.stderr.strip()} — 워크트리는 "
+            f"제거됨; 메인({main_wt})에서 수동 checkout 으로 복구하세요")
+    return {"ok": True, "branch": entry.branch, "mainWorktreePath": str(main_wt),
+            "removedWorktree": entry.worktree_path, "status": "checked-out"}
+
+
 def _impl_task_key_for(rows: List[Dict[str, Any]], stage: int) -> str:
     done = consumers.latest_done_by_stage(rows)
     row = done.get(stage)
@@ -251,6 +323,20 @@ def _impl_task_key_for(rows: List[Dict[str, Any]], stage: int) -> str:
     return row.get("impl_task_key", "")
 
 
+def _impl_task_key_for_any(rows: List[Dict[str, Any]], stages: List[int]) -> str:
+    """task 를 식별하는 키 — stages 중 done 행이 있는 아무 stage 에서나 승계한다.
+    PR 기록은 특정 stage 의 done 에 묶일 이유가 없으므로 최저 stage 가 비어도
+    다른 stage 의 done 으로 충족한다."""
+    done = consumers.latest_done_by_stage(rows)
+    for n in sorted(stages):
+        row = done.get(n)
+        if row:
+            return row.get("impl_task_key", "")
+    raise HandoffError(
+        f"none of stages {sorted(stages)} have a done row in consumers.jsonl — "
+        "finish at least one implementation stage first")
+
+
 def record_verified(*, plan_run_root, stage: int, report_path: str,
                     data_json) -> Dict[str, Any]:
     """단독-stage accepted 만 기록. data.json 의 taskType/scope/verdict 를 검증해
@@ -283,7 +369,7 @@ def record_pr(*, plan_run_root, stages: List[int], branch: str,
     if not stages:
         raise HandoffError("record-pr requires at least one stage")
     rows = consumers.read_consumers(Path(plan_run_root))
-    key = _impl_task_key_for(rows, sorted(stages)[0])
+    key = _impl_task_key_for_any(rows, stages)
     consumers.append_pr(Path(plan_run_root), impl_task_key=key,
                         stages=stages, branch=branch, url=url)
     return {"ok": True, "stages": sorted(stages), "branch": branch, "url": url}
@@ -338,6 +424,13 @@ def main(argv: Optional[list] = None) -> int:
     sp.add_argument("--branch", required=True)
     sp.add_argument("--url", required=True)
 
+    sp = sub.add_parser("local-checkout")
+    common(sp, plan=False)
+    sp.add_argument("--project-root", default=".")
+    sp.add_argument("--project-id", required=True)
+    sp.add_argument("--task-group", required=True)
+    sp.add_argument("--task-id", required=True)
+
     a = p.parse_args(argv)
     try:
         if a.cmd == "eligible":
@@ -356,13 +449,19 @@ def main(argv: Optional[list] = None) -> int:
             out = record_verified(plan_run_root=Path(a.plan_run_root),
                                   stage=a.stage, report_path=a.report_path,
                                   data_json=a.data_json)
+        elif a.cmd == "local-checkout":
+            out = local_checkout(
+                project_root=Path(a.project_root).resolve(),
+                project_id=a.project_id, task_group=a.task_group,
+                task_id=a.task_id)
         else:
             out = record_pr(plan_run_root=Path(a.plan_run_root),
                             stages=_parse_stages_csv(a.stages),
                             branch=a.branch, url=a.url)
     except HandoffConflict as exc:
         print(json.dumps({"error": str(exc), "stage": exc.stage,
-                          "conflicts": exc.paths}, ensure_ascii=False))
+                          "branch": exc.branch, "conflicts": exc.paths},
+                         ensure_ascii=False))
         return 2
     except HandoffError as exc:
         print(json.dumps({"error": str(exc)}, ensure_ascii=False))

package/runtime/python/okstra_ctl/implementation_stage.py

@@ -109,7 +109,14 @@ def select_and_provision_implementation_stage(
             concurrent_stages=concurrent_stages,
         )
 
-    head_sha = _git_out(inp.project_root, "rev-parse", "HEAD")
+    # The anchor and multi-dep candidate base must come from the task-key
+    # worktree HEAD (where stage work accumulates), not from inp.project_root
+    # (the user's invocation cwd, which may sit on an older/unrelated commit).
+    # The task-key worktree is the SSOT in the registry; whole-task
+    # final-verification (run.py) resolves its base from the same path.
+    task_entry = _reg.lookup(inp.project_id, inp.task_group, inp.task_id)
+    task_worktree_path = (task_entry.worktree_path if task_entry else "") or inp.project_root
+    head_sha = _git_out(task_worktree_path, "rev-parse", "HEAD")
     if head_sha:
         _reg.set_implementation_base(
             inp.project_id,
@@ -133,7 +140,7 @@ def select_and_provision_implementation_stage(
             consumer_done_rows,
             anchor_base_commit=anchor,
             candidate_base=head_sha,
-            project_root=Path(inp.project_root),
+            project_root=Path(task_worktree_path),
             plan_run_root=plan_run_root,
         )
     except stage_targets.StageTargetError as exc: