okstra 0.96.1 → 0.97.0

package/runtime/python/okstra_ctl/stage_integrate.py

@@ -0,0 +1,193 @@
+"""whole-task stage 통합(머지) + worktree teardown 코어.
+
+Phase A: stage done commit 을 task 브랜치에 위상순 --no-ff 머지(이미 머지면
+skip, 충돌이면 해당 머지만 abort 후 IntegrateError). Phase B: 머지/skip 된
+stage 의 worktree·registry 키·stage 브랜치를 정리(dirty 면 skip).
+설계: docs/superpowers/specs/2026-06-20-stage-auto-integrate-teardown-design.md
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from .worktree import _git
+
+
+class IntegrateError(Exception):
+    """stage 머지 충돌 등으로 통합을 중단해야 함."""
+
+
+@dataclass
+class IntegrateResult:
+    merged: list[int] = field(default_factory=list)
+    already_merged: list[int] = field(default_factory=list)
+    torn_down: list[int] = field(default_factory=list)
+    teardown_skipped: list[tuple[int, str]] = field(default_factory=list)
+    warnings: list[str] = field(default_factory=list)
+
+
+def _merge_stage(task_wt: str, stage_n: int, branch: str, done_commit: str) -> str:
+    """한 stage 의 done commit 을 task 브랜치에 머지. 'merged'|'already_merged'.
+    충돌 시 abort 후 IntegrateError.
+
+    already_merged 판정과 실제 머지 대상을 모두 done_commit 으로 통일한다 —
+    consumers 의 done.head_commit 은 reconcile 로 `-sN` 브랜치 tip 과 다른
+    commit 일 수 있어, ancestor 는 done_commit 으로 보고 머지는 브랜치 ref 로
+    하면 tip 이 아직 안 머지됐는데 skip 하거나 이미 머지된 변경을 중복 재도입할
+    수 있다. branch 는 정리(teardown) 식별용으로만 쓰고 머지 대상은 아니다."""
+    from .worktree import MergeError, is_ancestor, merge_branch
+
+    head = _git(task_wt, "rev-parse", "HEAD").stdout.strip()
+    if is_ancestor(task_wt, done_commit, head):
+        return "already_merged"
+    try:
+        conflicts = merge_branch(task_wt, done_commit, no_ff=True)
+    except MergeError as exc:
+        raise IntegrateError(
+            f"stage {stage_n} ({branch}) 머지 실패(내용 충돌 아님) — abort 함. "
+            f"{exc}. 원인 해소 후 재시도."
+        ) from exc
+    if conflicts is not None:
+        raise IntegrateError(
+            f"stage {stage_n} ({branch}) 머지 충돌 — abort 함. "
+            f"충돌 파일: {', '.join(conflicts) or '(unknown)'}. 수동 머지로 해소 후 재시도."
+        )
+    return "merged"
+
+
+def integrate_stages(
+    *, project_id: str, task_group: str, task_id: str,
+    task_worktree_path: str, stage_map: list[dict[str, Any]],
+    done_rows: list[dict[str, Any]],
+) -> IntegrateResult:
+    """whole-task 통합: Phase A 머지 → Phase B teardown."""
+    from .consumers import latest_done_by_stage
+
+    res = IntegrateResult()
+    if not task_worktree_path or not Path(task_worktree_path).exists():
+        return res  # non-git / degraded — no-op
+    done = latest_done_by_stage(done_rows)
+    ordered = sorted((s["stage_number"] for s in stage_map))
+
+    for n in ordered:
+        row = done.get(n)
+        if not row or not row.get("head_commit"):
+            continue  # 미완 stage 는 merged 게이트가 별도로 잡음
+        branch = _stage_branch_name(project_id, task_group, task_id, n)
+        if branch is None:
+            res.warnings.append(f"stage {n}: registry 에 stage-key 없음 — 머지 skip")
+            continue
+        try:
+            outcome = _merge_stage(task_worktree_path, n, branch,
+                                   row["head_commit"])
+        except IntegrateError as exc:
+            # 앞선 stage 머지는 이미 task 브랜치에 남는다(롤백 없음, 재시도 시
+            # already_merged 로 skip). 부분 통합 상태를 명시해 사용자가 인지하게 한다.
+            if res.merged:
+                raise IntegrateError(
+                    f"{exc} 이미 task 브랜치에 머지된 stage: {res.merged} "
+                    "— 재시도 시 자동 skip 됩니다.") from exc
+            raise
+        (res.merged if outcome == "merged" else res.already_merged).append(n)
+
+    _teardown_all(project_id, task_group, task_id, task_worktree_path, res)
+    return res
+
+
+def _stage_branch_name(project_id, task_group, task_id, stage_n) -> str | None:
+    from . import worktree_registry
+    row = worktree_registry.get_stage_row(project_id, task_group, task_id, stage_n)
+    if not row:
+        return None
+    return row.get("branch") or None
+
+
+def _teardown_all(project_id, task_group, task_id, task_wt: str,
+                  res: IntegrateResult) -> 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)
+        if outcome == "torn_down":
+            res.torn_down.append(n)
+        elif outcome == "skipped":
+            res.teardown_skipped.append((n, detail))
+        if outcome == "warn":
+            res.warnings.append(detail)
+
+
+def _remove_clean_worktree(task_wt: str, wt: str, stage_n: int) -> tuple[str, str] | None:
+    """clean stage worktree 를 물리 제거. dirty/실패면 (outcome, detail), 성공이면 None."""
+    from .worktree import is_dirty_excluding_okstra, remove_worktree_force
+
+    if is_dirty_excluding_okstra(wt):
+        return ("skipped", "dirty — 미커밋 변경 보존")
+    rm = remove_worktree_force(task_wt, wt)
+    if rm.returncode != 0:
+        return ("warn", f"stage {stage_n} worktree remove 실패: {rm.stderr.strip()}")
+    return None
+
+
+def _teardown_stage(project_id, task_group, task_id, task_wt, stage_n, row):
+    """clean stage worktree 를 제거 + registry release + branch -d.
+    branch -d 가 성공한 뒤에만 branch 슬롯을 free 한다 — 물리 브랜치가
+    살아있는 채로 슬롯이 풀려 동시 run 이 같은 이름을 재예약하는 윈도우를
+    막기 위함. 반환 ('torn_down'|'skipped'|'warn', detail)."""
+    from . import worktree_registry
+
+    wt = (row or {}).get("worktree_path") or ""
+    branch = (row or {}).get("branch") or ""
+    if wt and Path(wt).exists():
+        outcome = _remove_clean_worktree(task_wt, wt, stage_n)
+        if outcome is not None:
+            return outcome
+    worktree_registry.release_status(project_id, task_group, task_id, stage_number=stage_n)
+    if branch:
+        bd = _git(task_wt, "branch", "-d", branch)
+        if bd.returncode != 0:
+            return ("warn", f"stage {stage_n} branch -d {branch} 실패(미머지?): "
+                            f"{bd.stderr.strip()}")
+        worktree_registry.free_branch_slot(project_id, task_group, task_id,
+                                           stage_number=stage_n)
+    return ("torn_down", "")
+
+
+def main(argv: list[str] | None = None) -> int:
+    import argparse
+    import json
+    import sys
+
+    from .consumers import read_consumers
+
+    p = argparse.ArgumentParser(prog="okstra integrate-stages")
+    p.add_argument("--project-id", required=True)
+    p.add_argument("--task-group", required=True)
+    p.add_argument("--task-id", required=True)
+    p.add_argument("--plan-run-root", required=True)
+    p.add_argument("--task-worktree-path", required=True)
+    p.add_argument("--stage-map-json", default="[]",
+                   help="[{stage_number, depends_on}] JSON")
+    a = p.parse_args(argv)
+    # done 필터는 integrate_stages → latest_done_by_stage 가 단독 책임(SSOT).
+    try:
+        res = integrate_stages(
+            project_id=a.project_id, task_group=a.task_group,
+            task_id=a.task_id, task_worktree_path=a.task_worktree_path,
+            stage_map=json.loads(a.stage_map_json),
+            done_rows=read_consumers(Path(a.plan_run_root)),
+        )
+    except IntegrateError as exc:
+        print(f"integrate-stages: {exc}", file=sys.stderr)
+        return 2
+    print(f"merged={res.merged} already={res.already_merged} "
+          f"torn_down={res.torn_down} skipped={res.teardown_skipped}")
+    for w in res.warnings:
+        print(f"warning: {w}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/runtime/python/okstra_ctl/stage_targets.py

@@ -7,7 +7,6 @@ the stage lifecycle rules behind one interface instead of leaking raw
 """
 from __future__ import annotations
 
