Skip to content

fix(server): keep the lease marker across a server redirect (#1352) - #1381

Merged
divshekhar merged 8 commits into
reticlehq:mainfrom
drakeo338:claude/1352-fix
Oct 13, 2026
Merged

divshekhar merged 8 commits into
reticlehq:mainfrom
drakeo338:claude/1352-fix

Conversation

@drakeo338

@drakeo338 drakeo338 commented Oct 5, 2026 •

Copy link
Copy Markdown
Contributor

What & why

Closes #1352.

reticle_lease acquire on a URL the server redirects (/private -> /login) returned ready: false and a lease-... id naming no session: the redirect dropped ?__reticle_session=, so the SDK registered under its own id.

The pool now adds an init script (same addInitScript plumbing as storage-seed.ts) to the leased page. On every top-frame document at the lease's target origin that lacks the marker, it restores __reticle_session (and __reticle_project) with history.replaceState before app scripts run. The SDK then registers under the lease id exactly as without a redirect, and the existing resolveLeasedSessionId returns it with ready: true. No hint text changed, so this does not touch #1386.

Safety: an init script runs only in pages of the lease's own browser context. A person's tab at the same URL never carries the marker and is never adopted; nothing is matched by URL alone. The stamp skips child frames and other origins, so the lease id is not written into an identity provider's URL. Replaces the earlier unverified-candidate hint, pool.pageUrl and the unused pageUrl? parameter, all removed.

Verification

  • New lease-marker-stamp.test.ts: redirect that drops the marker resolves to the lease id; marker already present is untouched; other origin and child frame are not stamped; two concurrent leases do not cross; a person's same-URL tab is not adopted; the pool installs one stamp per lease with its own id and none without a marker.
  • One-off real Chromium run (not committed): 302 redirect, final URL and the page's location.search carry the marker.
  • With the pool hook removed (browser-pool.ts at upstream), the pool-wiring test fails; the other tests exercise the stamp module directly.
  • pnpm lint, tsc --noEmit (server), vitest for portal/pool, surface/tools/lease* and guards.

Changelog fragment .changes/1352-lease-keeps-marker-across-redirect.md describes this behaviour.

@drakeo338
drakeo338 requested a review from divshekhar as a code owner October 5, 2026 08:11
@github-actions

github-actions Bot commented Oct 5, 2026

Copy link
Copy Markdown

Thanks for your first pull request to Reticle! A maintainer aims to review within two days. Before then, pnpm verify locally catches most of what CI will, and CONTRIBUTING.md explains the rest. If CI does not start, a maintainer needs to approve it for first-time contributors; that is normal.

@github-actions github-actions Bot added area/server The daemon, MCP server and CLI: server/ area/docs Documentation and docs site labels Oct 5, 2026
@greptile-apps

greptile-apps Bot commented Oct 5, 2026 •

Copy link
Copy Markdown

RetriggerConfidence Score: 3/5

[Medium risk] Fixes lease session matching after server redirects.

This PR is not safe to merge until acquisition can establish that a URL-matched session belongs to the leased tab and the named-string requirement is met.

Findings

  1. P1 Security Lease can adopt another tab ▶
  2. P2 Diagnostic uses an inline string ▶

Summary

The PR adds a fallback for leases whose server redirect removes the session marker: it compares the leased page's URL with newly connected, unmarked sessions and returns the matched session ID.

  • Adds pooled-page URL reporting and redirect-matching tests.
  • The URL fallback cannot distinguish a leased tab from a person's tab that connects during acquisition.
Diagram
%%{init: {'theme': 'neutral'}}%%
flowchart TD
  A[Snapshot connected session IDs] --> B[Acquire and navigate leased page]
  B --> C[Another tab connects at landing URL]
  C --> D[Match sole new unmarked session by URL]
  D --> E[Return and alias that tab as the lease]
Loading

Reviews (1) · Last reviewed commit: "fix(server): do not adopt a tab that pre..."

Comment on lines +69 to +70
return all.filter(
(s) => s.url === pageUrl && sessionParamOf(s.url) === undefined && before?.has(s.id) !== true,

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 security Lease can adopt another tab. If a person opens the redirect destination after acquisition snapshots connected sessions but before the leased tab connects, their tab can be the only new, unmarked session at that URL. This match then reports the person's session as ready and aliases it to the lease, allowing the caller to drive the person's tab instead of the isolated tab. How this was verified: The resolver accepts any new unmarked session at the leased page's URL, while the pool checks URL collisions only against other leased pages.

// Several sessions on one URL cannot be told apart, so none is named: pointing at one would be
// the guess the resolver refuses to make.
if (pageUrl === undefined || only === undefined || 1 !== onPage.length) return '';
return `The lease id ${leaseId} names no session, but the leased tab is at ${pageUrl} and session ${only.id} connected there. Drive ${only.id}, not the lease id; release with the lease id. `;

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Diagnostic uses an inline string. This user-facing lease message is built as an inline template literal. The repository requires every domain, wire, or UI string to be a named constant; this requirement needs to be satisfied before merging.

Context Used: apps/examples/next/CLAUDE.md (source)

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

@drakeo338 drakeo338 changed the title fix(server): adopt the leased tab after a server redirect drops the session marker fix(server): name the connected session in the lease hint after a server redirect drops the marker Oct 5, 2026

@divshekhar divshekhar left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for taking a run at #1352. As it stands, though, this doesn't fix it. Acquire still returns ready:false and a lease-… id that names no session. The PR adds a hint that names an unverified candidate session and tells the agent to drive it "only if you know it is yours", which the agent has no way of knowing. Neither "Done when" item is met.

Two smaller problems:

  • The changelog fragment says the lease "now also adopts" the redirected session, but the code deliberately adopts nothing.
  • The pageUrl? parameter on acquireLeasedSession is unused.

The fix belongs at the cause. The pool already has addInitScript plumbing (storage-seed.ts), so the lease id can be stashed in the leased page in a way that survives a server redirect. Alternatively, read the SDK's session id from the leased page itself. Either way, return that session with ready:true. Your pool.pageUrl/page.url plumbing can be reused for that.

If you'd rather not take that on, I'll close this and leave #1352 open for someone else. Also, #1386 changes the same hint text, so whatever lands here should be rebased after it, and must not print the "no SDK / production" sentences when it names a connected session.

@drakeo338 drakeo338 changed the title fix(server): name the connected session in the lease hint after a server redirect drops the marker fix(server): keep the lease marker across a server redirect (#1352) Oct 5, 2026
@drakeo338

Copy link
Copy Markdown
Contributor Author

Reworked as you described in 346a6d7: the pool stamps the lease id into the leased page with an init script, so the lease comes back ready after a redirect.

@divshekhar divshekhar left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This rewrite fixes the cause, thanks. I checked it with the real BrowserPool and Playwright launcher, no mocks:

  • 302 /private → /login: the lease marker survives.
  • 302 /deep?keep=1 → /other/path: the lease marker survives.
  • An SSO round trip through another origin: the marker survives, and the identity provider's URL is not stamped.
  • Two concurrent leases on one origin: each keeps its own id.

On main, all of these arrive with no marker. Cross-lease confusion isn't possible, because the stamp fires only when the marker matches this lease's id.

The red package-quality check isn't your fault. Main is within about 2.4 KB of the server size budget, so we'll raise it on main. Two asks before merge:

  1. Restore the rationale on the stamp. 58bd3c0 and 11ff922 removed the comment explaining why the stamp is safe (top frame only, the lease's own origin, only when the marker matches). Please put it back. Don't trim to fit the budget.
  2. Add a real-browser test. The current tests use a fake window, and reverting browser-pool.ts alone leaves 6 of 7 green. A test using the real pool against a local server that answers with a 302 would pin the fix.

Follow-up, not needed here: a redirect to a different origin (apex → www) still returns an id that names no session. #1352's fallback, saying which session the tab connected under, isn't implemented. I'll file that separately.

@drakeo338

Copy link
Copy Markdown
Contributor Author

Pushed 8fc17dc with the stamp rationale restored and a real-browser test against a local 302 server that fails when the pool hook is removed.

@divshekhar divshekhar left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, this is close. The comment is back and accurate. I ran the new test in a clean clone: 3/3 pass on real Chromium, and when I removed the installLeaseMarker call from the pool all three failed. So the test does catch the bug.

One thing left: CI never runs that test. The unit-tests job doesn't install Chromium, so describe.skipIf(!available) skips all three (the log shows 3 skipped). As it stands, the guard can't fail in CI.

Fix: move the three cases into server/test/pool.integration.test.ts and drop the skipIf. That's where the real-Chromium BrowserPool tests already live, and CI runs them with Chromium installed (pnpm test:integration, in the first e2e shard). While you're there, put lease.release() in a finally. Right now a failed assertion leaks the lease, maxContexts runs out, and the next failure shows up as a 30s timeout instead of a readable error.

The red package-quality check isn't you. Main's server package is already within a couple of KB of the size budget. We've raised the budget on a branch that lands with 3.6.0, so you don't need to trim anything.

@divshekhar divshekhar left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks @drakeo338. The redirect cases now run in the real-Chromium integration suite, and I confirmed they fail when the pool hook is removed and pass with it. The only thing left is DCO: please git rebase --signoff origin/main and force-push. Then this is ready to merge. The cross-origin (apex to www) case is tracked separately, as discussed.

…marker

A lease finds its session by the __reticle_session marker in the session
URL. A server redirect drops the query string before the SDK loads, so the
tab connected under its own id and the lease returned an id naming no
session.

When the id and marker matches fail, resolveLeasedSessionId now takes the
one unmarked session whose URL equals the lease page's current URL. The
pool exposes that URL (PooledPage.url, BrowserPool.pageUrl). When nothing
matches, the not-ready hint names the id the tab connected under and the
URL.

Refs reticlehq#1352

Signed-off-by: drakeo338 <[email protected]>
…irect wiring

Snapshot the connected session ids before acquiring and never adopt one
of them by page URL, so a person's tab on the landing page is left alone.
Withhold the page URL while another live lease sits on it, name a session
in the hint only when exactly one is there, and drop the page-URL match
on the reuse path where no snapshot exists. Cover acquireLeasedSession
and reticle_lease acquire with a pool whose page lands on a redirect.

Signed-off-by: drakeo338 <[email protected]>
…ssion-match in the flat-directory list

An unmarked session at the lease URL cannot be told from a person's tab, so it is
no longer adopted; the hint names it as unverified. The file-count guard now
records surface/tools at 39.

Signed-off-by: drakeo338 <[email protected]>
…ng it in the leased page

Replaces the unverified-candidate hint: an init script puts __reticle_session back on the
document URL before the SDK reads it, so the SDK registers under the lease id and the
existing resolver returns it with ready:true. Refs reticlehq#1352.

Signed-off-by: drakeo338 <[email protected]>
…re the stamp's safety rationale

Signed-off-by: drakeo338 <[email protected]>
…ntegration suite

The unit-tests job installs no Chromium, so the skipIf block skipped all
three cases. Move them into test/pool.integration.test.ts, which CI runs
with Chromium, drop the skipIf, and release leases in a finally so a
failed assertion cannot exhaust maxContexts.

Signed-off-by: drakeo338 <[email protected]>
@drakeo338

Copy link
Copy Markdown
Contributor Author

Rebased onto main with DCO sign-off and force-pushed (45fa3ff).

@divshekhar
divshekhar enabled auto-merge October 13, 2026 03:55

@divshekhar divshekhar left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Every point is addressed. The init-script stamp keeps the marker across the redirect, and the Chromium integration test is the one that catches it. Nits for later: the "a person's tab is never adopted" unit test also passes without the fix, and the type name W in lease-marker-stamp.ts could say what it is.

@divshekhar
divshekhar added this pull request to the merge queue Oct 13, 2026
Merged via the queue into reticlehq:main with commit c0ee51f Oct 13, 2026
29 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area/docs Documentation and docs site area/server The daemon, MCP server and CLI: server/

Projects

None yet

Development

Successfully merging this pull request may close these issues.

A lease whose first page redirects on the server returns a session id that names nothing

2 participants