[nwparker]

	Files	Added	Deleted	Net
Test	4	$\color{#1a7f37}{\Huge{\mathbf{+}}}$​768	0	$\color{#1a7f37}{\Huge{\mathbf{+}}}$​768
Prod	4	$\color{#1a7f37}{\Huge{\mathbf{+}}}$​158	$\color{#cf222e}{\Huge{\mathbf{−}}}$​48	$\color{#1a7f37}{\Huge{\mathbf{+}}}$​110

Rewritten smaller (2026-09-17)

The first version reconciled four parallel signals for "which reconcile is current" — an integer authEpoch, a Promise compared by identity (latestReconcile), a deferred woken by wakeWaiters(), and RelayRetrySchedule.settled. The wait loop parked on promise identity while authority was an integer, and the two were reconciled by hand at each turnover site. Nothing structurally enforced "every turnover wakes the waiters"; it was a call you had to remember.

It is now one field, authority, and one mutator, turnover(). Ending the outgoing authority is what releases waiters, and it happens inside the same operation that installs the replacement — so a superseded wait is impossible rather than prevented. Object identity is the epoch, so isEpochCurrent becomes an identity check and the integer is gone.

Net effect of the rewrite: +124 / −210 against the previous version. Production across the whole PR is now +127/−84; the remainder is tests, which are the behavioural contract and were kept.

What fell out of the shape rather than being added

• A caller arriving after a fence gets the cause immediately. Previously the fence left latestReconcile pointing at the open it had just abandoned, so a waiter arriving afterwards parked behind that open until readContext's own 60s ceiling. The fence now installs an idle authority. New test.
• RelayRetrySchedule.settled is subsumed. A retry fires through beginReconcile, which turns the authority — the thing the waiter is already parked on. The armed deferred is deleted. cancel() still never resets the attempt counter.
• relay-live-broker-wait.ts and its six-closure LiveBrokerWaitSource seam are deleted. No test ever imported them; the seam existed to keep the coordinator under max-lines, which the smaller shape no longer needs.

Corrections to the earlier analysis

A previously-reported "fence hole" — the claim that fenceAndCloseNow left a woken waiter re-parking on the same fenced reconcile — was wrong, and is retracted. Measured on the old shape: the waiter did settle, because after the wake it fell through to armedRetry(), which the fence's retry.cancel() had nulled. Removing wakeWaiters() from the fence made it hang, which is what proved the wake load-bearing. No one-liner was applied and the header comment was accurate as written. What was missing was coverage, so the fence regression test written during that investigation is kept here.

Two independent design passes converged on the same shape and, separately, on the same missing test (post-fence arrival). That agreement is why the idle-authority case is pinned rather than assumed — worth stating, since a later reader cannot reconstruct it from the diff.

Dropped

The characterisation test pinning the transient-ref owner-scoping gap is deleted, not carried forward. Its own comment admitted the behaviour was a bug, and scoping the loop correctly would have failed exactly that one test — a test you must delete before you can fix a bug is worse than no test. The gap stays documented on hasDemand, in four lines rather than fourteen.

Explicitly still out of scope

The underlying churn — beginReconcile invalidating every in-flight open unconditionally, plus withTransientDemand calling refreshDemand() on both acquire and release of every RPC, so phones polling faster than an open completes can starve it — is not fixed here, deliberately. It is a behaviour change rather than a restructuring: relay-auth-coordinator.test.ts pins hard-restart semantics for same-identity re-reconciles, and adopting an in-flight open would invert that. It also needs a distinction the coordinator does not have (auth mutations must hard-restart; demand refreshes need not). Follow-up PR, roughly +40 prod / +60 test. This shape makes it a one-line choice in beginReconcile, because the wait keys on authority identity rather than on how many opens were started.

Mutation results (measured, not reasoned)

Mutation	Result
turnover() no longer ends the outgoing authority	10 tests fail
fence installs a running authority instead of idle	5 fail, incl. the new post-fence-arrival test
fold retry.reset() into turnover()	1 fails — the five-minute backoff-cap test
bound the arrived-on open with the budget	2 fail — wait-budget and slow-first-open

Suites: src/main/runtime/relay plus src/main/startup — 87 files / 752 passed, 8 skipped, 0 failures. pnpm tc exit 0. oxlint clean (coordinator under max-lines with the loop inlined). Changed-code quality gate passed, casting and SAFETY-rationale both 0 new.

Stacked on #19870 (fix/18211-lan-mode-applies-to-paired-devices). Review the seven commits above it.

Five relay-concurrency defects that lived only on un-PR'd integration branches. They were the relay half of nwparker/adv2-concurrency-fixes, which has no PR of its own and is not going to get one — so every one of these would have been lost when that branch was abandoned.

The live-broker wait (three fixes, one file)

waitForLiveBrokerResult is what every caller blocks on to get a broker. Three separate ways it failed to settle:

commit	defect
f8ab8f5c693	a newer reconcile takes the authority and the parked waiter is never woken — it waits for a reconcile that is no longer the current one
9070031ed13	stop() abandons the open the waiter is parked on, leaving the waiter on a promise nothing settles
0549bd19a65	a chain of superseding reconciles is unbounded — the pending !== latestReconcile arm re-enters the loop without re-checking the deadline, so the documented 20s budget is not enforced and the caller's transient demand ref is held past it

The third is not a hang — every iteration awaits a settling promise — so it is bounded by how long the churn lasts, which is exactly why it needed a bound rather than a fix.

Demand scoping

86781b85514 — nextPendingExpiry was not scoped the way hasDemand is. The two read the same ledger and disagreed about which devices count, so an expiry could be armed for demand that the other half did not consider live.

Interleaving coverage

e016ec1f27f — the existing mid-mint policy-flip test drove its steps in sequence, which cannot reach the interleaving the defect needs. This pins it under real interleaving.

Plus one documentation fix

78b274b55dd — lingerMs on the coordinator contract reads as a policy knob and is not one. The only production new RelayAuthCoordinator is in desktop-relay-service.ts and passes neither it nor random, so every shipped linger is the hardcoded ten-minute default. Labelled a test seam so the next person tunes the default, which is the only thing a user can feel.

Lifted from a dead-code/unread-field sweep (94ba0b9f052) stranded on an un-PR'd branch. The rest of that sweep is a protocol-reachability docstring and goes to #19861, not here.

Plus a correction this stack made necessary

61dd0e62b30 docs(relay): the live-broker wait budget does not bound the call.

LIVE_BROKER_WAIT_BUDGET_MS carried two claims. One is true and load-bearing — 20s bounds how long a waiter sits through armed retries. The other was false: "stays inside the phone's 30s request budget."

It cannot. The deadline is consulted only after the await, and a reconcile's own ceiling is readContext's cloud-refresh timeout (60s, plus one retry for a definitive 5xx) followed by the broker open. Measured: with a reconcile in flight, a wait at the default 20s budget had not settled at 45s.

Not academic — pairing.provisionRelay reaches this through requireActiveBroker, so it is phone-facing. The phone gives up and retries while the desktop still holds a transient demand ref for the call it abandoned.

Why it belongs in this PR specifically. f8ab8f5c693 extracts the wait into a new file, relay-live-broker-wait.ts — and carries both comments along verbatim. Without this commit, this stack moves a measurably false claim into a brand-new file, where it reads as freshly written and authoritative rather than as something inherited.

The same applies to the inner comment: "a reconcile always settles (opens carry HTTP deadlines)" is true, but the parenthetical names only the smaller of its two deadlines and omits readContext's, which dominates. "Settles" is not "settles soon", and reading it as the latter is how the 30s claim survived in the first place.

Behaviour unchanged. Bounding the reconcile would fail a slow-but-succeeding open — the worse trade, and what the adjacent comment already argues.

Carried from 6b029820cc9 on the un-PR'd nwparker/j4-skew-matrix. That commit targets relay-auth-coordinator.ts, where this code no longer lives after the extraction, so it does not apply as written; the corrections are ported to their new home. The mutation was re-run after the port rather than trusted: bounding the await with the deadline fails relay-auth-coordinator-wait-budget.test.ts, so the test still pins the property in its new location.

Not in here, deliberately

6bd997b2cca "fix(relay): clear the demand-expiry timeout on a fence, not only in stop()" shares this lineage and is superseded by #19963 — see that PR. Re-applying it would be a regression, not a duplicate.

Its near-twin fcea70fe3c6 (same subject, different content — the pair is not patch-identical, despite looking it) is worse than a duplicate here. Its one unique addition is a four-line comment documenting that the pending !== latestReconcile arm skips the deadline check — which is exactly the gap 0549bd19a65 fixes in this PR. Landing it would ship a comment describing a defect that no longer exists.

Base

main does not work as a base: f8ab8f5c693 conflicts there. The dependency is #19870's stack, onto which all six apply clean and in order. Merge order: #19870 → this.

Verification

tsc --noEmit -p config/tsconfig.node.json clean · src/main/runtime/relay + src/main/startup — 79 files / 683 tests passed, 2 files / 8 tests skipped, 0 failures, 0 infra errors · oxlint clean · oxfmt --check clean.

(src/main/startup/ensure-virtual-display.test.ts › reports failure when a stale socket blocks the Xvfb rebind is excluded — it is red on the untouched base, Xvfb on macOS.)

Rebase record (2026-09-11)

Stack preserved: base stays fix/18211-lan-mode-applies-to-paired-devices (#19870), rebased onto main at 5fa62feda7c264c6eda99ba4788ffebab9aae26c first. Replayed with git rebase --onto 13eee7eacf8a6fcd4bb77ff680d18f727fca1171 9ce190247edbdb508b452e8c62a63c4c2cdd0089.

	SHA
old head	61dd0e62b30f4700010f769bdedc7cdcd1e55a88
new head	80fcca2551252c95f4964378b4913ff18321913a
new base (#19870)	13eee7eacf8a6fcd4bb77ff680d18f727fca1171

No conflicts across all seven commits.

[pullfrog]

✅ No new issues found.

Reviewed changes

• Live-broker wait extraction — waitForLiveBrokerResult moves into relay-live-broker-wait.ts as runLiveBrokerWait, driven by a LiveBrokerWaitSource of re-read closures so every loop iteration sees current coordinator state.
• Authority-turnover wake — a new authorityChange resolver wakes waiters on every fresh reconcile and fence, so a waiter parked on a superseded open re-joins the newer reconcile instead of holding behind an open nobody will use.
• Stop/fence release — stop() and fenceAndCloseNow() now wake parked waiters, settling a waiter stranded on an abandoned open (previously a process-lifetime leak).
• Budget over superseding chains — the deadline is re-checked after a supersession (not only over armed retries), bounding a chain of superseding reconciles while still never cutting the initial open short.
• Demand-expiry scoping — nextPendingExpiry now shares demandCandidateBinding with hasDemand, excluding foreign-host, non-mobile, and policy-excluded devices from wake-timer arming.
• Documentation — lingerMs labelled a test seam (the only production construction passes neither it nor random); the budget comment corrected to stop claiming it bounds the call.
• Tests — three new test files covering interleaving, stop/fence settlement, churn-bounded budget, and demand-ledger lifecycle/scoping, all using an observe() helper that turns a leaked waiter into an assertion failure rather than a runner hang.

I traced the authorityChange wake/Promise.race logic against the reconcile/fence ordering (swap-then-resolve means a reader never sees a stale resolved promise; latestReconcile is updated before wakeWaiters), and verified the budget semantics against settledResult's live-broker re-read. Each bug-pinning test fails against the pre-fix implementation. The hasDemand refactor through demandCandidateBinding is behavior-preserving, and the nextPendingExpiry scoping change is correct (owner filtering is intentionally left to hasDemand; a foreign owner's expiry at worst causes a harmless spurious wake).

  ^{｜ View workflow run ｜ Using DeepSeek Pro (free via Pullfrog for OSS) ｜ 𝕏}

[pullfrog]

✅ No new issues found.

Reviewed changes

• Fence settlement test — adds one test pinning that fenceAndCloseNow() wakes a waiter parked on an open that never returns. It targets the direct fence callers (quit, sign-out) rather than stop(), so the wake stays in fenceAndCloseNow instead of migrating into stop() and silently leaking the direct path.

The rest of the PR is unchanged since the prior review (the 80fcca2 replay was a byte-identical rebase onto #19870). I confirmed the new test passes, that it fails if the wakeWaiters() call in fenceAndCloseNow is removed, and that oxfmt/oxlint are clean.

  ^{｜ View workflow run ｜ Using DeepSeek Flash (free via Pullfrog for OSS) ｜ 𝕏}

[pullfrog]

✅ No new issues found.

Reviewed changes

The delta since the prior pullfrog review is the single head commit e3dd6ae687, a refactor of the live-broker wait's authority model plus its test/comment fallout.

• One authority object — Replaced four parallel signals for "which reconcile is current" (the integer authEpoch, the latestReconcile promise, the authorityChange deferred, and RelayRetrySchedule.settled) with a single authority field mutated only through a new turnover(). Object identity is now the epoch, so isEpochCurrent(epoch) became isCurrent(authority).
• Wait parks on the authority — waitForLiveBrokerResult awaits the captured RelayAuthority (settled for completion/supersession, ended for an armed retry) and re-joins by identity, instead of the LiveBrokerWaitSource closure seam.
• Fence installs an idle authority — A caller arriving after fenceAndCloseNow() is now settled with the current cause rather than parking behind the open the fence abandoned; pinned by a new test.
• Extraction deleted — relay-live-broker-wait.ts and LiveBrokerWaitSource are gone; LIVE_BROKER_WAIT_BUDGET_MS moves to relay-auth-coordinator.ts.
• Retry schedule simplified — RelayRetrySchedule loses armed/settled (a firing retry now wakes waiters by turning over the authority); cancel() still does not reset the backoff ladder.
• Coverage trimmed — The transient-ref owner-scoping characterisation test is removed and the hasDemand KNOWN GAP comment compacted to four lines.

I traced the new state machine against every mutation site (stop, fenceAndCloseNow, beginReconcile, the retry timer callback, ensureLive, refreshAccessToken): turnover() is the only writer of authority and the only caller of RelayAuthority.end()/RelayRetrySchedule.cancel(), so any turnover that supersedes a parked authority resolves the exact promise the waiter holds — no lost wake, no spin past the deadline check, and no stale result. The retry-schedule suite dropped settled coverage in step with the API it removed, and the coordinator-level wake paths remain pinned in relay-concurrency-broker-wait.test.ts. Verified at head: full relay suite (32 files / 249 tests) passes, typecheck:node clean, check:code-quality:changed and check:max-lines-ratchet clean.

  ^{｜ View workflow run ｜ Using DeepSeek Flash (free via Pullfrog for OSS) ｜ 𝕏}