[Fix] Preserve applied PRs and review local changes when resuming tickets - #463

## Why

The Apply panel currently turns a GitHub pull request into an
unattributed diff on the active ticket branch. A first-time contributor
can test that code, but loses the author's commit history and cannot
safely tell the PR's work apart from edits made afterward. The checkout
primitives and IPC introduced by #459 and #460 need a contributor-facing
flow.

## What changes

Pull requests now preview their state and changed files, then check out
the fetched GitHub head as a local `pr/<number>` branch. Ticket or trunk
work is parked before the switch, edits made on top of the PR stay with
its local copy, and **Back to ticket #N** or **Back to trunk** restores
the previous work. If the remote PR moves while that local copy has
edits, the app offers **Return to saved copy** instead of overwriting
it.

The review screen attributes edits to the active PR and prevents
submitting the author's commits as the contributor's own work. Applying
a local or Trac `.patch`/`.diff` deliberately keeps the existing layer
model: it modifies the active branch and remains tracked through the
existing applied-patch state.

## How to test this

**Platform:** either macOS or Windows. Run against Buildkite's artifact
for current head `a55df1e85595b8de6309371fbd83c987def0f081`, once
available.

The layer-4 journey `tests/e2e/journeys/pr-checkout.spec.js` drives the
contributor path and is red without this change. From the repository
root, run:

```sh
npx playwright test --project=journeys tests/e2e/journeys/pr-checkout.spec.js
```

It verifies ticket → PR → local PR edits → ticket, returning to a saved
local copy after the upstream PR moves, and continuing into a PR
checkout after discarding loose trunk work. The existing patch journey
also remains green and verifies that `.patch` files still use the
applied-layer model:

```sh
npx playwright test --project=journeys tests/e2e/journeys/patch-apply.spec.js
```

**What must not have happened:** ticket work must not be lost or mixed
into `pr/<number>`; local PR edits must not be overwritten when the
upstream head moves; PR author commits must not become submit-able as
the contributor's work; applying a `.patch`/`.diff` must not change to
branch checkout semantics; `node_modules` must not be rebuilt unless
`package-lock.json` changed.

The journey uses a local Git remote and cannot exercise GitHub
availability, a real `wordpress-develop` clone, a long `npm install`, or
an OS path containing spaces. The draft's signed artifact will be used
for that manual pass.

## Risks and limitations

A `pr/<number>` branch is retained on disk after leaving it; there is no
deletion control in this change. Preview and checkout are separate
fetches, so the remote head can move between them; the checkout records
the head it actually fetched. A changed remote head plus local edits
intentionally returns to the saved copy until those edits are discarded.
Patch-file attribution and revert limitations remain those of the
existing patch-layer model.

The fresh self-review found four issues across two passes; all four were
fixed before this PR. The final pass found 0 [fix here] and 0
[follow-up].

## Related

The complete stack, including the refined Apply/Revert wording,
remembered applied PRs and review fixes, is available in #463. Use that
top branch to test the combined feature.

Fixes #458. Fixes #290. Stacked on #460, which is stacked on #459.

---

<details>
<summary>Design decisions and alternatives considered</summary>

The GitHub pull-request ref `refs/pull/<number>/head` is fetched into a
named local `pr/<number>` branch. A named branch avoids detached HEAD
and gives later contributor edits a stable home while preserving the PR
author's commits. Patch files do not identify a durable remote branch,
so `.patch` and `.diff` files continue to be applied to the active
branch and recorded as a reversible layer.

The UI says **Back to ticket #N** or **Back to trunk** because leaving a
PR restores the branch that was active before it; it does not run `git
revert` against the PR commits.

</details>

<details>
<summary>Review outcome (required — see AGENTS.md)</summary>

4 [fix here] · 0 [follow-up] — all 4 fixed. Final result: 0 [fix here] ·
0 [follow-up].

- **Review:** completed — fresh-context self-review against base
`ec96bfbab450debe3c23ac6b3f33e228e836d659` and the full working-tree
diff that became head `a55df1e85595b8de6309371fbd83c987def0f081`; the
initial pass found three issues: dirty-trunk continuation routed a PR
through ticket parsing, a moved upstream PR gave no path back to a
locally edited copy, and submission refusal always named a ticket. All
were fixed with regression coverage.
- **Re-review:** completed — found one low-severity placement issue when
a deleted return ticket redirected the active PR to trunk; fixed
tests-first by making explicit `pullRequest.returnTo` authoritative.
Final re-review found no findings across architecture, security,
performance, cross-platform behavior, or tests.
- **Since review:** the reviewed working tree was committed without
further source changes as `a55df1e85595b8de6309371fbd83c987def0f081`.
- **Validation:** `npm run lint`; `npm test` (1407 passed, 2 expected
Electron skips); `npm run test:electron` (1409 passed); `npx playwright
test --project=journeys` (25 passed); `npm run docs:build`; `git diff
--check`.

