fix(server): reticle_lease falls back to a connected tab when no managed browser launches

[Bhumika-1432006]

What & why

Several reporters on #691 hit a Chromium the pool could not launch — the binary missing, a shared-library dependency missing, a build-revision mismatch — and worked around it by hand: driving an already-open tab instead of the lease. That worked, and the issue names it directly as the third ask: "Fall back to the connected tab rather than failing outright when no managed browser can be launched."

It matters because a lease is what this daemon actively recommends when a human's tab is hidden or throttled. Refusing outright the moment the managed browser is unavailable strands the agent with no options, even when a driveable, connected session was sitting right there the whole time.

What changed

reticle_lease{action:"acquire"} in packages/server/src/tools/lease-tools.ts has two places it can currently fail before ever producing a lease:

1. The Chromium preflight (browserProbe) — throws "Chromium is not installed...".
2. pool.acquire() itself throwing — caught and rethrown as "could not open <url> — is the app running there?".

Both now check for a live, non-leased tab on the same project (liveTabFor, which already existed and backs the preferExisting advisory hint) before giving up. When one exists, it's handed back via a new noManagedBrowserFallback() helper instead of throwing — the response carries the existing session's id plus a new noManagedBrowser: { sessionId, reason } field explaining exactly why no managed browser was used.

This is explicitly not a lease — nothing was acquired from the pool, so reused/expiresInMs don't describe anything real. expiresInMs is now .optional() in the output schema (only in this fallback branch; every normal acquire still returns it), and its description says so. I checked for anything else relying on expiresInMs always being present — drive-attach.ts already treats it as optional (expiresInMs?: number), so this aligns with existing consumer code rather than introducing a new inconsistency.

Silent otherwise: with no live tab available, both paths throw the exact same clean errors they always did — nothing changes for the common case.

One structural change worth flagging: alreadyOpen (the live-tab lookup) is now sampled once at the top of the handler, before either failure point, rather than only after a successful acquire (where it previously only fed the advisory preferExisting hint). Same value, computed earlier so both failure branches can see it.

What I deliberately did NOT attempt

• The build-revision-mismatch messaging (issue's ask 0.6.10 - deterministic waiting, safe self-healing, token controls, domain understanding #2: "say which revision is wanted and which are present") — this needs matching an exact Playwright error string I could not confirm precisely from the (minified) bundled playwright-core, and getting it wrong would ship an unverified regex classifier.
• The two Windows-specific reports (playwright package reported missing despite being installed; doctor claiming Chromium missing after the requested version was installed) — these need a Windows repro I don't have reliable access to reproduce confidently.

Both are real, separate pieces of #691 and better left to someone who can verify them against an actual failure.

How it was verified

• Test-first: wrote the four new test cases against the not-yet-implemented fallback — confirmed RED (both fallback assertions failed with the original thrown errors).
• Implemented — all 34 tests in lease-tools.test.ts pass (30 pre-existing + 4 new): falls back when Chromium is absent and a tab is open; still throws the clean install error when Chromium is absent and no tab is open; falls back when the launch itself fails and a tab is open; still throws the clean nav error when the launch fails and no tab is open.
• tsc -b --force (typecheck) — clean.
• eslint on every changed file — clean.
• prettier --check on every changed file — clean.

Gates run

• pnpm lint && pnpm typecheck && pnpm test:unit (~2 min — always) — ran scoped to @reticlehq/server: 34/34 in lease-tools.test.ts, typecheck clean, lint clean, prettier clean.
• pnpm test:e2e (~8 min) — this touches the tool surface (reticle_lease's output shape gained a field), so this tier normally applies too. Flagging honestly: I could not run the full e2e battery in this environment (needs a real Chromium + booted fixture apps). The change is additive-only for the normal-acquire path (existing fields unchanged, new field only appears in the new fallback branch), so it shouldn't disturb existing e2e assertions on lease output, but this is worth a maintainer e2e run before merge.
• pnpm gate:install — not applicable, no install-path code touched.
• pnpm test:e2e:desktop — not applicable, no desktop code touched.

Checklist

• Every commit is signed off (git commit -s)
• Tests added/updated (RED → GREEN); the change is covered by a test that would fail without it
• No any, no free strings, no non-null !
• No console.log or internal tracking codes left in the diff
• Each changed file is under the 1000-line cap
• CHANGELOG.md updated under [Unreleased]
• Not security-affecting — this only changes which already-connected, already-authorized session gets returned when a managed launch isn't possible; no new trust boundary

Addresses the fallback ask of #691 (not closing it — the build-mismatch messaging and the Windows-specific reports stay open).

🤖 Generated with Claude Code

[divshekhar]

Closing this as a duplicate of #861, which covers the same ask of #691 and was opened 11 hours earlier — and the collision is partly my fault. When I closed your webpack PR I pointed you at "unclaimed work" without checking that #691's fallback ask already had a PR against it. That was careless of me and it cost you an evening.

Two things, because "duplicate" on its own would be unfair here.

Your envelope is the better one and I am going to ask for it. #861 signals the fallback with fellBackToExisting: true plus expiresInMs: 0 — a sentinel the caller has to know how to read. Yours carries noManagedBrowser: { sessionId, reason }, so the agent learns which of the three launch failures happened (binary missing, shared library missing, launch itself failed) rather than just that isolation was not available. That difference matters: the three have different fixes, and an agent that knows which one it hit can tell its human something actionable instead of "the lease did not work". I have asked #861's author to fold the reason in, crediting you.

Your PR description also states the severity better than theirs does — that a lease is what the daemon actively recommends when a tab is hidden or throttled, so refusing at exactly that moment strands the agent with no path forward. I have quoted that on #861.

You have now written three good PRs today and had two closed as duplicates. That is a bad ratio and it is a signal about our process, not your work: nothing in this repo made it discoverable that #680 and #691's fallback were already taken. I am fixing that by checking the open-PR list by symptom before pointing anyone at anything.

#870 is yours and it is live — rebased, approved, and merging on green. If you want another, say so and I will find you one that I have actually verified is unclaimed first.