@henryqw/pi-pr 9.1.0 → 9.2.0

package/NOTICE.md

@@ -15,8 +15,8 @@ Each source path below is relative to that repository. Each package path is rela
 | --- | --- | --- |
 | `git-commit/SKILL.md` | `skills/git-commit/SKILL.md` | Modified for pi-pr: use the shared native scoped commit tool, content/index checks, and uncertain-outcome rules. |
 | `git-pr/SKILL.md` | `skills/git-pr/SKILL.md` | Modified for pi-pr: replace shell publication with bounded native dispatch, explicit base intent, upstream consent, and exact PR reuse. |
-| `update-from-main/SKILL.md` | `skills/update-from-main/SKILL.md` | Modified for pi-pr: packaged helper guidance, bounded check output, exact backup identity, and retained-backup recovery after success or failure. |
-| `update-from-main/scripts/update_from_main.py` | `skills/update-from-main/scripts/update_from_main.py` | Modified for pi-pr: add collision/race regressions, identify the backup by a unique reflog message, and apply its exact OID without popping or dropping it. |
+| `update-from-main/SKILL.md` | `skills/update-from-main/SKILL.md` | Modified for pi-pr: packaged helper guidance, bounded check output, exact backup identity, worktree ownership, and retained-backup recovery after success or failure. |
+| `update-from-main/scripts/update_from_main.py` | `skills/update-from-main/scripts/update_from_main.py` | Modified for pi-pr: add collision/race regressions, identify the backup by a unique reflog message, record its owner in per-worktree refs, and apply its exact OID without popping or dropping it. |
 | `update-from-main/scripts/validate.py` | `skills/update-from-main/scripts/validate.py` | Copied validator; added the source, licence, and modification notice header. |
 
 The source snapshot has no separate `NOTICE` file and no file-specific copyright notice in these five files. The full original Apache licence, including its appendix, is preserved unchanged. Attribution to the source author and repository is retained here. The unrelated source `agents/openai.yaml` files were not imported.

package/README.md

@@ -8,7 +8,7 @@ See the current branch pull request in the Pi footer. Run `/pr` for the full PR
 pi install npm:@henryqw/pi-pr
 ```
 
-Requires Pi 1.0.0 or newer, an authenticated GitHub CLI session (`gh auth login`) and a GitHub.com or GitHub Enterprise checkout. Verify authentication with `gh auth status`. CI repair requires a GitHub CLI whose `gh api --help` lists `--allow-escape-sequences`; upgrade `gh` if that flag is unavailable.
+Requires Pi 1.1.0 or newer in the 1.x series, an authenticated GitHub CLI session (`gh auth login`) and a GitHub.com or GitHub Enterprise checkout. Verify authentication with `gh auth status`. CI repair requires a GitHub CLI whose `gh api --help` lists `--allow-escape-sequences`; upgrade `gh` if that flag is unavailable.
 
 ## Works with
 
@@ -68,7 +68,9 @@ All commit callers use the same literal-path staging and commit parent/tree chec
 
 Ask to update the current branch from main. `update-from-main` runs its packaged Python helper once. It requires Python 3.9 or newer and Git with `fetch --porcelain`. Unlike the `/pr` base-update route, this helper **merges**, not rebases. It fetches before local mutation and uses the exact OID from fetch output. It backs up tracked and untracked changes; when ignored paths collide with the source tree, the backup also includes ignored files. It never pushes.
 
-Each backup has a unique Git reflog message, so another linked worktree's stash push cannot change its identity. Restoration always applies the captured OID with `--index`. The helper never pops or drops a stash. Backups stay retained after success as well as conflict, hook, or submodule failures. Report the backup OID and verify restored bytes and staging before explicitly removing it. Do not rerun while a backup remains. Restore from the emitted stash OID, not from a later `origin/main`, and keep the backup until the user verifies restoration and explicitly removes it. See the packaged `update-from-main` skill for recovery.
+Each backup has a unique Git reflog message, so another linked worktree's stash push cannot change its identity. Before it stashes, the helper records ownership in the per-worktree ref `refs/worktree/update-from-main/pending/<token>`, then replaces it with `refs/worktree/update-from-main/backup` at the captured OID. Restoration always applies the captured OID with `--index`. The helper never pops or drops a stash. Backups stay retained after success as well as conflict, hook, or submodule failures.
+
+A retained backup blocks further runs only in the worktree that owns it, also after a branch switch; other worktrees can update. Report the backup OID, and restore from it rather than from a later `origin/main`. After the user verifies restored bytes and staging and explicitly asks, complete recovery with `git update-ref -d refs/worktree/update-from-main/backup <oid>`. This keeps the stash entry. An interrupted run leaves the `pending` ref and blocks its worktree until recovery. Backups from earlier helper versions have no recorded owner and block every worktree until the user drops them or the confirmed owner adopts them; adoption keeps the stash entry. Removing a worktree removes its ownership refs but not its stash entries. See the packaged `update-from-main` skill for the exact recovery and adoption commands.
 
 ### Local acceptance checks
 

package/docs/git-workflows-tested.md

@@ -112,7 +112,7 @@ Main can give separate acceptance workers the source `extensions/pi-pr/extension
 
 ## Limits
 
