Say what a ticket switch is doing while it does it

[juanmaguitar]

Why

Switching tickets is a worktree scan and a full git.checkout. On a real wordpress-develop that is seconds, and the window says nothing for all of them.

Every other long operation here streams — installs, scripts, the dev server — so this was the one place where it is taking a while looked exactly like it has hung. The natural responses are clicking again, or force-quitting. And force-quitting part-way through a checkout is precisely what leaves the half-swapped worktree the mid-switch marker exists to recover from: the app was silently inviting the state it then has to rescue people from.

#185 turned switching into a link contributors actually click, so this stopped being theoretical.

What changes

The panel names each stage while it happens: saving your work on the ticket you are leaving, then swapping the files, then ready.

The park stages are the point, and they are entirely synthetic. statusMatrix reports nothing while it runs and is about a third of a switch — and it covers the stretch where the contributor's edits are committed nowhere. "Saving your work on #59234…" is the sentence that stops someone quitting there. git.checkout reports its own progress; the scan and the commit had to be given theirs.

Three decisions a reviewer would otherwise have to reverse-engineer, all measured first:

• Progress is additive. The handlers still await and return exactly as they did. The obvious alternative — return an id, stream, finish on a :done channel — would mean the renderer subscribes after the invoke answers, and the first event lands ~4ms in. The beginning of every switch would be lost. That ordering gap is already documented in test/preload-listeners.test.cjs.
• Events are throttled, one per stage change plus one per 100ms. A checkout of 1500 files called back 4395 times in 143ms; unthrottled that is not a channel, it is a flood. The rule that earns its keep is flushing whatever was held when the stage turns over — a line that stops at 87% and jumps to done reads as a hang, which is the failure this exists to prevent.
• The subscription lives in App, not SiteRow. Every row stays mounted (the parent hides inactive ones), so subscribing per row would open one listener per registered site and wake all of them for each other's events. App already owns this shape for setup logs.

The trunk update feeds its own log rather than this channel — one operation with two progress surfaces is how the two end up disagreeing.

Deliberately not in this PR: deleteTicketBranch also checks out and stays silent; it runs under a different busy flag, so covering it means a second progress surface for a rarely-used destructive action.

How to test this

Platforms: any, but the effect is proportional to the checkout, so a real wordpress-develop shows it and a toy repo will not. Stacked on #198.

Starting state: a site with two ticket branches that have work on them, sitting on one of them with uncommitted edits.

1. Click switch on the other ticket. → A spinner and a line appear under the panel. The first thing it says is that it is saving your work on # — by number, not ticket/59234.
2. Watch it through. → The line moves: saving → checking which files change → swapping files, with a percentage → gone. It never sits on one sentence for the whole switch, and never freezes partway and then jumps.
3. Switch on a site with no changes to park. → The line still appears for the checkout half.
4. Trigger a switch from the Attach to Trac card's Link ticket field instead. → The same line appears there.
5. Open a second site in the sidebar, then switch tickets on the first. → Nothing renders on the second site's panel.
6. Run Update to latest trunk on a site with a linked ticket. → Its terminal shows a handful of park/return stage lines among the update output — and the ticket panel shows nothing, because that flow owns its own log.

What must not have happened:

• No silent stretch. If any part of the switch shows no line, that is the bug — particularly the beginning, which is the part a :done-channel design would have lost.
• The line never freezes. A sentence that stops moving and is then replaced by the finished panel means a suppressed frame was dropped.
• No spinner on an idle panel. After the switch completes (or fails), the line is gone.
• The switch is no slower. The progress callback is on the checkout's critical path — if a switch takes noticeably longer than before, the throttle is not doing its job.

What could not be tested by hand: a checkout that dies part-way, which needs an EPERM from an editor or antivirus holding a file. Covered by a wiring test asserting the last held frame is still delivered.

Risks and limitations

Review outcome: 3 [fix here] · 2 [follow-up] — all 3 fixed. The first is worth naming here because it is the feature's whole point: the staging stage carried no from, so the sentence dropped to "Saving your work… 41%" for the bulk of the park — losing the ticket number for exactly the stretch where naming it is what stops a force-quit. The scan and commit either side read correctly, which is why it would have looked right in any screenshot.

• deleteTicketBranch stays silent (above).
• branches:switch streams to a channel no renderer reaches yet. Deliberate: the send-only channel is invisible to the IPC classification guard, so the day the switcher is wired to that door, silence would arrive with nothing failing.
• The percentage covers only part of the work. Analyzing workdir reports a count with no total, so that phase gets a sentence and no number rather than an invented one.
• When a site has no linked ticket and a patch exists, the line renders in both the ticket card and the destination card — two copies of the same true sentence. Cosmetic; noted rather than fixed because this component has no test coverage for its output.

Related

Closes #173. Stacked on #198 → #185 → #168, all part of #108's line of work.

---

Design decisions and alternatives considered

Why not nonBlocking/batchSize on the checkout? They yield to the event loop between batches, which sounds like it would help the events reach the renderer. Measured, they are not needed — the events already arrive spread across the whole checkout (first at 4ms of 143ms, last at 141ms). And they are not free: yielding widens the window in which the worktree is half-swapped, which is the state this issue is trying to make less likely.

Why our own stage vocabulary instead of passing isomorphic-git's phases through? Analyzing workdir is not a sentence for a contributor, and the park stages have no library phase at all. Mapping in one place means a version bump breaks a lookup, not the UI.

Why a shared src/switch-progress.cjs rather than main-side text? The throttle belongs to the sender and the sentence to the renderer, but they are two ends of one contract — payload shape and stage names. Keeping them in one dependency-free module means node --test pins both, and the trunk-update log reuses the throttle in a different mode rather than growing its own.

Review outcome (required — see AGENTS.md)

3 [fix here] · 2 [follow-up] — all 3 fixed. Judgement pass in a fresh context per the skill.

#	Dimension	What was wrong
1 🟡	Architecture	The staging stage omitted from, so the sentence lost the ticket number for the longest stretch of the park. Fixed at the one call site; now asserted on the rendered sentence, not on the payload fields — the fields were what let it through.
2 🟡	Architecture	A refused switch left its last frame in the map, so the discard-and-switch that follows a dirty-trunk refusal ran under a spinner describing the attempt that never happened.
3 🔵	Architecture	Every flush() was a bare statement after an await, so a switch that threw mid-checkout dropped what the throttle held — contradicting the module's own contract, and in the trunk update losing the last line of the stage that failed. Now in a finally, with a test that fails without it.

[follow-up]: deleteTicketBranch staying silent, and the line rendering twice when both link controls are on screen. Both in Risks.

The review also confirmed the parts most likely to be wrong and were not: the throttle's stage-change flush, emit returning no thenable (isomorphic-git awaits it), the stageWorktree filter being exactly equivalent to the guard it replaced, and the subscription being leak-free.

Implementation notes

Measured before designing, on 1500 files: statusMatrix 91ms · commit 14ms · checkout 143ms, and 4395 checkout callbacks — 3895 of them Analyzing workdir with no total. wordpress-develop is several times that.

test/preload-listeners.test.cjs gains the first coverage of the subscribe* family — one listener per subscribe, removal by handler rather than by channel, independent unsubscribes, payload without the Electron event, double-unsubscribe safe. Pinned for the whole family, not just the new member, because the leak shape (App subscribing once per app rather than once per run) is what makes removal-by-handler load-bearing.