okstra 0.201.3 → 0.204.0

package/runtime/python/okstra_ctl/stage_integrate.py

@@ -1,10 +1,15 @@
-"""whole-task stage 통합(머지) + worktree teardown 코어.
+"""stage done commit 을 한 곳에 모으는 두 가지 방법.
 
-Phase A: stage done commit 을 task 브랜치에 위상순 --no-ff 머지(이미 머지면
-skip, 충돌이면 해당 머지만 abort 후 IntegrateError). Phase B: 머지/skip 된
-stage 의 worktree 디렉터리와 registry 키를 정리(dirty 면 skip). stage 브랜치는
-스택 보존을 위해 삭제하지 않는다.
+`integrate_stages` — whole-task 통합. Phase A: stage done commit 을 task 브랜치에
+위상순 --no-ff 머지(이미 머지면 skip, 충돌이면 해당 머지만 abort 후 IntegrateError).
+Phase B: 머지/skip 된 stage 의 worktree 디렉터리와 registry 키를 정리(dirty 면 skip).
+stage 브랜치는 스택 보존을 위해 삭제하지 않는다.
 설계: docs/superpowers/specs/2026-06-20-stage-auto-integrate-teardown-design.md
+
+`ensure_stage_merge_branch` — 여러 stage 의 done commit 만 담은 브랜치를 만든다.
+선행이 둘 이상인 stage 의 바닥(구현 워크트리의 base, PR 의 base)이 필요할 때 쓰며,
+task 브랜치를 건드리지 않는다.
+설계: .project-docs/specs/2026-09-24-release-handoff-per-stage-pr-design.md §4
 """
 from __future__ import annotations
 
@@ -28,6 +33,141 @@ class IntegrateResult:
     warnings: list[str] = field(default_factory=list)
 
 
+@dataclass(frozen=True)
+class StageMergeBranch:
+    branch: str
+    commit: str
+    created: bool
+    stages: list[int]
+    merge_commits: list[str]
+
+
+class MergeBranchConflict(IntegrateError):
+    """선행 stage 들끼리 내용이 충돌해 공통 바닥을 만들 수 없다."""
+
+    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} ({branch}): "
+            f"{', '.join(paths)}")
+
+
+def ensure_stage_merge_branch(
+    *, project_root, project_id: str, task_group: str, task_id: str,
+    work_category: str, heads: dict[int, str], anchor_base: str,
+    advance_existing: bool = False,
+) -> StageMergeBranch:
+    """`heads` 의 done commit 을 모두 담은 브랜치를 보장한다. 멱등.
+
+    이름은 stage 집합이 정한다(`<namespace>/<task>-g<n1>-<n2>`) — 같은 집합은
+    언제나 같은 브랜치다. 브랜치는 anchor 에서 떼어 각 done commit 을 `--no-ff`
+    로 머지해 만든다. 머지 대상이 브랜치 tip 이 아니라 기록된 done commit 인 이유는
+    `_merge_stage` 와 같다: reconcile 로 둘이 갈라져 있을 수 있다.
+
+    워크트리는 머지하는 동안만 존재하고 끝나면 지운다 — 이 브랜치는 누가 체크아웃해
+    작업하는 곳이 아니라 다른 브랜치가 올라앉는 바닥이다.
+
+    이미 있는 브랜치에 빠진 commit 이 있을 때 `advance_existing` 이 갈린다.
+    거짓(기본)이면 거부한다 — 열려 있는 PR 의 base 를 말없이 옮기지 않기 위해서다.
+    참이면 빠진 commit 만 추가로 머지한다 — 구현 워크트리의 base 는 언제나 현재
+    선행 위에 있어야 하기 때문이다.
+
+    **호출자가 task-key `worktree_provision_mutex` 를 쥐고 들어와야 한다.** flock 은
+    재진입이 안 되므로 여기서 다시 잡으면 이미 락을 쥔 implementation 경로가
+    교착한다 — `_resolve_and_integrate_whole_task_unlocked` 와 같은 분리다.
+    """
+    from .worktree import (compute_branch_name, compute_worktree_path,
+                           is_ancestor, remove_worktree_force, stage_group_id)
+
+    if not heads:
+        raise IntegrateError("ensure_stage_merge_branch requires at least one stage")
+    stages = sorted(heads)
+    branch = compute_branch_name(work_category=work_category,
+                                 task_id_segment=task_id,
+                                 group_id=stage_group_id(stages))
+    root = Path(project_root)
+    if _branch_exists(root, branch):
+        tip = _rev_parse(root, branch)
+        missing = [n for n in stages if not is_ancestor(root, heads[n], tip)]
+        if not missing:
+            return StageMergeBranch(branch=branch, commit=tip, created=False,
+                                    stages=stages, merge_commits=[])
+        if not advance_existing:
+            raise IntegrateError(
+                f"merge-base branch {branch} exists but stage(s) {missing} "
+                "are not merged into it — delete the branch and retry so "
+                "okstra can rebuild it")
+        # 기존 브랜치를 그대로 체크아웃해 빠진 commit 만 얹는다.
+        creating, start = False, branch
+        to_merge = {n: heads[n] for n in missing}
+    else:
+        if not anchor_base:
+            raise IntegrateError(
+                f"cannot create {branch}: the implementation base commit is not "
+                "recorded in the worktree registry — run at least one "
+                "implementation stage first")
+        creating, start = True, anchor_base
+        to_merge = dict(heads)
+
+    wt_path = compute_worktree_path(
+        project_id=project_id, task_group_segment=task_group,
+        task_id_segment=task_id, group_id=stage_group_id(stages))
+    wt_path.parent.mkdir(parents=True, exist_ok=True)
+    add = _git(root, "worktree", "add",
+               *(["-b", branch] if creating else []), str(wt_path), start)
+    if add.returncode != 0:
+        raise IntegrateError(
+            f"git worktree add for {branch} failed: "
+            f"{(add.stderr or add.stdout).strip()}")
+    try:
+        merge_commits = _merge_heads_into(wt_path, to_merge, work_category,
+                                          task_id)
+        commit = _rev_parse(wt_path, "HEAD")
+    except Exception:
+        remove_worktree_force(root, wt_path)
+        if creating:
+            _git(root, "branch", "-D", branch)
+        raise
+    remove_worktree_force(root, wt_path)
+    return StageMergeBranch(branch=branch, commit=commit, created=creating,
+                            stages=stages, merge_commits=merge_commits)
+
+
+def _merge_heads_into(wt_path, heads: dict[int, str], work_category: str,
+                      task_id: str) -> list[str]:
+    """stage 번호 순서로 done commit 을 `--no-ff` 머지한다. 이미 담긴 commit 은
+    git 이 `Already up to date` 로 지나가므로 빈 머지 커밋이 생기지 않는다."""
+    from .worktree import MergeError, compute_branch_name, merge_branch
+
+    merge_commits: list[str] = []
+    for n in sorted(heads):
+        stage_branch = compute_branch_name(work_category=work_category,
+                                           task_id_segment=task_id,
+                                           stage_number=n)
+        try:
+            conflicts = merge_branch(wt_path, heads[n], no_ff=True)
+        except MergeError as exc:
+            raise IntegrateError(
+                f"stage {n} ({stage_branch}) 머지 실패(내용 충돌 아님): {exc}"
+            ) from exc
+        if conflicts is not None:
+            raise MergeBranchConflict(stage=n, branch=stage_branch,
+                                      paths=conflicts)
+        merge_commits.append(_rev_parse(wt_path, "HEAD"))
+    return merge_commits
+
+
+def _branch_exists(project_root, branch: str) -> bool:
+    return _git(project_root, "rev-parse", "--verify", "--quiet",
+                f"refs/heads/{branch}").returncode == 0
+
+
+def _rev_parse(cwd, ref: str) -> str:
+    return _git(cwd, "rev-parse", ref).stdout.strip()
+
+
 def _merge_stage(task_wt: str, stage_n: int, branch: str, done_commit: str) -> str:
     """한 stage 의 done commit 을 task 브랜치에 머지. 'merged'|'already_merged'.
     충돌 시 abort 후 IntegrateError.