-- Automated native tests use the workspace-pinned Pi `1.0.0` dependency. The installed `1.0.2` authority is `/Users/henry/.pi/agent/install/releases/1.0.2/node_modules/@earendil-works/pi-coding-agent`; its documentation and declarations were inspected, and its resource APIs were probed. Live model-driven use of the packaged tools and TUI behavior were not tested.
+- The automated native tests in this report used the workspace-pinned Pi `1.0.0` dependency of that time. The package now requires and pins Pi `1.1.0`; its test suite runs on that version. The installed `1.0.2` authority is `/Users/henry/.pi/agent/install/releases/1.0.2/node_modules/@earendil-works/pi-coding-agent`; its documentation and declarations were inspected, and its resource APIs were probed. Live model-driven use of the packaged tools and TUI behavior were not tested.
 - Controlled GitHub responses test authorization and command boundaries. They do not prove live GitHub authentication, repository policy, network transport, or GitHub Enterprise behavior.
 - A user request and upstream consent are agent guidance requirements; a Boolean tool field cannot prove that a person gave consent. Ownership, secret-content detection, check adequacy, and semantic conflict resolution still need agent/user judgment.
 - The acceptance entry is available for later local runs. Main's exact-candidate acceptance and root-wide checks are recorded above. Package typecheck passed on the revision; no new claim is made for unchanged packages' typechecks.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@henryqw/pi-pr",
