prizmkit 1.1.100 → 1.1.101

package/bundled/dev-pipeline/prizmkit_runtime/gitops.py

@@ -0,0 +1,734 @@
+"""Branch and worktree helper primitives."""
+
+from __future__ import annotations
+
+import os
+import re
+import shutil
+import subprocess
+from collections.abc import Sequence
+from dataclasses import dataclass
+from pathlib import Path
+
+
+HIDDEN_TOOL_WORKTREE_EXCLUDES = (
+    ":(top,exclude).prizmkit-worktree",
+    ":(top,exclude).skills-lock.json",
+    ":(top,exclude).AGENTS.md",
+    ":(top,exclude,glob).*/worktree",
+    ":(top,exclude,glob).*/worktree/**",
+    ":(top,exclude,glob).*/worktrees",
+    ":(top,exclude,glob).*/worktrees/**",
+    ":(top,exclude).claude",
+    ":(top,exclude,glob).claude/**",
+    ":(top,exclude).codebuddy",
+    ":(top,exclude,glob).codebuddy/**",
+    ":(top,exclude).codex",
+    ":(top,exclude,glob).codex/**",
+    ":(top,exclude).agents",
+    ":(top,exclude,glob).agents/**",
+    ":(top,exclude).prizmkit/prizm-docs",
+    ":(top,exclude,glob).prizmkit/prizm-docs/**",
+    ":(top,exclude).prizmkit/config.json",
+    ":(top,exclude).prizmkit/manifest.json",
+    ":(top,exclude).prizmkit/dev-pipeline/scripts",
+    ":(top,exclude,glob).prizmkit/dev-pipeline/scripts/**",
+)
+
+WORKTREE_PLATFORM_SUPPORT_DIRS = (".claude", ".codebuddy", ".codex", ".agents")
+WORKTREE_ROOT_SUPPORT_FILES = ("skills-lock.json", "AGENTS.md")
+WORKTREE_PRIZMKIT_SUPPORT_ENTRIES = ("prizm-docs", "config.json", "manifest.json")
+WORKTREE_SUPPORT_IGNORE_NAMES = {"__pycache__", ".DS_Store", "settings.local.json"}
+
+
+@dataclass(frozen=True)
+class BranchContext:
+    """Branch state required by git/worktree helpers."""
+
+    base_branch: str
+    working_branch: str
+    project_root: Path
+    remote_name: str = "origin"
+
+
+@dataclass(frozen=True)
+class WorktreePolicy:
+    """Worktree creation and cleanup policy for later porting."""
+
+    use_worktree: bool
+    cleanup_on_success: bool
+    preserve_on_failure: bool
+    worktree_root: Path | None = None
+
+
+
+
+@dataclass(frozen=True)
+class WorktreeRuntimeContext:
+    """Resolved linked-worktree paths and safety metadata."""
+
+    context: BranchContext
+    policy: WorktreePolicy
+    worktree_root: Path
+    worktree_path: Path
+    sentinel_path: Path
+
+    def is_cleanup_path_safe(self) -> bool:
+        root = self.worktree_root.resolve()
+        target = self.worktree_path.resolve()
+        try:
+            return os.path.commonpath([str(root), str(target)]) == str(root) and target != root
+        except ValueError:
+            return False
+
+
+
+
+@dataclass(frozen=True)
+class WorktreeOperationResult:
+    """Executable linked-worktree operation result."""
+
+    ok: bool
+    reason: str = ""
+    runtime: WorktreeRuntimeContext | None = None
+    results: tuple[GitCommandResult, ...] = ()
+
+
+@dataclass(frozen=True)
+class WorktreeRemovalResult:
+    """Guarded worktree removal result."""
+
+    ok: bool
+    reason: str = ""
+    results: tuple[GitCommandResult, ...] = ()
+
+
+@dataclass(frozen=True)
+class WorktreeSupportAssetsResult:
+    """Support assets materialized into an AI-visible linked worktree."""
+
+    ok: bool
+    copied: tuple[Path, ...] = ()
+    existing: tuple[Path, ...] = ()
+    missing: tuple[str, ...] = ()
+    reason: str = ""
+
+
+def _safe_worktree_name(branch_name: str) -> str:
+    safe = re.sub(r"[^A-Za-z0-9._-]+", "-", branch_name.strip())
+    safe = safe.strip(".-")
+    return safe or "worktree"
+
+
+def worktree_runtime_context(context: BranchContext, policy: WorktreePolicy) -> WorktreeRuntimeContext:
+    """Resolve deterministic per-branch worktree paths under a runner-owned root."""
+    root = (policy.worktree_root or context.project_root / ".prizmkit" / "state" / "worktrees").resolve()
+    worktree_path = root / _safe_worktree_name(context.working_branch)
+    return WorktreeRuntimeContext(
+        context=context,
+        policy=policy,
+        worktree_root=root,
+        worktree_path=worktree_path,
+        sentinel_path=worktree_path / ".prizmkit-worktree",
+    )
+
+
+def linked_worktree_setup_plan(runtime: WorktreeRuntimeContext) -> GitCommandPlan:
+    """Plan linked-worktree branch creation without main-worktree checkout."""
+    context = runtime.context
+    return GitCommandPlan(
+        name="linked_worktree_setup",
+        commands=(
+            _git("rev-parse", "--verify", context.working_branch, allow_failure=True, description="check existing branch"),
+            _git("branch", context.working_branch, context.base_branch, allow_failure=True, description="create branch without checkout"),
+            _git("worktree", "list", "--porcelain", allow_failure=True, description="inspect registered worktrees"),
+            _git("worktree", "add", "--checkout", str(runtime.worktree_path), context.working_branch, allow_failure=True, description="create or reuse linked worktree"),
+        ),
+        notes=(
+            "Creates the task branch without checking it out in the main working tree.",
+            "A deterministic path lets context-overflow continuations reuse the same worktree.",
+        ),
+        require_one_success=((0, 1),),
+    )
+
+
+def worktree_merge_plan(runtime: WorktreeRuntimeContext, *, auto_push: bool = False) -> GitCommandPlan:
+    """Plan rebase-in-worktree then fast-forward merge in the main repository."""
+    context = runtime.context
+    commands = [
+        _git("rebase", context.base_branch, description="rebase worktree branch onto base"),
+        _git("merge", "--ff-only", context.working_branch, description="fast-forward base from worktree branch"),
+    ]
+    if auto_push:
+        commands.append(_git("push", allow_failure=True, description="optional auto-push after merge"))
+    return GitCommandPlan(
+        name="worktree_merge",
+        commands=tuple(commands),
+        notes=("Run rebase in the linked worktree and merge from the main checkout after checkout-free setup.",),
+    )
+
+
+def worktree_remove_plan(runtime: WorktreeRuntimeContext, *, delete_branch: bool = True) -> GitCommandPlan:
+    """Plan guarded linked-worktree removal and optional branch deletion."""
+    commands = [
+        _git("worktree", "remove", "--force", str(runtime.worktree_path), description="remove linked worktree"),
+    ]
+    if delete_branch:
+        commands.append(_git("branch", "-d", runtime.context.working_branch, allow_failure=True, description="delete merged task branch"))
+    return GitCommandPlan(
+        name="worktree_remove",
+        commands=tuple(commands),
+        notes=("Caller must verify cleanup safety and registration before executing.",),
+    )
+
+
+def worktree_registered(runtime: WorktreeRuntimeContext) -> bool:
+    """Return whether git worktree metadata contains the resolved path."""
+    result = run_git_command(runtime.context.project_root, ("worktree", "list", "--porcelain"))
+    if result.return_code != 0:
+        return False
+    target = str(runtime.worktree_path.resolve())
+    candidates: list[str] = []
+    for line in result.stdout.splitlines():
+        stripped = line.strip()
+        if stripped.startswith("worktree "):
+            candidates.append(stripped.removeprefix("worktree ").strip())
+        elif stripped:
+            candidates.append(stripped.split()[0])
+    return any(Path(candidate).resolve() == Path(target) for candidate in candidates if candidate)
+
+
+def mark_worktree_sentinel(runtime: WorktreeRuntimeContext) -> None:
+    """Write a small runner-owned sentinel inside a linked worktree."""
+    runtime.sentinel_path.parent.mkdir(parents=True, exist_ok=True)
+    runtime.sentinel_path.write_text(runtime.context.working_branch + "\n", encoding="utf-8")
+
+
+
+def materialize_worktree_support_assets(runtime: WorktreeRuntimeContext) -> WorktreeSupportAssetsResult:
+    """Copy ignored/untracked PrizmKit support assets into the linked worktree.
+
+    Git worktree checkout materializes only tracked files. Platform agent
+    definitions, Prizm docs/config, and installed runtime utility scripts are
+    commonly ignored support assets, yet generated prompts reference them from
+    the AI-visible project root. Copy only missing support files so continuation
+    worktrees keep any task-local artifact changes.
+    """
+    source_root = runtime.context.project_root
+    target_root = runtime.worktree_path
+    copied: list[Path] = []
+    existing: list[Path] = []
+    missing: list[str] = []
+
+    try:
+        for relative in WORKTREE_PLATFORM_SUPPORT_DIRS:
+            _materialize_optional_support_entry(source_root, target_root, relative, copied, existing, missing)
+        for relative in WORKTREE_ROOT_SUPPORT_FILES:
+            _materialize_optional_support_entry(source_root, target_root, relative, copied, existing, missing)
+        for relative in WORKTREE_PRIZMKIT_SUPPORT_ENTRIES:
+            _materialize_optional_support_entry(
+                source_root / ".prizmkit",
+                target_root / ".prizmkit",
+                relative,
+                copied,
+                existing,
+                missing,
+            )
+
+        runtime_scripts = _runtime_support_scripts_source(source_root)
+        if runtime_scripts is None:
+            missing.append(".prizmkit/dev-pipeline/scripts")
+        else:
+            target = target_root / ".prizmkit" / "dev-pipeline" / "scripts"
+            changed = _copy_support_entry(runtime_scripts, target)
+            (copied if changed else existing).append(target)
+    except OSError as exc:
+        return WorktreeSupportAssetsResult(False, tuple(copied), tuple(existing), tuple(missing), str(exc))
+
+    return WorktreeSupportAssetsResult(True, tuple(copied), tuple(existing), tuple(missing))
+
+
+def _materialize_optional_support_entry(
+    source_root: Path,
+    target_root: Path,
+    relative: str,
+    copied: list[Path],
+    existing: list[Path],
+    missing: list[str],
+) -> None:
+    source = source_root / relative
+    target = target_root / relative
+    if not source.exists() and not source.is_symlink():
+        missing.append(relative)
+        return
+    changed = _copy_support_entry(source, target)
+    (copied if changed else existing).append(target)
+
+
+def _runtime_support_scripts_source(project_root: Path) -> Path | None:
+    candidates = (
+        project_root / ".prizmkit" / "dev-pipeline" / "scripts",
+        project_root / "dev-pipeline" / "scripts",
+    )
+    for candidate in candidates:
+        if candidate.is_dir():
+            return candidate
+    return None
+
+
+def _copy_support_entry(source: Path, target: Path) -> bool:
+    if source.is_symlink():
+        if target.exists() or target.is_symlink():
+            return False
+        target.parent.mkdir(parents=True, exist_ok=True)
+        os.symlink(os.readlink(source), target)
+        return True
+    if source.is_file():
+        if target.exists():
+            return False
+        target.parent.mkdir(parents=True, exist_ok=True)
+        shutil.copy2(source, target)
+        return True
+
+    changed = False
+    if not target.exists():
+        target.mkdir(parents=True, exist_ok=True)
+        changed = True
+    for current_root, dir_names, file_names in os.walk(source):
+        dir_names[:] = [name for name in dir_names if not _skip_support_asset_name(name)]
+        relative_root = Path(current_root).relative_to(source)
+        target_root = target / relative_root
+        if not target_root.exists():
+            target_root.mkdir(parents=True, exist_ok=True)
+            changed = True
+        for file_name in file_names:
+            if _skip_support_asset_name(file_name):
+                continue
+            source_file = Path(current_root) / file_name
+            target_file = target_root / file_name
+            if target_file.exists() or target_file.is_symlink():
+                continue
+            if source_file.is_symlink():
+                os.symlink(os.readlink(source_file), target_file)
+            else:
+                shutil.copy2(source_file, target_file)
+            changed = True
+    return changed
+
+
+def _skip_support_asset_name(name: str) -> bool:
+    return name in WORKTREE_SUPPORT_IGNORE_NAMES or name.endswith(".pyc")
+
+
+def ensure_linked_worktree(runtime: WorktreeRuntimeContext) -> WorktreeOperationResult:
+    """Create or reuse a linked worktree for the runtime context."""
+    if not runtime.policy.use_worktree:
+        return WorktreeOperationResult(False, "worktree_disabled", runtime)
+    if not runtime.is_cleanup_path_safe():
+        return WorktreeOperationResult(False, "unsafe_worktree_path", runtime)
+
+    runtime.worktree_root.mkdir(parents=True, exist_ok=True)
+    results: list[GitCommandResult] = []
+
+    branch_check = run_git_command(runtime.context.project_root, ("rev-parse", "--verify", runtime.context.working_branch))
+    results.append(branch_check)
+    if branch_check.return_code != 0:
+        branch_create = run_git_command(
+            runtime.context.project_root,
+            ("branch", runtime.context.working_branch, runtime.context.base_branch),
+        )
+        results.append(branch_create)
+        if branch_create.return_code != 0:
+            return WorktreeOperationResult(False, "branch_create_failed", runtime, tuple(results))
+
+    if worktree_registered(runtime):
+        mark_worktree_sentinel(runtime)
+        return WorktreeOperationResult(True, runtime=runtime, results=tuple(results))
+
+    if runtime.worktree_path.exists() and any(runtime.worktree_path.iterdir()):
+        return WorktreeOperationResult(False, "worktree_path_exists_unregistered", runtime, tuple(results))
+
+    add = run_git_command(
+        runtime.context.project_root,
+        ("worktree", "add", "--checkout", str(runtime.worktree_path), runtime.context.working_branch),
+    )
+    results.append(add)
+    if add.return_code != 0:
+        if worktree_registered(runtime):
+            mark_worktree_sentinel(runtime)
+            return WorktreeOperationResult(True, runtime=runtime, results=tuple(results))
+        return WorktreeOperationResult(False, "worktree_add_failed", runtime, tuple(results))
+
+    mark_worktree_sentinel(runtime)
+    return WorktreeOperationResult(True, runtime=runtime, results=tuple(results))
+
+
+def merge_linked_worktree(runtime: WorktreeRuntimeContext, *, auto_push: bool = False) -> WorktreeOperationResult:
+    """Rebase the linked worktree branch and fast-forward merge it into base."""
+    results: list[GitCommandResult] = []
+    rebase = run_git_command(runtime.worktree_path, ("rebase", runtime.context.base_branch))
+    results.append(rebase)
+    if rebase.return_code != 0:
+        results.append(run_git_command(runtime.worktree_path, ("rebase", "--abort")))
+        return WorktreeOperationResult(False, "merge_conflict", runtime, tuple(results))
+
+    checkout = run_git_command(runtime.context.project_root, ("checkout", runtime.context.base_branch))
+    results.append(checkout)
+    if checkout.return_code != 0:
+        return WorktreeOperationResult(False, "base_checkout_failed", runtime, tuple(results))
+
+    merge = run_git_command(runtime.context.project_root, ("merge", "--ff-only", runtime.context.working_branch))
+    results.append(merge)
+    if merge.return_code != 0:
+        results.append(run_git_command(runtime.context.project_root, ("merge", "--abort")))
+        return WorktreeOperationResult(False, "merge_conflict", runtime, tuple(results))
+
+    if auto_push:
+        results.append(run_git_command(runtime.context.project_root, ("push",)))
+
+    return WorktreeOperationResult(True, runtime=runtime, results=tuple(results))
+
+def guarded_worktree_remove(runtime: WorktreeRuntimeContext, *, delete_branch: bool = True) -> WorktreeRemovalResult:
+    """Remove a worktree only when path, sentinel, and git metadata are safe."""
+    if not runtime.is_cleanup_path_safe():
+        return WorktreeRemovalResult(False, "unsafe_worktree_path")
+    if not runtime.sentinel_path.is_file():
+        return WorktreeRemovalResult(False, "missing_worktree_sentinel")
+    if not worktree_registered(runtime):
+        return WorktreeRemovalResult(False, "worktree_not_registered")
+    results: list[GitCommandResult] = []
+    for command in worktree_remove_plan(runtime, delete_branch=delete_branch).commands:
+        result = run_git_command(runtime.context.project_root, command.args)
+        results.append(result)
+        if result.return_code != 0 and not command.allow_failure:
+            return WorktreeRemovalResult(False, command.description or "worktree_remove_failed", tuple(results))
+    return WorktreeRemovalResult(True, results=tuple(results))
+
+
+@dataclass(frozen=True)
+class GitCommand:
+    """One planned git command."""
+
+    args: tuple[str, ...]
+    allow_failure: bool = False
+    description: str = ""
+
+
+@dataclass(frozen=True)
+class GitCommandPlan:
+    """A deterministic branch/worktree command plan."""
+
+    name: str
+    commands: tuple[GitCommand, ...]
+    never_fails: bool = False
+    notes: tuple[str, ...] = ()
+    require_one_success: tuple[tuple[int, ...], ...] = ()
+
+
+@dataclass(frozen=True)
+class GitCommandResult:
+    """Result from running one git command."""
+
+    args: tuple[str, ...]
+    return_code: int
+    stdout: str
+    stderr: str
+
+
+@dataclass(frozen=True)
+class GitPlanResult:
+    """Result from running a command plan."""
+
+    plan: GitCommandPlan
+    results: tuple[GitCommandResult, ...]
+
+    @property
+    def ok(self) -> bool:
+        if self.plan.never_fails:
+            return True
+        for command, result in zip(self.plan.commands, self.results):
+            if result.return_code != 0 and not command.allow_failure:
+                return False
+        for success_group in self.plan.require_one_success:
+            if not any(
+                index < len(self.results) and self.results[index].return_code == 0
+                for index in success_group
+            ):
+                return False
+        return True
+
+
+def _git(*args: str, allow_failure: bool = False, description: str = "") -> GitCommand:
+    return GitCommand(args=args, allow_failure=allow_failure, description=description)
+
+
+def branch_create_plan(context: BranchContext) -> GitCommandPlan:
+    """Plan shell-equivalent branch_create intent."""
+    return GitCommandPlan(
+        name="branch_create",
+        commands=(
+            _git("rev-parse", "--verify", context.working_branch, allow_failure=True, description="check existing branch"),
+            _git("checkout", "-b", context.working_branch, context.base_branch, allow_failure=True, description="create branch if absent"),
+            _git("checkout", context.working_branch, allow_failure=True, description="checkout existing branch fallback"),
+        ),
+        notes=("Create and checkout branch from source, or checkout if it already exists.",),
+        require_one_success=((1, 2),),
+    )
+
+
+def branch_return_plan(context: BranchContext) -> GitCommandPlan:
+    """Plan shell-equivalent branch_return intent."""
+    return GitCommandPlan(
+        name="branch_return",
+        commands=(
+            _git("rev-parse", "--abbrev-ref", "HEAD", description="detect current branch"),
+            _git("checkout", context.base_branch, allow_failure=True, description="checkout original branch if needed"),
+        ),
+        notes=("Safe when already on the original branch.",),
+    )
+
+
+def branch_merge_plan(context: BranchContext, *, auto_push: bool = False) -> GitCommandPlan:
+    """Plan shell-equivalent branch_merge safety invariants."""
+    commands = [
+        _git("diff", "--name-only", allow_failure=True, description="detect tracked dirty files"),
+        _git("diff", "--cached", "--name-only", allow_failure=True, description="detect staged dirty files"),
+        _git("stash", "push", "-m", "pipeline-merge-stash", allow_failure=True, description="stash tracked dirty files only"),
+        _git("rebase", context.base_branch, context.working_branch, description="rebase dev onto original"),
+        _git("checkout", context.base_branch, description="checkout original for fast-forward"),
+        _git("merge", "--ff-only", context.working_branch, description="fast-forward original"),
+    ]
+    if auto_push:
+        commands.append(_git("push", allow_failure=True, description="optional auto-push"))
+    commands.extend(
+        [
+            _git("branch", "-d", context.working_branch, allow_failure=True, description="delete merged dev branch"),
+            _git("stash", "pop", allow_failure=True, description="restore stashed tracked files"),
+        ]
+    )
+    return GitCommandPlan(
+        name="branch_merge",
+        commands=tuple(commands),
+        notes=(
+            "Tracked-only stash avoids capturing ignored state artifacts.",
+            "Rebase then fast-forward preserves merge invariant.",
+        ),
+    )
+
+
+def branch_save_wip_plan(context: BranchContext) -> GitCommandPlan:
+    """Plan shell-equivalent never-fail WIP preservation."""
+    return GitCommandPlan(
+        name="branch_save_wip",
+        commands=(
+            _git("rev-parse", "--abbrev-ref", "HEAD", allow_failure=True, description="verify current branch"),
+            _git("status", "--porcelain", allow_failure=True, description="detect uncommitted work"),
+            _git("add", "-A", "--", ".", *HIDDEN_TOOL_WORKTREE_EXCLUDES, allow_failure=True, description="stage non-ignored work excluding hidden tool worktrees"),
+            _git(
+                "commit",
+                "--no-verify",
+                "-m",
+                f"wip({context.working_branch}): interrupted — uncommitted work saved",
+                "-m",
+                "Pipeline was interrupted by signal. This commit preserves work-in-progress.",
+                "-m",
+                f"To resume: git checkout {context.working_branch}",
+                allow_failure=True,
+                description="create WIP commit",
+            ),
+        ),
+        never_fails=True,
+        notes=("Never-fail cleanup helper; errors are diagnostics only.",),
+    )
+
+
+def branch_ensure_return_plan(context: BranchContext) -> GitCommandPlan:
+    """Plan shell-equivalent guaranteed return cleanup."""
+    return GitCommandPlan(
+        name="branch_ensure_return",
+        commands=(
+            _git("rebase", "--abort", allow_failure=True, description="abort in-progress rebase"),
+            _git("rev-parse", "--abbrev-ref", "HEAD", allow_failure=True, description="detect current branch"),
+            _git("status", "--porcelain", "--", ".", *HIDDEN_TOOL_WORKTREE_EXCLUDES, allow_failure=True, description="detect WIP before checkout"),
+            _git("add", "-A", "--", ".", *HIDDEN_TOOL_WORKTREE_EXCLUDES, allow_failure=True, description="stage WIP before checkout"),
+            _git(
+                "commit",
+                "--no-verify",
+                "-m",
+                f"wip({context.working_branch}): interrupted — uncommitted work saved",
+                "-m",
+                "Pipeline was interrupted by signal. This commit preserves work-in-progress.",
+                "-m",
+                f"To resume: git checkout {context.working_branch}",
+                allow_failure=True,
+                description="save WIP before return when on dev branch",
+            ),
+            _git("stash", "push", "-m", "pipeline-ensure-return-stash", allow_failure=True, description="stash checkout blockers"),
+            _git("checkout", context.base_branch, allow_failure=True, description="return to original branch"),
+            _git("stash", "pop", allow_failure=True, description="restore stashed checkout blockers"),
+        ),
+        never_fails=True,
+        notes=("Always returns success to support trap/finally cleanup paths.",),
+    )
+
+
+def worktree_add_plan(context: BranchContext, policy: WorktreePolicy) -> GitCommandPlan:
+    """Plan worktree creation without recreating retired Windows runtime sources."""
+    root = policy.worktree_root or context.project_root.parent / f"{context.working_branch.replace('/', '-')}-worktree"
+    return GitCommandPlan(
+        name="worktree_add",
+        commands=(
+            _git("worktree", "add", str(root), context.working_branch, description="create git worktree"),
+        ),
+        notes=("Generic git worktree helper; no retired platform source trees are created.",),
+    )
+
+
+def current_branch(project_root: Path) -> str:
+    """Return current git branch name, or an empty string outside git."""
+    result = run_git_command(project_root, ("rev-parse", "--abbrev-ref", "HEAD"))
+    return result.stdout.strip() if result.return_code == 0 else ""
+
+
+def git_status_safe(project_root: Path) -> str:
+    """Return status while excluding hidden AI tool worktree directories."""
+    result = run_git_command(project_root, ("status", "--porcelain", "--", ".", *HIDDEN_TOOL_WORKTREE_EXCLUDES))
+    return result.stdout if result.return_code == 0 else ""
+
+
+def branch_save_wip(project_root: Path, working_branch: str) -> GitPlanResult:
+    """Execute shell-compatible WIP save only when currently on working_branch."""
+    context = BranchContext(base_branch="", working_branch=working_branch, project_root=project_root)
+    plan = branch_save_wip_plan(context)
+    if not working_branch or current_branch(project_root) != working_branch or not git_status_safe(project_root).strip():
+        return GitPlanResult(plan=plan, results=())
+    return run_git_plan(project_root, plan)
+
+
+def worktree_save_wip(runtime: WorktreeRuntimeContext) -> GitPlanResult:
+    """Preserve dirty linked-worktree changes on the task branch before removal."""
+    return branch_save_wip(runtime.worktree_path, runtime.context.working_branch)
+
+
+def branch_ensure_return(project_root: Path, base_branch: str, working_branch: str = "") -> GitPlanResult:
+    """Best-effort shell-compatible ensure-return helper that never reports failure."""
+    active = current_branch(project_root)
+    if working_branch and active == working_branch:
+        branch_save_wip(project_root, working_branch)
+    context = BranchContext(base_branch=base_branch, working_branch=working_branch or active, project_root=project_root)
+    return run_git_plan(project_root, branch_ensure_return_plan(context))
+
+def run_git_command(project_root: Path, args: Sequence[str]) -> GitCommandResult:
+    """Run one git command in a project root and capture output."""
+    completed = subprocess.run(
+        ["git", "-C", str(project_root), *map(str, args)],
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        text=True,
+        check=False,
+    )
+    return GitCommandResult(
+        args=tuple(map(str, args)),
+        return_code=completed.returncode,
+        stdout=completed.stdout,
+        stderr=completed.stderr,
+    )
+
+
+def run_git_plan(project_root: Path, plan: GitCommandPlan) -> GitPlanResult:
+    """Run a plan sequentially, stopping on non-allowed failures."""
+    results: list[GitCommandResult] = []
+    for command in plan.commands:
+        result = run_git_command(project_root, command.args)
+        results.append(result)
+        if result.return_code != 0 and not (command.allow_failure or plan.never_fails):
+            break
+    return GitPlanResult(plan=plan, results=tuple(results))
+
+
+@dataclass(frozen=True)
+class ResetBranchCleanupResult:
+    """Observed result for reset-time branch cleanup."""
+
+    branch: str
+    cleaned: bool
+    deleted: bool
+    returned_to: str
+    warnings: tuple[str, ...] = ()
+
+
+def default_branch(project_root: Path) -> str:
+    """Resolve the same main/master/default-branch fallback used by reset scripts."""
+    origin = run_git_command(project_root, ("symbolic-ref", "refs/remotes/origin/HEAD"))
+    if origin.return_code == 0 and origin.stdout.strip():
+        return origin.stdout.strip().removeprefix("refs/remotes/origin/")
+    if run_git_command(project_root, ("rev-parse", "--verify", "main")).return_code == 0:
+        return "main"
+    if run_git_command(project_root, ("rev-parse", "--verify", "master")).return_code == 0:
+        return "master"
+    return current_branch(project_root) or "main"
+
+
+def reset_branch_pattern(prefix: str, item_id: str) -> str:
+    """Return the reset helper branch glob for one item."""
+    return f"{prefix}/{item_id}-*"
+
+
+def list_reset_branches(project_root: Path, prefix: str, item_id: str) -> tuple[str, ...]:
+    """List dev branches that shell reset helpers would clean for an item."""
+    result = run_git_command(project_root, ("branch", "--list", reset_branch_pattern(prefix, item_id)))
+    if result.return_code != 0:
+        return ()
+    branches = []
+    for line in result.stdout.splitlines():
+        branch = line.strip().lstrip("* ").strip()
+        if branch:
+            branches.append(branch)
+    return tuple(branches)
+
+
+def reset_cleanup_branch(project_root: Path, branch: str, *, return_branch: str, delete: bool) -> ResetBranchCleanupResult:
+    """Discard uncommitted branch changes and optionally delete the branch.
+
+    This is intentionally reset-specific: unlike interrupted runner cleanup, manual
+    reset abandons uncommitted work on matching dev branches to recreate the
+    shell helper contract.
+    """
+    warnings: list[str] = []
+    active = current_branch(project_root)
+    restored = active
+    stashed = False
+
+    if active == branch:
+        run_git_command(project_root, ("reset", "HEAD"))
+        run_git_command(project_root, ("checkout", "--", "."))
+        run_git_command(project_root, ("clean", "-fd"))
+        checkout = run_git_command(project_root, ("checkout", return_branch))
+        if checkout.return_code != 0:
+            warnings.append(f"failed to checkout {return_branch}")
+            restored = branch
+        else:
+            restored = return_branch
+    else:
+        dirty = run_git_command(project_root, ("status", "--porcelain"))
+        if dirty.stdout.strip():
+            stash = run_git_command(project_root, ("stash", "push", "--include-untracked", "-m", "reset-pipeline-temp"))
+            stashed = stash.return_code == 0
+        checkout = run_git_command(project_root, ("checkout", branch))
+        if checkout.return_code == 0:
+            run_git_command(project_root, ("reset", "HEAD"))
+            run_git_command(project_root, ("checkout", "--", "."))
+            run_git_command(project_root, ("clean", "-fd"))
+            run_git_command(project_root, ("checkout", active or return_branch))
+            restored = active or return_branch
+        else:
+            warnings.append(f"could not checkout {branch} to discard changes")
+        if stashed:
+            run_git_command(project_root, ("stash", "pop"))
+
+    deleted = False
+    if delete:
+        deleted = run_git_command(project_root, ("branch", "-D", branch)).return_code == 0
+        if not deleted:
+            warnings.append(f"failed to delete branch {branch}")
+    return ResetBranchCleanupResult(branch=branch, cleaned=True, deleted=deleted, returned_to=restored, warnings=tuple(warnings))