[Add] A pull-request checkout module and the Git reads it needs (#458) - #459

## Why

The checkout module in #459 needs an IPC contract and a per-branch
record before the Apply panel can use it. Without the branch-aware
handler adjustments, updating trunk while trying a PR parks its work but
never returns to it: the return condition recognises only ticket
numbers.

## What changes

Adds preview, checkout and return handlers, with named preload methods
and correlated log/done events. The PR's recorded head is its base for
parking work; an interrupted checkout records the head immediately and
retries the same destination without fetching or parking partial files.
Status reports the PR, ticket lists omit PR branches, and submission
refuses a checked-out PR while ordinary backup export remains available.

The renderer is not connected yet. Trac attachments and local patch
files retain their existing apply/revert flow. This is the second part
of the stack, based on #459.

## How to test this

Platforms: any, current head. This adds no new clickable UI. From the
repository root, run:

```sh
node --test tests/unit/ipc-wiring.test.cjs tests/unit/preload-listeners.test.cjs tests/unit/pr-checkout-renderer.test.cjs
npm run test:electron
```

The wiring suite covers checkout and return, guard refusals,
partial-checkout recovery, deletion of the return ticket, preserved
ticket context, submission restrictions and backup export. The
trunk-return regression and the install decision when restoring parked
PR lockfile edits were both confirmed failing before their fixes.
Preload tests cover an immediate refusal arriving before invoke
resolves, listener cleanup and overlapping run correlation.

**What must not have happened:** a retry parks partial files; a return
drops the PR's recorded base; updating trunk leaves the site on trunk; a
PR author's commits are submitted as the contributor's work.

A real clone, slow blob download, Windows file locks and the visible
Apply journey are not exercised by this IPC layer. The renderer PR adds
the journey.

## Risks and limitations

- Preview fetches from the site's own origin; checkout fetches again, so
a preview is not a promise of an immutable remote head. Recovery instead
completes the already recorded destination.
- PR branches remain on disk. No deletion UI is introduced.
- The status field `hasEdits` describes a parked WIP commit; loose
worktree edits remain available through the existing change count for
the renderer to combine.
- Files and Trac attachments still use the applied-patch record. This
change does not resolve their attribution limitations.
- No UI changes in this PR; the next stack layer connects the new
methods.

## Related

Part of #458. Based on #459. The renderer layer completes #290.

---

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

Use the existing switch marker, Git child tracking and progress
formatter. A PR record is additive under the existing branches map;
store changes are computed inside changeSiteMeta. The original return
target is retained when a PR is applied again. Preload subscribes before
invoke and correlates early events once the id arrives, so a fast
validation refusal cannot leave the UI waiting.

</details>

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

0 [fix here] · 0 [follow-up]. No findings across the five dimensions.

- **Review:** completed by fresh Codex subagent `/root/review_pr_ipc`,
against base f44798a, including the six
functional files committed at the time as
15984c9. After #459 gained its Windows
assertion fix, `git range-diff` confirmed the rebased functional commit
e97fbe0de4601c17c314d435899793838e128e38 is equivalent.
- **Since review:** replaced a nested ternary in the reviewed lockfile
destination calculation with equivalent conditionals to satisfy lint,
then added the packaged-smoke API-key expectation in
ec96bfb. Both changes are mechanical
coverage updates; focused recovery, lockfile and packaged-smoke tests
passed.
- **Validation:** npm test: 1,396 passed, 2 skipped; Electron: 1,398
passed; final lint clean.
- **CodeRabbit:** not run: its check reports success, but its comment
says automatic reviews are disabled. The completed local review plus the
recorded equivalence and mechanical follow-up above cover the current
head ec96bfb.

</details>


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

Rebased onto the reviewed #459 fix as `7c706f3`. `git range-diff`
matched both original commits exactly, so this layer has no functional
delta; it only inherits the validated OID and Git-error handling below
it. CodeRabbit did not produce inline findings for this PR. **0
remaining [fix here] · 0 [follow-up].**

</details>

## 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>

…kets (#463)

## Why

Leaving a ticket with a PR applied and returning to it reopened the
ticket branch instead of the saved PR. A real older WordPress PR also
exposed 1,784 generated Gutenberg files as the contributor's changes,
and reviewing a large added file failed with `Maximum call stack size
exceeded` while the screen claimed there was nothing to send.

## What changes

Tickets remember their applied local PR across unlink, switching tickets
and app restart. **Revert this PR** clears that association and restores
the ticket work; edits on the PR stay with its local copy. Restoring a
PR pauses the watcher, installs dependencies only when the lockfile
changes, and rebuilds the site.

The single highlighted banner stays inside the ticket card, using **PR
#N is applied** and **Revert this PR**. Existing Apply wording and the
`.patch`/`.diff` mechanism remain. Other source actions are hidden while
a PR is applied. Ticket actions remain disabled, with a visible reason,
until applying or reverting and its rebuild finish.

Generated `/gutenberg/` files remain ignored when an older PR's
`.gitignore` is checked out. The review excludes generated additions
already parked by older app versions, while retaining changes to files
present in the original base. Updating `diff` from 5.2 to 8.0.4 fixes
large-file patch generation. Failed reviews show an error rather than an
empty-state claim, and PR reviews name the PR as their comparison base.

## How to test this

**Platforms:** macOS and Windows, on this PR's **current head**. The top
PR's code includes #459, #460 and #461. No signed Buildkite artifact has
been verified for this head yet.

From the repository root:

```sh
npm test
npm run test:electron
npm run test:e2e
```

`tests/e2e/journeys/pr-checkout.spec.js` covers apply → edit → unlink →
restart → relink → switch tickets → revert. It verifies that saved PR
edits and the original ticket edits return separately, that a restored
PR actually rebuilds its assets, and that an explicit revert stops
automatic PR restoration. Its regression cases were run red before the
fixes. The failed-review journey verifies that a read error cannot
become “nothing to send.” The IPC regressions cover untracked and
previously parked generated files, a 150,000-line text addition, and
conditional installation on PR restoration.

The existing patch journeys verify apply/revert and persistence for
`.patch` files. **What must not happen:** PR edits must not overwrite
ticket work; restoration must not replace the saved copy with a new
GitHub head; unchanged lockfiles must not trigger an install; generated
Gutenberg downloads must not appear as the contributor's work.

**Local macOS package:** built unsigned from `c71fbb7`, with all 15
packaged smoke tests passing. The packaged main process, renderer bundle
and ticket-action module match the current build byte-for-byte.

**Real-repository check performed on macOS:** an isolated local clone of
the reported `wordpress-develop` PR #8906, including the old WIP commit
with all 1,784 generated files, opens Review with zero contributor
changes and no exception. The original site was not modified.

**Remaining manual coverage:** a signed Windows build, live GitHub
fetching, long real dependency installs, OS file dialogs and real
build-watch processes. The automated journeys use a local Git remote and
small npm scripts; their passing result does not claim those external
checks.

## Risks and limitations

Generated files already stored in old WIP commits are not deleted or
rewritten; the review excludes additions under `/gutenberg/` absent from
the original base. The app retains local PR branches after reverting. PR
edits still cannot be submitted as a new contribution through this flow.
An already-unlinked ticket from an older app version has no saved
active-PR association; apply that PR again once.

The independent review found four issues in PR restoration and its
integration; all were fixed and re-reviewed. Review record below.

## Related

Stacked on #461 → #460 → #459. Part of #458. This PR preserves the
existing stack commits.

<details>
<summary>Review outcome</summary>

- **Review:** completed — independent Codex agent `review_final_stack`;
reviewed base/HEAD `a55df1e85595b8de6309371fbd83c987def0f081` plus the
complete pending diff. Four runtime findings fixed across re-review:
restored-PR build/install, missing new-ticket destination, cancellation
handler, and terminal ownership. One terminal test fixture correction
applied. Final outcome: **0 remaining [fix here] · 0 [follow-up]**.
- **Since review:** committed as `9b49879`; the commit contains the
reviewed pending work, including the final fixture correction and
screenshot, then `9b49879 → 6709d44` reviewed independently: only two
test fixtures changed to use explicit Git identity after Windows CI
exposed reliance on host configuration. No runtime changes in that
delta. The subsequent `6709d44 → c71fbb7` delta was reviewed
independently with zero findings: publish ticket-switch callbacks in a
layout effect and keep ticket actions blocked through the entire
PR/patch operation. The latter fixes a real Windows journey failure
where Unlink was clickable before Revert had finished; its new unit
regression was red before the fix and green afterward.

- **CodeRabbit:** completed a review of `9b49879` and raised one
actionable finding (callbacks assigned to a ref during render). Fixed in
`c71fbb7` with a layout effect and independently re-reviewed. Subsequent
green CodeRabbit statuses say **Review skipped**, so the independent
review is the review of record for the final head.

Validation on `c71fbb7`: Node 1,417 passed, 2 expected skips; Electron
1,419 passed; all 29 journeys passed in one run; 15 local packaged smoke
tests passed; lint clean. Final-head CI is green on macOS and Windows:
unit suites, all journeys and packaged smoke tests; lint and docs build
pass. [E2E
run](https://github.com/WordPress/contributor-toolkit/actions/runs/34770983332),
[unit
run](https://github.com/WordPress/contributor-toolkit/actions/runs/34770983301).
Pages deployment is intentionally skipped for a PR.

</details>

<details>
<summary>Screenshots</summary>

The banner and source controls are captured from the real Electron UI:

![Applied PR in its
ticket](https://raw.githubusercontent.com/WordPress/contributor-toolkit/juanmaguitar/pr-checkout-ticket-continuity/docs/public/screenshots/pr-applied.png)

![Apply
controls](https://raw.githubusercontent.com/WordPress/contributor-toolkit/juanmaguitar/pr-checkout-ticket-continuity/docs/public/screenshots/apply-patch-panel.png)

</details>


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

Rebased onto the reviewed lower stack as `c9e828f`. The CodeRabbit
finding on `ticketSwitchLifecycleRef` remains fixed in the commit phase,
and the same layout effect now publishes the corrected PR retry callback
inherited from #461. Validation on the final stack: focused
unit/integration suites 33/33; full Node suite 1,420 passed with 2
expected skips; targeted dirty-trunk journey 1/1; 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>