-  "version": "9.1.0",
+  "version": "9.2.0",
   "description": "Run /pr to safely discover or link the current pull request, then create, update, address feedback, fix CI, or merge when ready.",
   "keywords": [
     "pi-package",
@@ -31,8 +31,8 @@
     "pack:check": "npm pack --dry-run"
   },
   "peerDependencies": {
-    "@earendil-works/pi-coding-agent": ">=1.0.0",
-    "@earendil-works/pi-tui": ">=1.0.0",
+    "@earendil-works/pi-coding-agent": ">=1.1.0",
+    "@earendil-works/pi-tui": ">=1.1.0",
     "typebox": "^1.3.15"
   },
   "dependencies": {
@@ -42,8 +42,8 @@
     "proper-lockfile": "^4.1.2"
   },
   "devDependencies": {
-    "@earendil-works/pi-coding-agent": "1.0.0",
-    "@earendil-works/pi-tui": "1.0.0",
+    "@earendil-works/pi-coding-agent": "1.1.0",
+    "@earendil-works/pi-tui": "1.1.0",
     "@types/proper-lockfile": "^4.1.4"
   },
   "repository": {

package/skills/update-from-main/SKILL.md

@@ -5,9 +5,9 @@ description: Safely sync attached non-`main` worktree branch with fetched `origi
 
 # update-from-main
 
-<!-- SPDX-License-Identifier: Apache-2.0. Derived from HenryQW/skills; modified for pi-pr exact backup identity and retained recovery. See ../../NOTICE.md for source identity and changes. -->
+<!-- SPDX-License-Identifier: Apache-2.0. Derived from HenryQW/skills; modified for pi-pr exact backup identity, worktree ownership, and retained recovery. See ../../NOTICE.md for source identity and changes. -->
 
-Run `python3 <skill>/scripts/update_from_main.py` once from the target worktree. Use this file's directory for `<skill>`. Requires Python 3.9 or newer and Git with `fetch --porcelain`. This is a standalone **merge**, not the `/pr` rebase route. The helper fetches before worktree mutation, backs up tracked/untracked state plus ignored paths when they collide, and merges the exact `main` OID captured from fetch output. It does not push or use GitHub. A retained update-from-main stash blocks a second run. The instructions below are the single recovery guide.
+Run `python3 <skill>/scripts/update_from_main.py` once from the target worktree. Use this file's directory for `<skill>`. Requires Python 3.9 or newer and Git with `fetch --porcelain`. This is a standalone **merge**, not the `/pr` rebase route. The helper fetches before worktree mutation, backs up tracked/untracked state plus ignored paths when they collide, and merges the exact `main` OID captured from fetch output. It does not push or use GitHub. Before it stashes, the helper records ownership in this worktree's per-worktree ref. A retained backup blocks another run in its own worktree, also after a branch switch, but not in other worktrees. The instructions below are the single recovery guide.
 
 ## Fast path
 
@@ -18,7 +18,7 @@ git status --short --branch
 git diff --check <emitted-before-sha> HEAD
 ```
 
-If `stash` is non-`none`, restoration used that exact OID and kept the backup. Report the OID even on success. A later run stays blocked until the user verifies staged, unstaged, untracked, and applicable ignored bytes, then explicitly removes this backup. Never pop or drop a mutable stash stack entry automatically.
+If `stash` is non-`none`, restoration used that exact OID and kept the backup. Report the OID even on success. A later run in this worktree stays blocked until the user verifies staged, unstaged, untracked, and applicable ignored bytes, then explicitly asks to [complete recovery](#complete-recovery). Never pop or drop a mutable stash stack entry automatically.
 
 Stop. No tests, install, history scan, push, extra commit, or helper rerun.
 
@@ -32,7 +32,47 @@ Emitted `main` SHA is authoritative for run. Do not rerun because `origin/main`
 - `status=stash_conflict`: resolve and stage every emitted conflict path; retain and report stash OID.
 - `status=stash_restore_failed`: retain and report stash OID. Inspect once with `git stash show --name-status --include-untracked <oid>`, restore clear changes, and ask user only when one upstream-path collision version must win. Never drop backup first.
 
-After manual recovery, keep the backup and report its OID. A later update stays blocked until the user verifies restoration and explicitly removes that backup. Do not drop it automatically. If execution stops without a complete result, inspect HEAD, Git operation state, and the stash before further action; do not rerun an uncertain mutation.
+After manual recovery, keep the backup and report its OID. A later update in this worktree stays blocked until the user verifies restoration and explicitly asks to complete recovery. Do not drop it automatically. If execution stops without a complete result, inspect HEAD, Git operation state, the stash, and `git for-each-ref refs/worktree/update-from-main/` before further action; do not rerun an uncertain mutation.
+
+### Complete recovery
+
+Only after the user verifies the restored bytes and explicitly asks, run in the owning worktree:
+
+```bash
+git update-ref -d refs/worktree/update-from-main/backup <oid>
+```
+
+This unblocks the worktree and keeps the stash entry. Drop that entry only on a separate explicit request, with no concurrent stash changes in any linked worktree. Re-find its `stash@{n}` by OID with `git stash list --format='%gd %H'` immediately before `git stash drop`; a concurrent push can change the selector and cause removal of another backup.
+
+### Interrupted run
+
+The helper error names `refs/worktree/update-from-main/pending/<token>` when a run stopped before it recorded its stash OID. Find this run's entry:
+
+```bash
+git stash list --format='%H %gs' | grep -F 'update-from-main owned <token>'
+```
+
+- One entry: record it, remove the pending ref, then restore its exact OID. If `apply` fails, continue as `stash_restore_failed`.
+
+  ```bash
+  git update-ref refs/worktree/update-from-main/backup <oid> ""
+  git update-ref -d refs/worktree/update-from-main/pending/<token>
+  git stash apply --index <oid>
+  ```
+
+- No entry: stop and retain the pending ref. Absence does not prove that Git left the worktree unchanged; another session can remove a shared stash entry. Inspect the stash reflog and local state. Only after the user verifies all expected staged, unstaged, untracked, and applicable ignored bytes and explicitly asks to complete recovery, run `git update-ref -d refs/worktree/update-from-main/pending/<token>`. If the expected state cannot be verified, keep the ref and ask the user.
+- More entries, or a `backup` ref is also present: stop and ask the user.
+
+### Legacy backup
+
+A stash entry with subject `update-from-main` or `update-from-main <uuid>` came from a helper without worktree ownership. It blocks every worktree until its owner adopts it or the user explicitly drops it. Ask the user to confirm the owner: the worktree that created it (the stash subject names its branch), or, if that worktree is gone, the worktree where they will verify recovery. In the owner worktree, run:
+
+```bash
+git update-ref refs/worktree/update-from-main/backup <oid> ""
+git update-ref refs/update-from-main/adopted/<oid> <oid> ""
+```
+
+The first command blocks the owner; the second unblocks other worktrees. Both keep the stash entry. Then verify or restore it with `git stash apply --index <oid>` as for `stash_restore_failed`, and complete recovery. Keep the shared `adopted` ref while the stash entry exists; delete it with `git update-ref -d refs/update-from-main/adopted/<oid> <oid>` only together with an explicitly requested drop of that entry.
 
 Start conflict triage with emitted JSON conflict path list, then inspect marker line numbers one separately quoted path at a time:
 

package/skills/update-from-main/scripts/update_from_main.py

@@ -1,6 +1,6 @@
 #!/usr/bin/env python3
 # SPDX-License-Identifier: Apache-2.0
-# Derived from HenryQW/skills; modified for exact backup identity, retention, and regressions.
+# Derived from HenryQW/skills; modified for exact backup identity, retention, worktree ownership, and regressions.
 # See ../../../NOTICE.md for the source snapshot and modification notices.
 """Update current non-main worktree branch from fetched origin/main."""
 
@@ -23,6 +23,14 @@ from unittest import mock
 MAIN_SOURCE_REF = "refs/heads/main"
 FETCHED_MAIN_REF = "refs/remotes/origin/main"
 MAIN_BRANCH_REF = "refs/heads/main"
+# Per-worktree refs record backup ownership; other worktrees cannot see them.
+OWNER_PREFIX = "refs/worktree/update-from-main/"
+BACKUP_REF = OWNER_PREFIX + "backup"
+PENDING_PREFIX = OWNER_PREFIX + "pending/"
+# Shared marker: an owner adopted this legacy backup in its worktree.
+ADOPTED_PREFIX = "refs/update-from-main/adopted/"
+# Stash subjects written before worktree ownership existed; they have no recorded owner.
+LEGACY_SUBJECT = re.compile(r": update-from-main(?: [0-9a-f-]{36})?$")
 IN_PROGRESS_PATHS = (
     "MERGE_HEAD",
     "CHERRY_PICK_HEAD",
@@ -37,10 +45,13 @@ class UpdateError(RuntimeError):
     pass
 
 
-def run(args: list[str], *, cwd: Path | None = None, check: bool = True) -> subprocess.CompletedProcess[str]:
+def run(
+    args: list[str], *, cwd: Path | None = None, check: bool = True, input: str | None = None
+) -> subprocess.CompletedProcess[str]:
     result = subprocess.run(
         ["git", *args],
         cwd=cwd,
+        input=input,
         text=True,
         stdout=subprocess.PIPE,
         stderr=subprocess.PIPE,
@@ -107,9 +118,17 @@ def require_ready_worktree() -> str:
     if unmerged_paths():
         raise UpdateError("worktree has unresolved conflicts")
     branch = current_branch_ref()
-    if any(re.search(r": update-from-main(?: [0-9a-f-]{36})?$", line)
-           for line in git(["stash", "list", "--format=%gs"]).splitlines()):
-        raise UpdateError("update-from-main backup remains retained; finish its recovery before another run")
+    owned = git(["for-each-ref", "--format=%(refname) %(objectname)", OWNER_PREFIX])
+    if owned:
+        raise UpdateError(
+            f"this worktree has unfinished update-from-main recovery: {'; '.join(owned.splitlines())}; "
+            "finish and complete it before another run"
+        )
+    adopted = set(git(["for-each-ref", "--format=%(objectname)", ADOPTED_PREFIX]).splitlines())
+    entries = (line.split("\0", 1) for line in git(["stash", "list", "--format=%H%x00%gs"]).splitlines())
+    legacy = [oid for oid, subject in entries if LEGACY_SUBJECT.search(subject) and oid not in adopted]
+    if legacy:
+        raise UpdateError(f"legacy update-from-main backup {legacy[0]} has no recorded owner; its owner must recover or adopt it")
     return branch
 
 
@@ -117,14 +136,23 @@ def stash_dirty_worktree(source_sha: str) -> str | None:
     ignored = ignored_source_paths(source_sha)
     if not status_lines() and not ignored:
         return None
-    message = f"update-from-main {uuid.uuid4()}"
+    token = str(uuid.uuid4())
+    message = f"update-from-main owned {token}"
+    pending = PENDING_PREFIX + token
+    # Record ownership before the stash can change the worktree.
+    run(["update-ref", pending, "HEAD", ""])
     mode = "--all" if ignored else "--include-untracked"
-    run(["stash", "push", mode, "--message", message])
+    pushed = run(["stash", "push", mode, "--message", message], check=False)
     # Linked worktrees share the stash stack. Find this run's entry, not its mutable tip.
     entries = git(["stash", "list", "--format=%H%x00%gs"]).splitlines()
     matches = [line.split("\0", 1)[0] for line in entries if line.endswith(f": {message}")]
+    detail = (pushed.stderr or pushed.stdout).strip()
     if len(matches) != 1:
-        raise UpdateError(f"could not identify backup with message {message}; inspect the stash reflog before retrying")
+        failure = f"{detail}; " if pushed.returncode else ""
+        raise UpdateError(f"{failure}could not identify backup with message {message}; {pending} blocks this worktree until recovery")
+    run(["update-ref", "--stdin"], input=f"create {BACKUP_REF} {matches[0]}\ndelete {pending}\n")
+    if pushed.returncode:
+        raise UpdateError(f"{detail}; stash backup retained at {matches[0]}")
     return matches[0]
 
 
@@ -379,8 +407,76 @@ def self_test() -> None:
         assert (repo / "main.txt").read_text(encoding="utf-8") == "main\n"
         assert "A  staged.txt" in test_git(repo, "status", "--porcelain=v1", "--untracked-files=all")
         assert (repo / "untracked.txt").read_text(encoding="utf-8") == "untracked\n"
-        assert update_in(repo)[0] == 1  # Even a restored backup needs explicit user removal.
-        assert test_git(repo, "rev-parse", "refs/stash") == stash_oid
+        peer = root / "clean-peer"
+        test_git(repo, "worktree", "add", "-b", "peer", os.fspath(peer), "HEAD")
+        (peer / "peer.txt").write_text("peer\n", encoding="utf-8")
+        result, output = update_in(peer)  # Another worktree's retained backup does not block this one.
+        assert result == 0, output
+        peer_oid = re.search(r"stash=([0-9a-f]+):retained", output).group(1)
+        assert peer_oid != stash_oid and test_git(peer, "rev-parse", BACKUP_REF) == peer_oid
+        assert (peer / "peer.txt").read_text(encoding="utf-8") == "peer\n"
+        assert test_git(repo, "rev-parse", BACKUP_REF) == stash_oid
+        assert update_in(repo)[0] == 1  # Even a restored backup needs explicit user completion.
+        test_git(repo, "checkout", "-b", "switched")
+        assert update_in(repo)[0] == 1  # Ownership follows the worktree, not its branch.
+        assert test_git(repo, "rev-parse", BACKUP_REF) == stash_oid
+
+        _seed, repo = setup_repo(root / "interrupted")
+        (repo / "shared.txt").write_text("staged\n", encoding="utf-8")
+        test_git(repo, "add", "shared.txt")
+        (repo / "shared.txt").write_text("unstaged\n", encoding="utf-8")
+        (repo / "local.txt").write_bytes(b"local\x00bytes\n")
+        real_run = run
+
+        def interrupt_after_push(args, **kwargs):
+            result = real_run(args, **kwargs)
+            if args[:2] == ["stash", "push"]:
+                raise KeyboardInterrupt
+            return result
+
+        with mock.patch(__name__ + ".run", side_effect=interrupt_after_push):
+            try:
+                update_in(repo)
+            except KeyboardInterrupt:
+                pass
+            else:
+                raise AssertionError("interruption did not propagate")
+        pending = test_git(repo, "for-each-ref", "--format=%(refname)", PENDING_PREFIX)
+        assert len(pending.splitlines()) == 1 and not (repo / "local.txt").exists()
+        assert update_in(repo)[0] == 1  # Uncaptured backup blocks until recovered.
+        assert test_git(repo, "for-each-ref", "--format=%(refname)", PENDING_PREFIX) == pending
+        token = pending.removeprefix(PENDING_PREFIX)
+        entries = test_git(repo, "stash", "list", "--format=%H %gs").splitlines()
+        (stash_oid,) = [line.split()[0] for line in entries if line.endswith(f": update-from-main owned {token}")]
+        test_git(repo, "update-ref", BACKUP_REF, stash_oid, "")
+        test_git(repo, "update-ref", "-d", pending)
+        test_git(repo, "stash", "apply", "--index", stash_oid)
+        assert test_git(repo, "show", ":shared.txt") == "staged"
+        assert (repo / "shared.txt").read_text(encoding="utf-8") == "unstaged\n"
+        assert (repo / "local.txt").read_bytes() == b"local\x00bytes\n"
+        assert update_in(repo)[0] == 1
+
+        _seed, repo = setup_repo(root / "stash-store-failure")
+        (repo / "shared.txt").write_text("staged\n", encoding="utf-8")
+        test_git(repo, "add", "shared.txt")
+        (repo / "shared.txt").write_text("unstaged\n", encoding="utf-8")
+        (repo / "local.txt").write_bytes(b"local\x00bytes\n")
+        before_status = test_git(repo, "status", "--porcelain=v1")
+        stash_lock = repo / ".git" / "refs" / "stash.lock"
+        stash_lock.touch()
+        try:
+            assert update_in(repo)[0] == 1
+        finally:
+            stash_lock.unlink()
+        assert test_git(repo, "status", "--porcelain=v1") == before_status
+        assert test_git(repo, "show", ":shared.txt") == "staged"
+        assert (repo / "shared.txt").read_text(encoding="utf-8") == "unstaged\n"
+        assert (repo / "local.txt").read_bytes() == b"local\x00bytes\n"
+        assert not test_git(repo, "stash", "list")
+        pending = test_git(repo, "for-each-ref", "--format=%(refname)", PENDING_PREFIX)
+        assert len(pending.splitlines()) == 1 and update_in(repo)[0] == 1
+        test_git(repo, "update-ref", "-d", pending)  # Explicit completion after byte/index verification.
+        assert update_in(repo)[0] == 0
 
         for phase in ("capture", "restore"):
             seed, repo = setup_repo(root / f"stash-race-{phase}")
@@ -421,11 +517,19 @@ def self_test() -> None:
             assert update_in(repo)[0] == 1
 
         _seed, repo = setup_repo(root / "legacy-backup")
-        (repo / "legacy.txt").write_text("legacy\n", encoding="utf-8")
-        test_git(repo, "stash", "push", "--include-untracked", "-m", "update-from-main")
+        owner = root / "legacy-owner"
+        test_git(repo, "worktree", "add", "-b", "owner", os.fspath(owner), "HEAD")
+        (owner / "legacy.txt").write_text("legacy\n", encoding="utf-8")
+        test_git(owner, "stash", "push", "--include-untracked", "-m", "update-from-main")
         legacy_oid = test_git(repo, "rev-parse", "refs/stash")
-        assert update_in(repo)[0] == 1
-        assert test_git(repo, "rev-parse", "refs/stash") == legacy_oid
+        assert update_in(repo)[0] == 1  # An unowned legacy backup blocks every worktree.
+        assert update_in(owner)[0] == 1
+        # Owner-confirmed adoption keeps the entry, blocks its owner, and unblocks other worktrees.
+        test_git(owner, "update-ref", BACKUP_REF, legacy_oid, "")
+        test_git(owner, "update-ref", ADOPTED_PREFIX + legacy_oid, legacy_oid, "")
+        assert update_in(repo)[0] == 0
+        assert update_in(owner)[0] == 1
+        assert test_git(repo, "stash", "list", "--format=%H %gs") == f"{legacy_oid} On owner: update-from-main"
 
         seed, repo = setup_repo(root / "conflict")
         commit(repo, "conflict.txt", "feature\n", "test: feature")
@@ -484,6 +588,12 @@ def self_test() -> None:
         assert (repo / "new.txt").read_text(encoding="utf-8") == "upstream\n"
         assert update_in(repo)[0] == 1
         assert test_git(repo, "rev-parse", "refs/stash") == stash_oid
+        assert test_git(repo, "rev-parse", BACKUP_REF) == stash_oid
+        # The user restores the chosen version, then explicitly completes recovery.
+        (repo / "new.txt").write_text(test_git(repo, "show", f"{stash_oid}^3:new.txt") + "\n", encoding="utf-8")
+        test_git(repo, "update-ref", "-d", BACKUP_REF, stash_oid)
+        result, output = update_in(repo)
+        assert result == 0 and (repo / "new.txt").read_text(encoding="utf-8") == "local\n", output
 
         seed, repo = setup_repo(root / "fetch-failure")
         (repo / "shared.txt").write_text("staged\n", encoding="utf-8")
@@ -567,6 +677,7 @@ def self_test() -> None:
         assert (repo / "ordinary.txt").read_text(encoding="utf-8") == "ordinary\n"
         assert (repo / "sub" / "child.txt").read_text(encoding="utf-8") == "dirty\n"
         assert test_git(repo, "stash", "list")  # Error-path restoration also retains its backup.
+        assert test_git(repo, "rev-parse", BACKUP_REF) == test_git(repo, "rev-parse", "refs/stash")
 
         seed, repo = setup_repo(root / "submodule-update")
         child = root / "submodule-update-child"