@@ -62,12 +202,20 @@ def integrate_stages(
     task_worktree_path: str, stage_map: list[dict[str, Any]],
     done_rows: list[dict[str, Any]],
     teardown: bool = True,
+    merge: bool = True,
+    verified_head: str = "",
 ) -> IntegrateResult:
     """whole-task 통합: Phase A 머지 → Phase B teardown.
 
     teardown=False 면 Phase B(stage worktree 디렉터리·registry 키 정리)를 건너뛴다 —
-    container 는 머지만 하고 stage 트리를 보존한다(스펙 §10). final-verification
-    호출은 기본값(True)으로 기존 행위를 유지한다."""
+    container 는 머지만 하고 stage 트리를 보존한다(스펙 §10).
+    merge=False 면 Phase A 를 건너뛴다 — 한 stage 브랜치가 이미 전체를 담고 있어
+    검증이 거기서 돌았다면 task 브랜치로의 머지는 아무도 읽지 않는 산출물이고,
+    정리 시점에 충돌만 만들 수 있다(`stage_targets.containing_stage`). 정리 대상은
+    그때도 완료된 stage 전부다 — stage 브랜치는 어느 경우에도 남는다.
+    verified_head 는 "검증이 실제로 본 커밋"이다. 비면 task worktree HEAD 를 쓴다
+    (Phase A 가 만든 통합 commit). merge=False 로 들어올 때는 검증이 돈 stage
+    브랜치의 head 를 넘겨야 브랜치 tip 경고가 옳은 기준으로 판정된다."""
     from .consumers import latest_done_by_stage
 
     res = IntegrateResult()
@@ -75,6 +223,12 @@ def integrate_stages(
         return res  # non-git / degraded — no-op
     done = latest_done_by_stage(done_rows)
     ordered = sorted((s["stage_number"] for s in stage_map))
+    if not merge:
+        res.already_merged.extend(n for n in ordered if done.get(n))
+        if teardown:
+            _teardown_all(project_id, task_group, task_id,
+                          task_worktree_path, res, verified_head)
+        return res
 
     for n in ordered:
         row = done.get(n)
@@ -98,7 +252,8 @@ def integrate_stages(
         (res.merged if outcome == "merged" else res.already_merged).append(n)
 
     if teardown:
-        _teardown_all(project_id, task_group, task_id, task_worktree_path, res)
+        _teardown_all(project_id, task_group, task_id, task_worktree_path, res,
+                      verified_head)
     return res
 
 
@@ -111,13 +266,13 @@ def _stage_branch_name(project_id, task_group, task_id, stage_n) -> str | None:
 
 
 def _teardown_all(project_id, task_group, task_id, task_wt: str,
-                  res: IntegrateResult) -> None:
+                  res: IntegrateResult, verified_head: str = "") -> None:
     from . import worktree_registry
 
     for n in [*res.merged, *res.already_merged]:
         row = worktree_registry.get_stage_row(project_id, task_group, task_id, n)
         outcome, detail = _teardown_stage(project_id, task_group, task_id,
-                                          task_wt, n, row)
+                                          task_wt, n, row, verified_head)
         if outcome == "torn_down":
             res.torn_down.append(n)
         elif outcome == "skipped":
@@ -138,9 +293,12 @@ def _remove_clean_worktree(task_wt: str, wt: str, stage_n: int) -> tuple[str, st
     return None
 
 
-def _unmerged_branch_tip_warning(task_wt: str, stage_n: int, branch: str) -> str:
-    """Warn text when the stage branch tip is not an ancestor of the task
-    worktree HEAD, or "" when it is (or cannot be resolved).
+def _unmerged_branch_tip_warning(task_wt: str, stage_n: int, branch: str,
+                                 verified_head: str = "") -> str:
+    """Warn text when the stage branch tip is not an ancestor of the commit
+    verification actually inspected, or "" when it is (or cannot be resolved).
+    `verified_head` defaults to the task worktree HEAD — the integration commit
+    Phase A builds. A tip-branch verification passes its own head instead.
 
     Phase A merges `done.head_commit`, never the branch ref, so a stage branch
     can carry commits that whole-task verification never saw. `local-checkout
@@ -152,14 +310,15 @@ def _unmerged_branch_tip_warning(task_wt: str, stage_n: int, branch: str) -> str
     if tip.returncode != 0:
         return ""
     sha = tip.stdout.strip()
-    head = _git(task_wt, "rev-parse", "HEAD").stdout.strip()
+    head = verified_head or _git(task_wt, "rev-parse", "HEAD").stdout.strip()
     if is_ancestor(task_wt, sha, head):
         return ""
-    return (f"stage {stage_n} 브랜치 {branch} 의 tip {sha[:12]} 이 검증된 task "
-            f"HEAD 에 포함되지 않습니다 — 검증에 포함되지 않은 커밋이 있습니다")
+    return (f"stage {stage_n} 브랜치 {branch} 의 tip {sha[:12]} 이 검증된 "
+            f"{head[:12]} 에 포함되지 않습니다 — 검증에 포함되지 않은 커밋이 있습니다")
 
 
-def _teardown_stage(project_id, task_group, task_id, task_wt, stage_n, row):
+def _teardown_stage(project_id, task_group, task_id, task_wt, stage_n, row,
+                    verified_head: str = ""):
     """Remove the clean stage worktree directory and mark the registry row
     released. The stage branch is deliberately kept: the per-stage stack
     branches must survive whole-task verification so that