</details>

<details>
<summary>Implementation notes</summary>

The renderer calls the streaming preview, checkout, and leave APIs from
#460. The main process recognizes a moved PR whose local branch has
edits and switches back to that saved tip without fetching over it.
Documentation now uses “apply” for patch files and “check out” for pull
requests throughout the contributor flow.

</details>

<details>
<summary>Screenshots or recording</summary>

Pending capture from the signed Buildkite artifact for this draft's
current head. That artifact is also the first build that contains the
complete three-PR stack.

</details>



<details>
<summary>Stack review update (2026-09-14)</summary>

CodeRabbit raised four findings. Three were already addressed in
`a55df1e`; the remaining high-severity finding was valid: publishing
`retryPrSwitchRef.current` during render could expose a callback from a
discarded React render. A regression test failed before the fix, and
`068cd6b` now publishes the callback from `useLayoutEffect`. Validation:
full Node suite 1,410 passed with 2 expected skips, lint and `git diff
--check` clean. **0 remaining [fix here] · 0 [follow-up].**

</details>

The pull-request checkout stack (#459, #460, #461, #463) landed while this was
open. One conflict, in README.md: trunk rewrote the "try the work that already
exists" bullet, because a pull request is a checkout now rather than a patch
applied into the tree, and this branch had added a sentence to the bullet above
it. Trunk's wording kept, this branch's sentence kept.

Everything else merged without a conflict, and the seams that could have merged
cleanly and still broken were checked: the packaged smoke test's list of
contextBridge keys now carries both sides' additions, and the IPC coverage
guard classifies both sides' channels.

Verified on the merge: lint clean, 29 journeys, 15 packaged, and a wpct:// link
delivered against a build packaged from it. One unit test fails,
"the patch panel can render a large added text file without overflowing the
stack" — it fails on origin/trunk alone on this machine too, so it is a
baseline failure and not this branch's.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SNfwbKozBsY9ub5goLJyBm

## Why

`v1.1.0-beta.1` shipped on 12 September. Trunk carries five commits
since, and this is the **second beta for 1.1.0**, published so
contributors can keep testing before the stable tag. The headline is
checking out a pull request as a real branch, with the author's commits
intact, in place of the unattributed diff the Apply panel produced
(#459, #460, #461, #463, closing #290 and #458); it also gives the app
an address a browser can hand a ticket to, `wpct://ticket/<id>` (#465,
closing #464).

The version reaches two places a contributor sees, and both must carry
the real build: electron-builder embeds it in the artifact names
(`wordpress-contributor-toolkit-1.1.0-beta.2-*`), and `src/logging.js`
writes `app <version>` as the log's first line, so a problem report
names the build it came from. That is why the bump merges before the
tag.

## What changes

Only the version. All three package-version fields in `package.json` and
`package-lock.json` move together from `1.1.0-beta.1` to `1.1.0-beta.2`.
No dependency versions change, and there is no application behaviour
change in this PR.

## How to test this

Platforms: any for the suite; macOS or Windows for the artifact check
that follows the merge.

In the repository root:

1. `npm run lint` is clean and `npm test` passes.
2. `node -e "console.log(require('./package.json').version)"` prints
`1.1.0-beta.2`.
3. `python3 -c "import
json;d=json.load(open('package-lock.json'));print(d['version'],
d['packages']['']['version'])"` prints `1.1.0-beta.2 1.1.0-beta.2`.

**What must not have happened:** no dependency version may change. `git
diff trunk` shows exactly three changed lines, all of them the root
package version.

After merge, the release build must produce artifacts named
`wordpress-contributor-toolkit-1.1.0-beta.2-*`, and the first line of a
fresh app log must read `app 1.1.0-beta.2`.

## Risks and limitations

No UI change. The risk is a mis-scoped edit in `package-lock.json`,
where dependencies also carry `1.1.0-beta.1`; the replacement was
confined to the first 2000 bytes of the file, which holds the two root
entries, and both files were re-parsed as JSON afterwards.

## Related

Same shape as #397 (v1.0.1) and #457 (v1.1.0-beta.1).

---

<details>
<summary>Review outcome (required — see AGENTS.md)</summary>

Version-only change, three lines. Verified locally on this branch: `npm
run lint` clean, `npm test` 1451 pass, 0 fail, 2 expected skips; `git
diff --stat` shows two files, three insertions, three deletions; both
JSON files parse. Nothing to fix, nothing deferred.

</details>

<details>
<summary>Screenshots or recording</summary>

Nothing on screen changes.

</details>

🤖 Generated with [Claude Code](https://claude.com/claude-code)

https://claude.ai/code/session_0121dia1RzfskutrzA8iSK1K

Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>