feat(bootstrap): add createSessionLifter for renewable session lifts

[chrischall]

Closes #183.

The problem

bootstrap() returns a value, so consumers naturally capture a session once at process start and hand it to their client. That's the API's grain, not a consumer mistake — and it produces a bug that stays invisible until the site's credential lifetime is short enough to notice:

• The expiry dead end. A browser-backed account has no password, so when the captured credential lapses there's nothing to re-login with. The MCP is unauthenticated for the life of the process — while the browser held a live session the whole time.
• The sticky startup failure. A lift that failed at boot (user not signed in yet) gets cached just as permanently, so signing in afterwards changes nothing.

The audit in #183 found four MCPs carrying the one-shot capture (infinitecampus, groupon, setlist, canvas-parent) and four that had independently hand-rolled the renewable shape (ofw, resy, evite, zola). Four repos solving it and four not is the argument for putting it in the library.

The API

const lift = createSessionLifter({ serverName, version, domains, declare });
const manager = new CookieSessionManager({ login: lift, isExpired });

Construction is pure — no server, no listen(), no pair prompt — so it drops straight into whatever mints a session, and every expiry re-reads the browser.

Answering the design questions from #183

Keep bootstrap() or deprecate it? Kept, and reimplemented as one invocation of a lifter so the two cannot drift. It stays first-class because the tool-invoked capture pattern (vibo, honeybook: a capture_session tool the user runs on demand, which then persists the token) is legitimately one-shot.

Should the lifter own TTL/caching? No. Expiry semantics are app-specific — some sites need the lifted token exchanged before it's usable, others lapse on an idle timer the library can't observe. The caller's session manager owns when to re-lift; the lifter owns how.

A renew hook? Not needed — post-processing composes in userland:

const raw = createSessionLifter(opts);
const lift = async () => exchangeIfStale(await raw());

Adding a hook would bake app-specific auth into the bridge library for no expressiveness gain.

One thing not in the issue: concurrent calls are single-flighted, so two simultaneous expiries share one bridge round-trip rather than racing two open/close cycles for the same MCP. That's de-duplication, not caching — once a lift settles, the next call starts a fresh one.

Verification

1092 tests pass; typecheck clean. Beyond the stubs, verified against a live bridge:

constructed — bridge not touched yet
lift 1: cookies: accessToken,cfid,cftoken | missing: none
lift 2: cookies: accessToken,cfid,cftoken | same lifter, second bridge round-trip
concurrent lifts single-flighted: true

Follow-on

The four affected MCPs can migrate to this once it publishes. signupgenius-mcp and infinitecampus-mcp already have the renewable shape hand-rolled and will simplify onto it.

[claude]

Claude finished @chrischall's task in 2m 45s —— View job

---

Review: PR #191 — createSessionLifter

• Read CLAUDE.md conventions
• Read PR diff (origin/main...HEAD)
• Review packages/bootstrap/src/index.ts changes
• Review test coverage in packages/bootstrap/tests/bootstrap.test.ts
• Post findings / verdict

Note: npm test/npm run typecheck were not runnable in this sandbox (Bash execution required approval that wasn't available), so verification here is by careful reading rather than execution. The PR body reports 1092 tests passing and clean typecheck, plus a live-bridge smoke test.

What I checked closely

The single-flight mechanism in createSessionLifter (packages/bootstrap/src/index.ts:263-275) is the trickiest part of this change — it wraps runOneLift(opts).finally(...) and clears inFlight inside the finally callback. I traced the microtask ordering: because p = q.finally(fn), fn (which clears inFlight) runs and completes before p itself settles, so any code awaiting lift() sees inFlight === null by the time its continuation runs — matching the "a lift started from within a continuation is not deduped against the one that just settled" comment, and the "single-flights concurrent lifts" test. .finally fires on both success and rejection, so a failed lift correctly un-sticks the lifter for the next attempt (covered by the "surfaces a failed lift and stays usable" test). bootstrap() being reimplemented as runOneLift(opts) is a faithful behavior-preserving refactor, confirmed by the "bootstrap() is exactly one invocation of a lifter" test.

I didn't find any 🔴 Important issues — no bugs, no security/data-integrity concerns, and the change follows the documented @fetchproxy/bootstrap conventions (kept bootstrap() for one-shot capture-tool callers, no TTL/caching baked into the lifter, per the PR description's design rationale). Test coverage for the new function is thorough: construction purity, repeatability, fresh-state-per-call, failure recovery, single-flight, the disable-env-var path, and equivalence with bootstrap().

🟡 Nit (non-blocking)

• The file-level doc comment at the top of packages/bootstrap/src/index.ts (lines 1-17) still describes the module as a one-shot-only helper and doesn't mention createSessionLifter, even though it's now the recommended entry point whenever a session can expire. Left as an inline comment.

Verdict: warn

[claude]

🟡 Nit: now that createSessionLifter is the recommended entry point whenever a session can expire, the file-level doc comment at the top of this file (lines 1-17) is stale — it still frames the whole module as a "one-shot session-capture helper" and only describes bootstrap()'s lifecycle, with no mention of this function. Worth a short update so a reader skimming just the header doesn't get the superseded picture.

Fix this →

[github-actions]

🟡 Auto-review verdict: warn — The createSessionLifter implementation is correct — the single-flight/finally microtask ordering, error-recovery, and bootstrap() delegation all check out — and test coverage is thorough; only a stale file-level doc comment nit was found.
📋 Tracking follow-ups: #192