-import subprocess
 from dataclasses import dataclass
 from pathlib import Path
 from typing import Any
@@ -92,13 +91,8 @@ def resolve_effective_stages(
 
 def commit_is_ancestor(project_root: Path, ancestor: str, descendant: str) -> bool:
     """True iff ``ancestor`` is an ancestor of ``descendant`` in git history."""
-    result = subprocess.run(
-        ["git", "merge-base", "--is-ancestor", ancestor, descendant],
-        cwd=str(project_root),
-        capture_output=True,
-        text=True,
-    )
-    return result.returncode == 0
+    from .worktree import is_ancestor
+    return is_ancestor(project_root, ancestor, descendant)
 
 
 def check_multi_dep_merged(

package/runtime/python/okstra_ctl/task_target.py

@@ -44,7 +44,10 @@ def infer_project_root(task_root: Path) -> Path:
     parts = task_root.parts
     if ".okstra" not in parts:
         return task_root
-    idx = parts.index(".okstra")
+    # The okstra subtree (.okstra/tasks/...) introduces the deepest ".okstra"
+    # segment; a project checked out under a path that itself contains
+    # ".okstra" must not resolve to that outer segment.
+    idx = len(parts) - 1 - parts[::-1].index(".okstra")
     return Path(*parts[:idx]).resolve()
 
 

package/runtime/python/okstra_ctl/team_reconcile.py

@@ -112,7 +112,12 @@ def main(argv: list[str]) -> int:
         print(f"team-reconcile: no team config at {cfg_path}", file=sys.stderr)
         return 1
 
-    config = json.loads(cfg_path.read_text())
+    try:
+        config = json.loads(cfg_path.read_text())
+    except (OSError, json.JSONDecodeError) as exc:
+        print(f"team-reconcile: cannot read team config at {cfg_path}: {exc}",
+              file=sys.stderr)
+        return 1
     available, live = live_pane_ids()
     if not available:
         print("team-reconcile: tmux unavailable — skipped (no flip)")

package/runtime/python/okstra_ctl/wizard.py

@@ -43,7 +43,6 @@ from okstra_ctl.run import (
     _load_final_report_data_if_present,
     _reject_blocking_plan_body_gate,
     _set_data_json_approved_true_if_present,
-    _validate_data_json_approval_consistency,
     recommended_role_models,
 )
 from okstra_ctl.user_response import (
@@ -956,28 +955,42 @@ def _parse_stage_objects(state: WizardState) -> list:
 
 def _done_stage_numbers(state: WizardState) -> set:
     """approved plan 을 소비한 implementation run 들의 consumers.jsonl 에서
-    done 처리된 stage 번호 집합. git 호출 없음 — 파일 읽기만(prepare 와 동일 SSOT)."""
+    done 처리된 stage 번호 집합. 순수 읽기 — carry backfill 은 하지 않는다.
+
+    backfill_done_from_carry 는 consumers.jsonl 에 done 행을 append 하고
+    그 부수효과로 worktree-registry stage 점유를 해제한다. 이 함수는 stage
+    picker 표시와 progress 추정(_remaining_screens 가 매 step 반복 호출)에서만
+    쓰이므로, 화면을 그리는 것만으로 동시 실행 중인 run 의 점유를 풀면 안 된다.
+    carry 기반 done 보정은 prepare 게이트(run.py)가 단일 진입점으로 수행한다."""
     if not state.approved_plan_path:
         return set()
-    from .consumers import (read_consumers, backfill_done_from_carry,
-                            latest_done_by_stage)
+    from .consumers import read_consumers, latest_done_by_stage
     plan_run_root = Path(state.approved_plan_path).resolve().parents[1]
-    backfill_done_from_carry(plan_run_root)
     rows = read_consumers(plan_run_root)
     return set(latest_done_by_stage(rows).keys())
 
 
-def _whole_task_allowed(state: WizardState) -> bool:
+def _whole_task_allowed(
+    state: WizardState,
+    *,
+    stages: Optional[list] = None,
+    done: Optional[set] = None,
+) -> bool:
     """final-verification 이고 Stage Map 의 모든 stage 가 done 일 때만 True.
-    위저드는 done 만 본다 — 머지/clean/active 는 prepare 게이트가 강제한다."""
+    위저드는 done 만 본다 — 머지/clean/active 는 prepare 게이트가 강제한다.
+
+    `stages`/`done` 를 넘기면 재파싱(validator exec_module)·재읽기를 생략한다 —
+    이미 둘을 계산한 `_build_stage_pick` 의 hot path 중복을 없애기 위한 seam."""
     if state.task_type != "final-verification":
         return False
     if not state.approved_plan_path:
         return False
-    stages = _parse_stage_objects(state)
+    if stages is None:
+        stages = _parse_stage_objects(state)
     if not stages:
         return False
-    done = _done_stage_numbers(state)
+    if done is None:
+        done = _done_stage_numbers(state)
     return all(s.stage_number in done for s in stages)
 
 
@@ -1801,7 +1814,7 @@ def _build_stage_pick(state: WizardState) -> Prompt:
     options = []
     if _stage_auto_allowed(state):
         options.append(_opt("auto", t["options"]["auto"]))
-    if _whole_task_allowed(state):
+    if _whole_task_allowed(state, stages=stages, done=done):
         options.append(_opt(WHOLE_TASK_STAGE, t["options"]["whole_task"]))
     for s in stages:
         depends = ",".join(map(str, s.depends_on)) or "(none)"
@@ -3281,8 +3294,10 @@ def _sim_advance(state: WizardState, prompt: Prompt) -> None:
         STEP_BY_ID[prompt.step].submit(state, _sim_answer(prompt))
         if prompt.step not in state.answered:
             state.answered.append(prompt.step)
-    except Exception:
-        # 추천 경로가 막히는 드문 text 분기: answered 마킹만으로 전진시킨다.
+    except WizardError:
+        # 추천 기본답이 검증에서 막히는 드문 text 분기(WizardError)만 전진 처리한다.
+        # KeyError/AttributeError 등 실제 버그는 삼키지 않고 그대로 전파시켜
+        # progress 라벨이 그럴듯하게 틀리는 대신 테스트/실행에서 시끄럽게 실패한다.
         members = prompt.questions if prompt.kind == "pick_group" else [prompt]
         for p in members:
             if p.step not in state.answered:

package/runtime/python/okstra_ctl/workflow.py

@@ -98,7 +98,7 @@ PHASE_RULES: dict[str, dict[str, str]] = {
     "release-handoff": {
         "allowed": (
             "  - entering this phase only when the cited final-verification report's `Verdict Token` is exactly `accepted`\n"
-            "  - asking the user (via `AskUserQuestion` / interactive prompt) which delivery action to take: `local only`, `push + PR`, or `skip` (end the run)\n"
+            "  - asking the user (via `AskUserQuestion` / interactive prompt) which delivery action to take: `local checkout`, `push + PR`, or `skip` (end the run)\n"
             "  - asking the user to pick a PR base branch from `staging` | `preprod` | `prod` | `main` | `dev` | a user-supplied branch name\n"
             "  - drafting PR title and PR body **inline as the Claude lead** (no drafter worker, no `Agent` dispatch); the lead reviews its own draft with the user before any mutating git / gh command runs\n"
             "  - read-only git inspection: `git status`, `git diff`, `git log`, `git rev-parse`\n"
@@ -129,6 +129,14 @@ def load_phase_forbidden(workspace_root: Path) -> dict[str, str]:
     """
     path = Path(workspace_root) / "prompts" / "profiles" / "forbidden-actions.json"
     data = json.loads(path.read_text(encoding="utf-8"))
+    if "unknown" not in data:
+        # compute_workflow_state falls back to the "unknown" entry for any
+        # unmapped task_type; without it a missing/renamed key would surface as
+        # a KeyError deep in prompt assembly instead of here at the SSOT seam.
+        raise ValueError(
+            f"forbidden-actions SSOT at {path} is missing the required "
+            "'unknown' fallback entry"
+        )
     return {phase: render_forbidden(items) for phase, items in data.items()}
 
 

package/runtime/python/okstra_ctl/worktree.py

@@ -426,6 +426,89 @@ def okstra_clean_gate_excludes(project_root: Optional[Path] = None) -> tuple[str
     return tuple(out)
 
 
+def nested_worktree_excludes(worktree_path) -> tuple[str, ...]:
+    """Relative paths of git worktrees nested under `worktree_path`.
+
+    implementation stage worktrees live inside the task worktree
+    (`<task-id>/stage-<N>/`), so the parent's `git status --short` reports
+    each as an untracked `?? stage-N/`. They are git-registered worktrees,
+    not user source changes, so clean gates must ignore them. Derived from
+    `git worktree list` rather than a hardcoded pattern so it tracks exactly
+    what git registered.
+    """
+    root = Path(worktree_path).resolve()
+    r = _git(root, "worktree", "list", "--porcelain")
+    if r.returncode != 0:
+        return ()
+    out: list[str] = []
+    for line in r.stdout.splitlines():
+        if not line.startswith("worktree "):
+            continue
+        wt = Path(line[len("worktree "):].strip()).resolve()
+        if wt == root:
+            continue
+        try:
+            rel = wt.relative_to(root)
+        except ValueError:
+            continue
+        out.append(str(rel))
+    return tuple(out)
+
+
+def is_ancestor(cwd, commit: str, head: str) -> bool:
+    """True iff `commit` is an ancestor of `head` (both non-empty)."""
+    if not commit or not head:
+        return False
+    return _git(Path(cwd), "merge-base", "--is-ancestor", commit, head).returncode == 0
+
+
+def is_dirty_excluding_okstra(cwd) -> bool:
+    """True iff the worktree has changes outside okstra-owned paths.
+
+    okstra-owned = `okstra_clean_gate_excludes` (e.g. `.okstra`, synced dirs)
+    plus `nested_worktree_excludes` (stage worktrees nested under `cwd`).
+    """
+    owned = (*okstra_clean_gate_excludes(Path(cwd)), *nested_worktree_excludes(cwd))
+    excludes = [f":(exclude){p}" for p in owned]
+    out = _git(Path(cwd), "status", "--short", "--", ".", *excludes).stdout
+    return bool(out.strip())
+
+
+class MergeError(RuntimeError):
+    """`git merge` 가 내용 충돌이 아닌 사유로 실패했을 때(추적되지 않은 파일
+    덮어쓰기, 진행 중인 머지 잔존, 없는 브랜치 등) 던진다. 충돌 파일이 0개인
+    실패를 '충돌'로 둔갑시키지 않고 git stderr 를 그대로 노출해 호출자가 올바른
+    복구 경로로 안내하도록 한다."""
+
+
+def merge_branch(cwd, branch: str, *, no_ff: bool) -> list[str] | None:
+    """`branch` 를 cwd 의 현재 HEAD 에 머지한다. 성공이면 None, 내용 충돌이면
+    abort 후 충돌 파일 목록을 반환한다(최소 1개). 충돌이 아닌 머지 실패는
+    MergeError 로 던진다 — 충돌 0개를 충돌로 보고하지 않기 위함. 호출자가 충돌
+    목록을 HandoffConflict/IntegrateError 등 적절한 예외로 변환한다 — 머지·
+    충돌감지·abort 시퀀스의 단일 지점."""
+    args = ["merge", "--no-ff", "--no-edit", branch] if no_ff \
+        else ["merge", "--no-edit", branch]
+    res = _git(Path(cwd), *args)
+    if res.returncode == 0:
+        return None
+    conflicts = _git(Path(cwd), "diff", "--name-only",
+                     "--diff-filter=U").stdout.split()
+    _git(Path(cwd), "merge", "--abort")
+    if not conflicts:
+        raise MergeError((res.stderr or res.stdout).strip()
+                         or f"git merge {branch} failed (exit={res.returncode})")
+    return conflicts
+
+
+def remove_worktree_force(cwd, worktree_path) -> subprocess.CompletedProcess:
+    """워크트리를 강제 제거한다. provision_*_worktree 가 워크트리에 .okstra·
+    synced 디렉터리/파일 symlink(untracked) 를 깔기 때문에 plain remove 는 그
+    잔여물 때문에 git 이 거부한다 — dirty 게이트로 실사용자 변경을 막은 뒤
+    --force 로 okstra 잔여물만 정리하는 단일 지점."""
+    return _git(Path(cwd), "worktree", "remove", "--force", str(worktree_path))
+
+
 def _link_sync_dirs(source_root: Path, worktree_path: Path) -> list[str]:
     """Symlink each configured dir from `source_root` (the MAIN
     worktree) into the new worktree.
@@ -449,7 +532,10 @@ def _link_sync_dirs(source_root: Path, worktree_path: Path) -> list[str]:
         if dst.exists() or dst.is_symlink():
             continue
         dst.parent.mkdir(parents=True, exist_ok=True)
-        os.symlink(src, dst)
+        try:
+            os.symlink(src, dst)
+        except FileExistsError:
+            continue
         notes.append(rel)
     return notes
 
@@ -472,7 +558,10 @@ def _link_sync_files(source_root: Path, worktree_path: Path) -> list[str]:
         if dst.exists() or dst.is_symlink():
             continue
         dst.parent.mkdir(parents=True, exist_ok=True)
-        os.symlink(src, dst)
+        try:
+            os.symlink(src, dst)
+        except FileExistsError:
+            continue
         notes.append(rel)
     return notes
 
@@ -748,7 +837,7 @@ def provision_task_worktree(
     except RuntimeError:
         # Roll back the on-disk worktree so the next attempt is not
         # blocked by the lingering directory / branch.
-        _git(main_root, "worktree", "remove", "--force", str(worktree_path))
+        remove_worktree_force(main_root, worktree_path)
         _git(main_root, "branch", "-D", branch)
         raise
 
@@ -872,7 +961,7 @@ def provision_stage_worktree(
             stage_number=stage_number,
         )
     except RuntimeError:
-        _git(main_root, "worktree", "remove", "--force", str(worktree_path))
+        remove_worktree_force(main_root, worktree_path)
         _git(main_root, "branch", "-D", branch)
         raise
 

package/runtime/python/okstra_ctl/worktree_registry.py

@@ -184,6 +184,11 @@ def reserve(
             "stage": stage_number,
             "stages": stages,
         }
+        # Re-reserving a released task-key must not drop the anchor: the
+        # implementation base commit is task-lifetime state, not per-reservation,
+        # so a release()/reserve() cycle (e.g. local_checkout) keeps it.
+        if existing and existing.get("implementation_base_commit"):
+            row["implementation_base_commit"] = existing["implementation_base_commit"]
         data["tasks"][key] = row
         data["branches"][branch] = key
         _save(data)
@@ -289,15 +294,17 @@ def list_active_stage_numbers(
         return out
 
 
-def release(
+def release_status(
     project_id: str, task_group: str, task_id: str,
     stage_number: Optional[int] = None,
     group_id: Optional[str] = None,
 ) -> Optional[WorktreeEntry]:
-    """Mark the entry as `released` (worktree dir intact — preservation
-    is the project's policy). The branch index is freed so future
-    reservations of the same branch name are not blocked.
-    Returns the prior entry, or None when not found.
+    """Mark the entry as `released` WITHOUT freeing its branch index slot.
+
+    Use when the physical branch still exists and its name must stay
+    reserved — e.g. teardown defers the slot-free until `git branch -d`
+    actually succeeds, so the registry never advertises a free branch
+    name that is still alive on disk. Returns the prior entry, or None.
     """
     key = task_key(project_id, task_group, task_id, stage_number, group_id)
     with _registry_lock():
@@ -306,8 +313,50 @@ def release(
         if not row:
             return None
         row["status"] = "released"
-        # Free the branch slot so reuse / new task can reclaim the name.
-        if data["branches"].get(row["branch"]) == key:
-            del data["branches"][row["branch"]]
         _save(data)
         return WorktreeEntry(task_key=key, **row)
+
+
+def free_branch_slot(
+    project_id: str, task_group: str, task_id: str,
+    stage_number: Optional[int] = None,
+    group_id: Optional[str] = None,
+) -> bool:
+    """Free only the branch index slot for this key. Returns True when a
+    slot was freed.
+
+    Call this ONLY after the physical branch is deleted, so the invariant
+    "a branch name the registry marks free is always physically deleted"
+    holds even under concurrent runs on the same machine.
+    """
+    key = task_key(project_id, task_group, task_id, stage_number, group_id)
+    with _registry_lock():
+        data = _load()
+        row = data["tasks"].get(key)
+        if not row:
+            return False
+        branch = row.get("branch")
+        if branch and data["branches"].get(branch) == key:
+            del data["branches"][branch]
+            _save(data)
+            return True
+        return False
+
+
+def release(
+    project_id: str, task_group: str, task_id: str,
+    stage_number: Optional[int] = None,
+    group_id: Optional[str] = None,
+) -> Optional[WorktreeEntry]:
+    """Mark the entry as `released` and free its branch slot (worktree dir
+    intact — preservation is the project's policy). Used by callers that
+    release at a point where the branch is gone or intentionally orphaned
+    (done-time reservation release, group cleanup). Teardown of a physical
+    branch must instead pair `release_status` + `free_branch_slot` so the
+    slot is freed only after `git branch -d` succeeds.
+    Returns the prior entry, or None when not found.
+    """
+    entry = release_status(project_id, task_group, task_id, stage_number, group_id)
+    if entry is not None:
+        free_branch_slot(project_id, task_group, task_id, stage_number, group_id)
+    return entry