@@ -181,7 +340,8 @@ def _teardown_stage(project_id, task_group, task_id, task_wt, stage_n, row):
             return outcome
     worktree_registry.release_status(project_id, task_group, task_id, stage_number=stage_n)
     if branch:
-        warning = _unmerged_branch_tip_warning(task_wt, stage_n, branch)
+        warning = _unmerged_branch_tip_warning(task_wt, stage_n, branch,
+                                               verified_head)
         if warning:
             return ("warn", warning)
     return ("torn_down", "")

package/runtime/python/okstra_ctl/stage_map.py

@@ -223,6 +223,21 @@ def _parse_stage_map_row(
     )
 
 
+def stage_number_gap_message(stage_number: int, row_number: int) -> str:
+    """행 위치와 stage 번호가 어긋났을 때의 사유. 두 검증기가 같은 문장을 쓴다.
+
+    "1..N monotonic" 만 적던 동안 이어지는 계획의 작성자는 이 거절을 "검증기가
+    첫 계획만 상정한다" 로 읽었고, 우회한 계획은 `okstra prepare` 에서 다시
+    막혔다(2026-09-24, dev-10860). 무엇을 고쳐야 하는지 문장이 말한다.
+    """
+    return (
+        f"stage numbers must be 1..N with no gap, got {stage_number} at row "
+        f"{row_number}: a plan that continues an earlier one re-declares every "
+        "earlier stage — copy each `done` stage row unchanged — instead of "
+        "starting above them"
+    )
+
+
 def _validate_stage_numbers(
     stages: list[StageMapStage], source_plan_path: str,
 ) -> None:
@@ -238,8 +253,7 @@ def _validate_stage_numbers(
         if stage.stage_number != row_number:
             raise StageMapError(
                 "stage_map",
-                "stage numbers must be 1..N monotonic, "
-                f"got {stage.stage_number} at row {row_number}",
+                stage_number_gap_message(stage.stage_number, row_number),
                 source_plan_path,
             )
 

package/runtime/python/okstra_ctl/stage_targets.py

@@ -427,39 +427,114 @@ def commit_is_ancestor(project_root: Path, ancestor: str, descendant: str) -> bo
     return is_ancestor(project_root, ancestor, descendant)
 
 
-def check_multi_dep_merged(
+def reconcile_pred_commits(
     project_root: Path,
     plan_run_root: Path | None,
     latest: dict[int, dict[str, Any]],
     pred_commits: dict[int, str],
     candidate_base: str,
-    stage_n: int,
-) -> None:
-    """Ensure all predecessor commits are merged into the candidate base."""
+) -> dict[int, str]:
+    """선행의 기록 commit 을 실제로 머지할 commit 으로 옮긴다.
+
+    기록된 done commit 이 task 브랜치에서 rebase·squash 로 다시 쓰였다면, 그
+    commit 을 그대로 머지하는 것은 이미 다른 모양으로 들어간 내용을 한 번 더
+    얹는 일이다. patch-id 로 동치 commit 을 찾으면 그쪽으로 옮기고 원장에도
+    보정 row 를 남긴다(`git-reconcile` 과 같은 기준).
+
+    찾지 못하는 것은 오류가 아니다 — 아직 어디에도 머지되지 않은 선행이 오히려
+    기본이고, 그런 선행은 기록된 commit 그대로 공통 바닥에 들어간다. 종전에는
+    이 자리가 게이트였고, task 브랜치에 선행을 손으로 머지하기 전에는 다중 의존
+    stage 가 시작할 수 없었다."""
     from .git_reconcile import content_merged, _record_reconciled
 
+    if not candidate_base:
+        return dict(pred_commits)
+    resolved: dict[int, str] = {}
     for dep_stage, head in pred_commits.items():
+        resolved[dep_stage] = head
         if commit_is_ancestor(project_root, head, candidate_base):
             continue
         match = content_merged(project_root, head, candidate_base)
-        if match.status in ("ancestor", "patch-equivalent"):
-            if plan_run_root is not None:
-                _record_reconciled(
-                    plan_run_root,
-                    impl_task_key=(latest.get(dep_stage) or {}).get("impl_task_key", ""),
-                    stage=dep_stage,
-                    new_commit=match.matched_commit,
-                    replaced=head,
-                    reason="auto-patch-id",
-                )
+        if match.status != "patch-equivalent" or not match.matched_commit:
             continue
+        resolved[dep_stage] = match.matched_commit
+        if plan_run_root is not None:
+            _record_reconciled(
+                plan_run_root,
+                impl_task_key=(latest.get(dep_stage) or {}).get("impl_task_key", ""),
+                stage=dep_stage,
+                new_commit=match.matched_commit,
+                replaced=head,
+                reason="auto-patch-id",
+            )
+    return resolved
+
+
+@dataclass(frozen=True)
+class StageWorktreeIdentity:
+    """선행 머지 브랜치를 만들 때 필요한 이름 조각. 읽기 전용 호출자는 넘기지
+    않으며, 그때 다중 의존 base 는 만들어야 하는 순간에 거부된다."""
+
+    project_id: str
+    task_group: str
+    task_id: str
+    work_category: str
+
+
+def _multi_dep_base(
+    stage_number: int,
+    deps: list[int],
+    latest: dict[int, dict[str, Any]],
+    anchor_base_commit: str,
+    candidate_base: str,
+    project_root: Path | None,
+    plan_run_root: Path | None,
+    identity: "StageWorktreeIdentity | None",
+) -> str:
+    """선행이 둘 이상인 stage 의 base — 그 선행들만 담은 공통 바닥.
+
+    종전에는 task 워크트리 HEAD 를 base 로 쓰고, 선행이 거기 머지돼 있지 않으면
+    거부했다. 그 base 는 선행이 아닌 stage 의 작업까지 담고 있어서 stage 경계가
+    흐려졌고, 사람이 손으로 머지하기 전에는 stage 가 시작조차 못 했다. 이제
+    선행들의 done commit 만 담은 브랜치를 만들어 그 위에서 시작한다."""
+    from .stage_integrate import IntegrateError, ensure_stage_merge_branch
+
+    pred_commits: dict[int, str] = {}
+    for dep_stage in deps:
+        head = (latest.get(dep_stage) or {}).get("head_commit")
+        if not head:
+            raise StageTargetError(
+                f"predecessor stage {dep_stage} has no done row with head_commit "
+                f"in consumers.jsonl; multi-dependency stage {stage_number} cannot start"
+            )
+        pred_commits[dep_stage] = head
+    if project_root is None:
         raise StageTargetError(
-            f"multi-dependency stage {stage_n}: predecessor stage {dep_stage} "
-            f"({head[:8]}) is not merged into the task worktree "
-            f"({candidate_base[:8]}). Merge stage branches "
-            f"(e.g. the `-s{dep_stage}` branches) into the task worktree "
-            "(or into main, then refresh the worktree) and retry."
+            f"multi-dependency stage {stage_number} needs a git worktree to "
+            "resolve its base; the task-key worktree could not be resolved"
         )
+    heads = reconcile_pred_commits(
+        project_root, plan_run_root, latest, pred_commits, candidate_base)
+    contained = single_containing_head(project_root, heads)
+    if contained is not None:
+        # 한 선행이 나머지를 이미 담고 있으면 그 commit 이 곧 공통 바닥이다.
+        return heads[contained]
+    if identity is None:
+        raise StageTargetError(
+            f"multi-dependency stage {stage_number} has no single predecessor "
+            f"commit containing the others ({sorted(heads)}), so its base is an "
+            "integration branch that only an implementation run may create"
+        )
+    try:
+        merged = ensure_stage_merge_branch(
+            project_root=project_root, project_id=identity.project_id,
+            task_group=identity.task_group, task_id=identity.task_id,
+            work_category=identity.work_category, heads=heads,
+            anchor_base=anchor_base_commit, advance_existing=True)
+    except IntegrateError as exc:
+        raise StageTargetError(
+            f"multi-dependency stage {stage_number}: {exc}") from exc
+    return merged.commit
 
 
 def resolve_stage_base_commit(
@@ -469,6 +544,7 @@ def resolve_stage_base_commit(
     candidate_base: str = "",
     project_root: Path | None = None,
     plan_run_root: Path | None = None,
+    identity: "StageWorktreeIdentity | None" = None,
 ) -> str:
     """Pick the git base commit a stage's isolated worktree branches from."""
     from .consumers import latest_done_by_stage
@@ -476,30 +552,9 @@ def resolve_stage_base_commit(
     latest = latest_done_by_stage(consumer_done_rows)
     deps = stage.get("depends_on") or []
     if len(deps) >= 2:
-        stage_number = stage["stage_number"]
-        pred_commits: dict[int, str] = {}
-        for dep_stage in deps:
-            head = (latest.get(dep_stage) or {}).get("head_commit")
-            if not head:
-                raise StageTargetError(
-                    f"predecessor stage {dep_stage} has no done row with head_commit "
-                    f"in consumers.jsonl; multi-dependency stage {stage_number} cannot start"
-                )
-            pred_commits[dep_stage] = head
-        if not candidate_base or project_root is None:
-            raise StageTargetError(
-                f"candidate base missing for multi-dependency stage {stage_number}; "
-                "task-key worktree HEAD could not be resolved"
-            )
-        check_multi_dep_merged(
-            project_root,
-            plan_run_root,
-            latest,
-            pred_commits,
-            candidate_base,
-            stage_number,
-        )
-        return candidate_base
+        return _multi_dep_base(
+            stage["stage_number"], list(deps), latest, anchor_base_commit,
+            candidate_base, project_root, plan_run_root, identity)
     if not deps:
         if not anchor_base_commit:
             raise StageTargetError(
@@ -677,9 +732,22 @@ def _resolve_and_integrate_whole_task_unlocked(
     done_rows: list[dict[str, Any]], anchor_base: str, teardown: bool,
 ) -> dict[str, Any]:
     """Integrate and resolve a whole-task target while the caller owns the lock."""
+    from .consumers import latest_done_by_stage
     from .stage_integrate import IntegrateError, integrate_stages
     from .worktree import _git, is_dirty_excluding_okstra
 
+    # 끝나지 않은 stage 가 있으면 _resolve_whole_task_target 이 어차피 거부한다.
+    # 그 전에 끝난 stage 를 머지해 두면 거부된 요청이 task worktree 에 머지를
+    # 남긴다(되돌리지 않는다). 머지하기 전에 같은 조건으로 거부한다.
+    done_by_stage = latest_done_by_stage(done_rows)
+    for stage in stage_map:
+        n = stage["stage_number"]
+        if n not in done_by_stage:
+            raise PrepareError(
+                f"final-verification(whole-task): stage {n} not done — "
+                f"run implementation --stage {n} first"
+            )
+
     try:
         integration = integrate_stages(
             project_id=project_id,
@@ -852,6 +920,93 @@ def _acquire_single_stage_target(
     )
 
 
+def single_containing_head(project_root: Path,
+                           heads: dict[int, str]) -> int | None:
+    """주어진 stage 들의 commit 을 혼자서 모두 담고 있는 stage. 없으면 None.
+
+    stage 브랜치는 스택이라 한 stage 가 다른 stage 들을 이미 담고 있는 경우가
+    흔하다. 그럴 땐 새 브랜치를 만들 이유가 없다 — 그 commit 이 곧 공통 바닥이다.
+    판정은 계획의 의존 그래프가 아니라 git 조상 관계로 한다: 계획상 tip 이어도 그
+    브랜치가 실제로 다른 stage 의 커밋을 담고 있는지가 문제이기 때문이다."""
+    from .worktree import is_ancestor
+
+    if not heads:
+        return None
+    for candidate, head in heads.items():
+        if all(is_ancestor(project_root, other, head)
+               for n, other in heads.items() if n != candidate):
+            return candidate
+    return None
+
+
+def containing_stage(project_root: Path,
+                     done_by_stage: dict[int, dict[str, Any]]) -> int | None:
+    """완료된 stage 전부를 혼자 담고 있는 stage. 하나라도 commit 이 비면 None.
+
+    whole-task 검증이 "이 브랜치가 곧 전체인가" 를 묻는 자리다. 병렬 stage 가 있어
+    tip 이 여럿이면 어느 브랜치도 전체가 아니므로 None 이다."""
+    heads = {n: row.get("head_commit", "")
+             for n, row in done_by_stage.items() if row.get("head_commit")}
+    if len(heads) != len(done_by_stage):
+        return None
+    return single_containing_head(project_root, heads)
+
+
+def _acquire_tip_stage_target(
+    request: FinalVerificationTargetRequest,
+    done_rows: list[dict[str, Any]],
+    registry_coordinates: tuple[str, str, str],
+) -> FinalVerificationTargetAcquisition | None:
+    """전체를 담은 단일 stage 브랜치가 있으면 그것을 whole-task 검증 대상으로
+    삼는다 — 머지 없이. 없거나 그 워크트리가 쓸 수 없으면 None 을 돌려 기존
+    task 브랜치 통합 경로로 넘긴다."""
+    from . import worktree_registry
+    from .consumers import latest_done_by_stage
+    from .worktree import _git, is_dirty_excluding_okstra
+
+    done = latest_done_by_stage(done_rows)
+    planned = [int(s["stage_number"]) for s in request.stage_map]
+    if any(n not in done for n in planned):
+        return None  # 미완 stage 의 거부 메시지는 기존 경로가 낸다
+    tip = containing_stage(request.project_root,
+                          {n: done[n] for n in planned})
+    if tip is None:
+        return None
+    row = worktree_registry.get_stage_row(*registry_coordinates, tip) or {}
+    worktree_path = row.get("worktree_path", "")
+    if not worktree_path or not Path(worktree_path).is_dir():
+        return None
+    head_result = _git(worktree_path, "rev-parse", "HEAD")
+    if head_result.returncode != 0:
+        return None
+    head = head_result.stdout.strip()
+    if head != done[tip].get("head_commit", ""):
+        # 브랜치 tip 이 done 기록과 갈라져 있다. 검증 대상이 무엇인지 모호하므로
+        # 판정을 기존 경로로 넘긴다.
+        return None
+    if is_dirty_excluding_okstra(worktree_path):
+        raise StageTargetError(
+            "final-verification: worktree has uncommitted source changes "
+            "(outside .okstra/) — commit or stash before verifying"
+        )
+    anchor_base = worktree_registry.get_implementation_base(
+        *registry_coordinates) or ""
+    stages = sorted(planned)
+    return FinalVerificationTargetAcquisition(
+        target=FinalVerificationTarget(
+            scope="whole-task",
+            base=anchor_base,
+            head=head,
+            worktree_path=worktree_path,
+            stages=stages,
+            reports=[done[n].get("report_path", "") for n in stages],
+        ),
+        relocations=(),
+        worktree_branch=row.get("branch", ""),
+        integration_result=None,
+    )
+
+
 def _acquire_whole_task_target(
     request: FinalVerificationTargetRequest,
     done_rows: list[dict[str, Any]],
@@ -859,6 +1014,10 @@ def _acquire_whole_task_target(
 ) -> FinalVerificationTargetAcquisition:
     from . import worktree_registry
 
+    tip = _acquire_tip_stage_target(request, done_rows, registry_coordinates)
+    if tip is not None:
+        return tip
+
     project_id, task_group, task_id = registry_coordinates
     entry = worktree_registry.lookup(project_id, task_group, task_id)
     worktree_path = (
@@ -946,6 +1105,8 @@ def integrate_and_teardown_whole_task(
     if entry is None:
         return {"skipped": "task worktree is no longer registered"}
 
+    done_by_stage = consumers.latest_done_by_stage(done_rows)
+    tip = containing_stage(project_root, done_by_stage)
     with worktree_provision_mutex(okstra_home(), project_id, task_group, task_id):
         result = integrate_stages(
             project_id=project_id,
@@ -955,6 +1116,11 @@ def integrate_and_teardown_whole_task(
             stage_map=stage_map,
             done_rows=done_rows,
             teardown=True,
+            # 한 stage 브랜치가 이미 전체를 담고 있으면 검증은 거기서 돌았다
+            # (`_acquire_tip_stage_target`). 그 경우 task 브랜치로의 머지는 아무도
+            # 읽지 않는 산출물이므로 정리만 한다.
+            merge=tip is None,
+            verified_head=(done_by_stage.get(tip) or {}).get("head_commit", ""),
         )
     return {
         "tornDown": result.torn_down,

package/runtime/python/okstra_ctl/team.py

@@ -36,7 +36,7 @@ from .dispatch_core import (
     await_dispatches,
     dispatch_plan,
 )
-from .ports.worker_dispatch import WorkerDispatchRequest
+from .ports.worker_dispatch import WorkerDispatchPort, WorkerDispatchRequest
 from .registry.host_registry import default_host_registry
 from .registry.provider_registry import default_provider_registry
 from .session import observe_lead_session
@@ -161,18 +161,7 @@ def _dispatch(args) -> int:
         raise DispatchError("--jobs-file and --workers cannot be combined")
     manifest = _load_manifest(args.project_root, args.run_manifest)
     _observe_lead_session_from_manifest(Path(args.project_root).resolve(), manifest)
-    terminal_backend = _manifest_backend(manifest)
-    lead_runtime = _require_string(manifest, "leadRuntime")
-    fallback_port = default_host_registry().resolve(
-        lead_runtime
-    ).worker_dispatch()
-    port = dispatch_port_for_terminal_backend(
-        terminal_backend,
-        fallback_port,
-        supported_worker_wrappers=_SUPPORTED_WRAPPERS,
-        unsupported_worker_label=f"{lead_runtime} lead",
-        required_lead_runtime=None if _is_cmux_run(manifest) else lead_runtime,
-    )
+    port = team_dispatch_port(manifest)
     request = WorkerDispatchRequest(
         project_root=Path(args.project_root),
         run_manifest=Path(args.run_manifest),
@@ -195,6 +184,26 @@ def _dispatch(args) -> int:
     return result
 
 
+def team_dispatch_port(manifest: Mapping[str, Any]) -> WorkerDispatchPort:
+    """이 run 의 워커를 띄울 포트. cmux run 이면 pane, 아니면 리드 호스트의 포트.
+
+    `team dispatch` 와 finalize 의 `translate` 단계가 같이 쓴다 — 번역자만
+    CLI 래퍼 디스패처로 띄우던 동안 cmux run 에서도 번역자는 pane 없이 돌았다
+    (실측 2026-09-22, dev-10860 implementation-planning-001: 18건 중 번역자 1건).
+    """
+    lead_runtime = _require_string(manifest, "leadRuntime")
+    fallback_port = default_host_registry().resolve(
+        lead_runtime
+    ).worker_dispatch()
+    return dispatch_port_for_terminal_backend(
+        _manifest_backend(manifest),
+        fallback_port,
+        supported_worker_wrappers=_SUPPORTED_WRAPPERS,
+        unsupported_worker_label=f"{lead_runtime} lead",
+        required_lead_runtime=None if _is_cmux_run(manifest) else lead_runtime,
+    )
+
+
 def _await(args) -> int:
     manifest = _load_manifest(args.project_root, args.run_manifest)
     _validate_team_manifest(manifest)