@clien-ai/mcp 0.1.0

package/README.md

@@ -0,0 +1,221 @@
+# @clien-ai/mcp
+
+Run a full Clien.ai product-research pass from Claude Code. One tool —
+`clien_research` — that takes an idea, runs a 15-25 minute deep research pass
+on our sandbox, and hands you back a markdown report plus structured
+`report_data` (hypotheses, competitors, key findings).
+
+---
+
+## Quick start
+
+```bash
+npx @clien-ai/mcp install
+```
+
+Restart Claude Code, then ask:
+
+> run a deep research pass on my product idea
+
+The first call opens your browser for a one-time OAuth login. The refresh
+token is stored in your OS keyring (or an encrypted file if the keyring is
+unavailable). Subsequent calls reuse it silently.
+
+---
+
+## Manual install
+
+If you prefer to edit Claude Code's config yourself, add this to
+`~/.claude.json`:
+
+```json
+{
+  "mcpServers": {
+    "clien": {
+      "command": "npx",
+      "args": ["-y", "@clien-ai/mcp"]
+    }
+  }
+}
+```
+
+Restart Claude Code. First call triggers OAuth.
+
+---
+
+## What the tool returns
+
+```jsonc
+{
+  "content": [{ "type": "text", "text": "<full markdown report>" }],
+  "_meta": {
+    "job_id": "...",
+    "status": "complete",
+    "report_data": {
+      "hypotheses": [...],
+      "competitors": [...],
+      "key_findings": [...],
+      // ...the full structured report
+    }
+  }
+}
+```
+
+The markdown is what a human reads. The structured `report_data` is what you
+pass back to Claude Code when you want it to reason about the research
+further — "find the strongest competitor", "draft a positioning doc against
+the top 3 threats", etc.
+
+---
+
+## Inputs
+
+| Field          | Type                     | Required | Default | Notes                                                                                            |
+|----------------|--------------------------|----------|---------|--------------------------------------------------------------------------------------------------|
+| `idea`         | string (1-10,000 chars)  | yes      |         | The idea, hypothesis, or question                                                                |
+| `depth`        | `"quick"` \| `"deep"`    | no       | `deep`  | `quick` caps cost; `deep` is the full 15-25 min pass                                             |
+| `project_id`   | UUID                     | no       |         | Existing Clien.ai project to attach the run to (returned in `_meta.project_id` from prior runs)  |
+| `project_name` | string (1-100 chars)     | no       |         | Name for a new project. Supply when `project_id` is not set so the report is discoverable in the web UI. Ignored when `project_id` is also provided. |
+
+## Outputs
+
+The tool returns markdown content plus `_meta`:
+
+| `_meta` field      | Type            | Notes                                                                               |
+|--------------------|-----------------|-------------------------------------------------------------------------------------|
+| `job_id`           | UUID            | The validation job's ID                                                             |
+| `status`           | string          | Terminal status: `complete`, `failed`, or `cancelled`                               |
+| `project_id`       | UUID \| `null`  | The project this run is attached to. Pass back as `project_id` on follow-up runs.  |
+| `report_data`      | object \| `null`| Structured report (hypotheses, competitors, key findings)                           |
+| `total_cost_cents` | number          | Optional. Total cost of the run, in cents.                                          |
+
+---
+
+## Progress
+
+The MCP emits `notifications/progress` events every ~5 seconds during the
+run. Claude Code keeps the tool call alive as long as progress flows
+(verified in our Unit 0 spike with a 25-minute run).
+
+---
+
+## Troubleshooting
+
+| Symptom                                                    | Likely cause                                       | Fix                                                                                                            |
+|------------------------------------------------------------|----------------------------------------------------|----------------------------------------------------------------------------------------------------------------|
+| "Session expired during research"                          | Access + refresh both expired                      | Run `clien_research` again — triggers re-consent in browser                                                    |
+| "Insufficient credits ..."                                 | Credit balance at 0                                | Buy a pack at <https://clien.ai/app/billing>                                                                   |
+| "All OAuth redirect ports [7873, 7874, 7875] are in use"   | Another app is on all three loopback ports         | Free one port and retry                                                                                        |
+| "keytar not available" note in logs                        | libsecret missing (WSL, headless Linux)            | Falls back to AES-256-GCM encrypted file at `~/.clien-ai/tokens.json.enc` — OK but weaker than the OS keyring  |
+| Browser never opens                                        | Headless environment / container                   | See the **Devcontainer / remote SSH** section below                                                            |
+| `tokens.json.enc` corrupt after a copy to a different host | Machine-id changed; encrypted file can't decrypt   | Run `clien_research` — triggers new OAuth, overwrites the file                                                 |
+
+### Reset authentication
+
+```bash
+# Drops the stored refresh token. Next tool call opens OAuth again.
+npx @clien-ai/mcp logout
+
+# --json for agent-pipeable output
+npx @clien-ai/mcp logout --json
+# {"ok":true,"hadTokenIn":"file"}
+```
+
+### Check current state
+
+```bash
+# Snapshot of credentials state without triggering OAuth.
+npx @clien-ai/mcp status
+
+#   @clien-ai/mcp v0.1.0
+#
+#   Backend:        file
+#   Has token:      yes
+#   Last refreshed: 2026-04-27T14:32:18.421Z (3h ago)
+
+# --json for agents
+npx @clien-ai/mcp status --json
+```
+
+### Headless / CI authentication
+
+For non-interactive environments (devcontainers, CI runners, remote SSH), the
+loopback OAuth flow can't open a browser. Two ways to authenticate without a
+TTY:
+
+```bash
+# 1) Pre-seed via env var (skips OAuth entirely on first call):
+export CLIEN_MCP_REFRESH_TOKEN=<refresh_token_from_a_prior_browser_run>
+npx @clien-ai/mcp
+
+# 2) Or persist the seed once with the authorize subcommand:
+npx @clien-ai/mcp authorize --token <refresh_token>
+```
+
+If neither is set in a non-TTY context (CI / devcontainer / SSH session
+without a browser), the OAuth flow opens a loopback server and waits up to
+5 minutes for the callback. After that timeout it surfaces `oauth_timeout`
+with the authorize URL — re-run after seeding the env var or the
+`authorize` subcommand. (The MCP intentionally does NOT short-circuit on
+non-TTY because Claude Code launches the server over stdio, which is also
+non-TTY but is the primary production path.)
+
+---
+
+## Devcontainer / remote SSH / Docker
+
+**Run the MCP on your local machine, not inside a container or a remote
+shell.** The OAuth handshake opens a browser on `http://localhost:787x/callback`,
+which won't reach a containerized or remote process. Claude Code already
+runs locally; the MCP subprocess it spawns runs locally too by default.
+
+If you develop inside a devcontainer and want to use Clien.ai, install and
+configure the MCP in your host's Claude Code, not the one inside the
+container.
+
+---
+
+## Env overrides (for development)
+
+| Variable                    | Purpose                                            |
+|-----------------------------|----------------------------------------------------|
+| `CLIEN_MCP_ENV=test`        | Use the test Supabase project + test client id    |
+| `CLIEN_MCP_SERVER_URL`      | Override the Clien.ai HTTP base URL                |
+| `CLIEN_MCP_SUPABASE_URL`    | Override the Supabase auth base URL                |
+| `CLIEN_MCP_CLIENT_ID`       | Override the OAuth client id                       |
+| `CLIEN_MCP_POLL_INTERVAL_MS`| Change events poll cadence (default 5000 ms)       |
+
+---
+
+## Privacy
+
+Credentials never leave your machine. The refresh token is stored either in
+your OS keyring (macOS Keychain, Windows Credential Manager, Linux libsecret)
+or in an AES-256-GCM encrypted file keyed to your host. Clien.ai sees only
+the bearer token on each API call — the same token your browser would send
+from the web app.
+
+---
+
+## CLI exit codes
+
+The CLI uses stable, documented exit codes so scripts and agents can branch on
+failure class without parsing message strings.
+
+| Code | Meaning |
+|------|---------|
+| 0 | success |
+| 1 | generic / uncategorized error |
+| 2 | authentication failed (`OAuthError`, refresh-token revoked, no-TTY without env seed) |
+| 3 | filesystem operation failed (EACCES, ENOENT, ENOTDIR, ENOSPC, EROFS, ...) |
+| 4 | network operation failed (AbortError, TimeoutError, fetch failed) |
+| 5 | invalid arguments / unknown flag |
+
+Pass `--debug` to any command to surface stack traces alongside the
+human-readable error message.
+
+---
+
+## License
+
+UNLICENSED — do not redistribute. Contact Clien.ai for commercial licensing.

package/dist/auth/oauth.js

@@ -0,0 +1,468 @@
+/**
+ * OAuth 2.1 PKCE client for the Clien.ai Supabase authorization server.
+ *
+ * Two paths:
+ *   1. refreshAccessToken(refresh) - bounce a stored refresh token for a new
+ *      access token. Supabase rotates refresh tokens; we persist whatever the
+ *      server returns.
+ *   2. runAuthorizationCodeFlow(config, openBrowser) - full PKCE dance:
+ *        - bind loopback port (7873 then 7874 then 7875)
+ *        - open the browser to /auth/v1/oauth/authorize with code_challenge + state
+ *        - wait for the callback, verify state matches
+ *        - exchange code at /auth/v1/oauth/token for {access, refresh}
+ *
+ * The `openBrowser` callback is injected so tests can stub it out.
+ */
+import { createServer, } from 'node:http';
+import { URL, URLSearchParams } from 'node:url';
+import { z } from 'zod';
+import { generatePkcePair, generateState, } from './pkce.js';
+// 30 seconds. Token endpoint should respond within a few hundred ms; longer
+// means hung. Single bound covers both the network-issue case (#173) and the
+// TypeError-preservation case (#165) — AbortError flows through the same
+// catch path as connection-refused / DNS-down.
+const TOKEN_FETCH_TIMEOUT_MS = 30_000;
+// ------------------------------------------------------------------
+// Types
+// ------------------------------------------------------------------
+// Runtime schema for the token endpoint's success response. Replaces the
+// previous `as TokenResponse` cast so a malformed body fails loudly at the
+// boundary instead of returning `undefined` further down the stack.
+//
+// `TokenResponse` is derived directly from the schema so the runtime
+// validator and the static type cannot drift. Adding a field requires
+// touching one place.
+const TokenResponseSchema = z.object({
+    access_token: z.string().min(1),
+    refresh_token: z.string().min(1),
+    expires_in: z.number().int().nonnegative().optional().default(3600),
+    token_type: z.string().optional().default('Bearer'),
+    scope: z.string().optional(),
+});
+export class OAuthError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'OAuthError';
+    }
+}
+// ------------------------------------------------------------------
+// Token endpoint
+// ------------------------------------------------------------------
+function tokenEndpoint(config) {
+    return `${config.supabaseUrl}/auth/v1/oauth/token?grant_type=authorization_code`;
+}
+function refreshEndpoint(config) {
+    return `${config.supabaseUrl}/auth/v1/oauth/token?grant_type=refresh_token`;
+}
+function authorizeEndpoint(config, redirectUri, challenge, state) {
+    const url = new URL(`${config.supabaseUrl}/auth/v1/oauth/authorize`);
+    url.searchParams.set('response_type', 'code');
+    url.searchParams.set('client_id', config.clientId);
+    url.searchParams.set('redirect_uri', redirectUri);
+    url.searchParams.set('code_challenge', challenge);
+    url.searchParams.set('code_challenge_method', 'S256');
+    url.searchParams.set('scope', config.scope);
+    url.searchParams.set('state', state);
+    return url.toString();
+}
+async function postForm(url, body) {
+    const params = new URLSearchParams(body);
+    // Wrap fetch in try/catch so raw network failures (DNS down, connection
+    // refused, TLS error) and AbortError (timeout) become typed OAuthErrors
+    // with code `oauth_network_error`. The previous code let TypeError leak
+    // out, which bypassed `ensureSession`'s guard and forced re-consent.
+    // See issue #165.
+    let response;
+    try {
+        response = await fetch(url, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/x-www-form-urlencoded',
+                Accept: 'application/json',
+            },
+            body: params.toString(),
+            signal: AbortSignal.timeout(TOKEN_FETCH_TIMEOUT_MS),
+        });
+    }
+    catch (err) {
+        if (err instanceof OAuthError)
+            throw err;
+        const e = err;
+        const reason = e.name === 'AbortError' || e.name === 'TimeoutError'
+            ? `Token request timed out after ${TOKEN_FETCH_TIMEOUT_MS / 1000}s`
+            : (e.message ?? 'Token request failed before reaching the server');
+        throw new OAuthError('oauth_network_error', reason);
+    }
+    if (!response.ok) {
+        const text = await response.text().catch(() => '');
+        let code = `oauth_${response.status}`;
+        try {
+            const parsed = JSON.parse(text);
+            if (parsed.error)
+                code = parsed.error;
+            throw new OAuthError(code, parsed.error_description ?? parsed.error ?? text);
+        }
+        catch (err) {
+            if (err instanceof OAuthError)
+                throw err;
+            throw new OAuthError(code, `Token request failed: ${response.status} ${text}`);
+        }
+    }
+    const raw = await response.json().catch(() => null);
+    const parsed = TokenResponseSchema.safeParse(raw);
+    if (!parsed.success) {
+        throw new OAuthError('oauth_invalid_response', `Token response failed schema validation: ${parsed.error.issues
+            .map((i) => `${i.path.join('.') || 'root'}: ${i.message}`)
+            .join('; ')}`);
+    }
+    return parsed.data;
+}
+function toTokenSet(raw) {
+    const expiresInMs = Math.max(0, (raw.expires_in ?? 3600) * 1000);
+    // Apply 60s skew so we refresh a touch early.
+    return {
+        accessToken: raw.access_token,
+        refreshToken: raw.refresh_token,
+        expiresAt: Date.now() + Math.max(0, expiresInMs - 60_000),
+        tokenType: raw.token_type ?? 'Bearer',
+    };
+}
+/** Refresh an access token using a stored refresh token. */
+export async function refreshAccessToken(config, refreshToken) {
+    const raw = await postForm(refreshEndpoint(config), {
+        grant_type: 'refresh_token',
+        refresh_token: refreshToken,
+        client_id: config.clientId,
+    });
+    return toTokenSet(raw);
+}
+async function tryBindPort(port) {
+    const server = createServer();
+    return new Promise((resolve) => {
+        server.once('error', (err) => {
+            // Surface the actual errno (EADDRINUSE / EACCES / EMFILE / ENOBUFS / ...)
+            // so port_unavailable's message tells the user *why* — not all bind
+            // failures look the same and "in use" is misleading for EACCES/EMFILE.
+            resolve({ server: null, errorCode: err.code ?? 'EUNKNOWN' });
+        });
+        server.once('listening', () => {
+            resolve({ server, errorCode: null });
+        });
+        // Bind to 127.0.0.1 explicitly — loopback only, never external iface.
+        server.listen(port, '127.0.0.1');
+    });
+}
+async function bindLoopback(ports) {
+    const failures = [];
+    for (const p of ports) {
+        const attempt = await tryBindPort(p);
+        if (attempt.server)
+            return { server: attempt.server, port: p };
+        failures.push({ port: p, code: attempt.errorCode ?? 'EUNKNOWN' });
+    }
+    const detail = failures.map((f) => `${f.port}=${f.code}`).join(', ');
+    throw new OAuthError('port_unavailable', `All OAuth redirect ports [${ports.join(', ')}] failed to bind on 127.0.0.1 (${detail}). ` +
+        'Free one of them and retry, or set CLIEN_MCP_OAUTH_PORT=<port>.');
+}
+/** Await a single /callback request; reject on timeout or bad state. */
+function awaitCallback(server, expectedState, timeoutMs) {
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+            cleanup();
+            reject(new OAuthError('oauth_timeout', `Did not receive OAuth callback within ${Math.round(timeoutMs / 1000)}s. ` +
+                'Did you complete the browser consent?'));
+        }, timeoutMs);
+        const onRequest = (req, res) => {
+            try {
+                const reqUrl = new URL(req.url ?? '/', 'http://127.0.0.1');
+                if (reqUrl.pathname !== '/callback') {
+                    res.writeHead(404);
+                    res.end('Not found');
+                    return;
+                }
+                const err = reqUrl.searchParams.get('error');
+                if (err) {
+                    const desc = reqUrl.searchParams.get('error_description') ?? err;
+                    respondHtml(res, 400, errorPage(desc));
+                    cleanup();
+                    reject(new OAuthError(err, desc));
+                    return;
+                }
+                const code = reqUrl.searchParams.get('code');
+                const state = reqUrl.searchParams.get('state');
+                if (!code || !state) {
+                    respondHtml(res, 400, errorPage('Missing code or state in callback.'));
+                    cleanup();
+                    reject(new OAuthError('invalid_callback', 'Missing code or state'));
+                    return;
+                }
+                if (state !== expectedState) {
+                    respondHtml(res, 400, errorPage('State mismatch — potential CSRF attempt.'));
+                    cleanup();
+                    reject(new OAuthError('state_mismatch', 'OAuth state did not match'));
+                    return;
+                }
+                respondHtml(res, 200, successPage());
+                cleanup();
+                resolve({ code, state });
+            }
+            catch (e) {
+                cleanup();
+                reject(e);
+            }
+        };
+        server.on('request', onRequest);
+        function cleanup() {
+            clearTimeout(timer);
+            server.off('request', onRequest);
+            // Close the listener so the next OAuth flow can rebind the same port.
+            // Force-kill any lingering keep-alive sockets on Node 18+.
+            try {
+                server.closeAllConnections?.();
+            }
+            catch {
+                // ignore
+            }
+            server.close(() => { });
+        }
+    });
+}
+function respondHtml(res, status, body) {
+    res.writeHead(status, { 'Content-Type': 'text/html; charset=utf-8' });
+    res.end(body);
+}
+function successPage() {
+    return `<!doctype html><html><head><title>Clien.ai — Connected</title>
+<meta charset="utf-8"><style>
+body { font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+  background: #FDFBF7; color: #1a1a1a; display: flex; min-height: 100vh;
+  align-items: center; justify-content: center; margin: 0; }
+.card { max-width: 480px; text-align: center; padding: 2rem; }
+h1 { color: #3B5CCC; margin-bottom: .5rem; }
+p { color: #444; margin: .25rem 0; }
+</style></head><body><div class="card">
+<h1>Clien.ai connected</h1>
+<p>You can return to Claude Code. Close this tab at your leisure.</p>
+</div></body></html>`;
+}
+function errorPage(message) {
+    const safe = message.replace(/[<>&]/g, (c) => c === '<' ? '&lt;' : c === '>' ? '&gt;' : '&amp;');
+    return `<!doctype html><html><head><title>Clien.ai — Error</title>
+<meta charset="utf-8"><style>
+body { font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+  background: #FDFBF7; color: #1a1a1a; display: flex; min-height: 100vh;
+  align-items: center; justify-content: center; margin: 0; }
+.card { max-width: 480px; text-align: center; padding: 2rem; }
+h1 { color: #E87B6D; margin-bottom: .5rem; }
+p { color: #444; margin: .25rem 0; }
+</style></head><body><div class="card">
+<h1>Connection failed</h1>
+<p>${safe}</p>
+<p>Close this tab and try <code>clien_research</code> again.</p>
+</div></body></html>`;
+}
+async function exchangeCode(config, code, redirectUri, pkce) {
+    const raw = await postForm(tokenEndpoint(config), {
+        grant_type: 'authorization_code',
+        code,
+        client_id: config.clientId,
+        redirect_uri: redirectUri,
+        code_verifier: pkce.verifier,
+    });
+    return toTokenSet(raw);
+}
+/**
+ * Run the full authorization code flow. On success, returns the token set
+ * (access + refresh). On failure, throws OAuthError with a stable code.
+ */
+export async function runAuthorizationCodeFlow(config, openBrowser) {
+    const pkce = generatePkcePair();
+    const state = generateState();
+    const { server, port } = await bindLoopback(config.oauthPorts);
+    const actualPort = server.address()?.port ?? port;
+    // RFC 8252 §7.3: prefer 127.0.0.1 over the symbolic `localhost` so that
+    // dual-stack hosts (Linux + Node 17+) don't try to connect to ::1 while
+    // we listen on the v4 loopback. See issue #170.
+    const redirectUri = `http://127.0.0.1:${actualPort}/callback`;
+    const authorizeUrl = authorizeEndpoint(config, redirectUri, pkce.challenge, state);
+    // Register the callback listener FIRST so we don't race the browser
+    // (important in tests where openBrowser is synchronous + awaited).
+    const callbackPromise = awaitCallback(server, state, config.oauthTimeoutMs);
+    // Attach a noop catch so Node doesn't warn about "unhandled rejection"
+    // if openBrowser is still running when the callback rejects — we still
+    // await this promise below.
+    callbackPromise.catch(() => { });
+    // Open the browser after the listener is wired up.
+    try {
+        await openBrowser(authorizeUrl);
+    }
+    catch (err) {
+        // Don't abort — the URL may also be logged; user can click manually.
+        // But surface as stderr so operators see the recovery path.
+        console.error('[clien-mcp] Failed to auto-open browser, please visit manually:', authorizeUrl, err);
+    }
+    const callback = await callbackPromise;
+    const tokens = await exchangeCode(config, callback.code, redirectUri, pkce);
+    return { tokens, redirectUri };
+}
+/** Read the env-var refresh-token seed for headless contexts (issue #169). */
+function readEnvRefreshSeed() {
+    const v = process.env.CLIEN_MCP_REFRESH_TOKEN;
+    return v && v.length > 0 ? v : null;
+}
+const ALREADY_USED_CODES = new Set([
+    'invalid_grant',
+    'refresh_token_already_used',
+    'refresh_token_not_found',
+]);
+function isAlreadyUsedError(err) {
+    return err instanceof OAuthError && ALREADY_USED_CODES.has(err.code);
+}
+/**
+ * Ensure a valid session. On success: refresh token persisted via
+ * `saveRefreshToken`, access token returned in-memory for the current run.
+ *
+ * State machine:
+ *   1. CLIEN_MCP_REFRESH_TOKEN env seed -> use it; skip disk + browser.
+ *   2. Stored refresh -> take cross-process lock -> reload from disk ->
+ *      refresh. On 'already-used' (peer rotated), reload + retry once.
+ *      On `oauth_network_error`, bubble WITHOUT clearing storage (#165).
+ *      On any other failure, clear and fall through.
+ *   3. Otherwise -> full browser OAuth.
+ *
+ * NOTE: A previous version of this code added a `process.stdin.isTTY` check
+ * before step 3 to fast-fail with `oauth_no_tty` in headless contexts. That
+ * check was removed because Claude Code launches the MCP server over stdio
+ * (stdin = pipe, isTTY === undefined), which is the PRIMARY production path.
+ * The TTY check broke the first-call user flow for every Claude Code user.
+ *
+ * For genuinely headless contexts (CI, devcontainers without a browser), the
+ * recommended path is to set `CLIEN_MCP_REFRESH_TOKEN` (skips OAuth entirely)
+ * or run `clien-mcp authorize --token <r>` from a TTY first to seed the
+ * stored token. If neither is set, the OAuth flow's existing 5-min timeout
+ * surfaces a clear error message at the end, which is recoverable.
+ */
+export async function ensureSession(opts) {
+    // 1. Headless seed via env var — skip disk + browser entirely.
+    const envSeed = readEnvRefreshSeed();
+    if (envSeed) {
+        const tokens = await refreshAccessToken(opts.config, envSeed);
+        // Best-effort persist so subsequent calls without the env var still work.
+        await Promise.resolve(opts.saveRefreshToken(tokens.refreshToken)).catch(() => { });
+        return makeSession(tokens, opts);
+    }
+    // 2. Stored refresh-token path, coordinated across processes by the lock.
+    const stored = await opts.loadRefreshToken();
+    let tokens = null;
+    if (stored) {
+        tokens = await opts.withTokenLock(async () => {
+            // Re-read inside the lock — a peer process may have rotated since our
+            // outer load (their save races our load).
+            const current = (await opts.loadRefreshToken()) ?? stored;
+            try {
+                const fresh = await refreshAccessToken(opts.config, current);
+                await opts.saveRefreshToken(fresh.refreshToken);
+                return fresh;
+            }
+            catch (err) {
+                // CRITICAL: bubble network errors WITHOUT clearing storage. The
+                // previous code unconditionally cleared, defeating the guard. #165.
+                if (err instanceof OAuthError && err.code === 'oauth_network_error') {
+                    throw err;
+                }
+                // 'already-used' race: peer rotated between our reads. Reload and
+                // retry once; the disk now holds the rotated token.
+                if (isAlreadyUsedError(err)) {
+                    const reloaded = await opts.loadRefreshToken();
+                    if (reloaded && reloaded !== current) {
+                        try {
+                            const fresh = await refreshAccessToken(opts.config, reloaded);
+                            await opts.saveRefreshToken(fresh.refreshToken);
+                            return fresh;
+                        }
+                        catch (retryErr) {
+                            if (retryErr instanceof OAuthError && retryErr.code === 'oauth_network_error') {
+                                throw retryErr;
+                            }
+                            // fall through to clearTokens
+                        }
+                    }
+                }
+                // Genuine failure — clear and fall through to OAuth/seed path.
+                await opts.clearTokens().catch(() => { });
+                return null;
+            }
+        });
+    }
+    // 3. Fall through to full browser OAuth. The OAuth flow opens a browser
+    // via the `open` package and waits for the loopback callback. In a true
+    // headless environment with no browser, the existing 5-min timeout
+    // surfaces a clear error — the recommended path for those users is the
+    // CLIEN_MCP_REFRESH_TOKEN env seed (handled in step 1) or running
+    // `clien-mcp authorize --token <r>` from a TTY first to seed the disk.
+    if (!tokens) {
+        const result = await runAuthorizationCodeFlow(opts.config, opts.openBrowser);
+        tokens = result.tokens;
+        await opts.saveRefreshToken(tokens.refreshToken);
+    }
+    return makeSession(tokens, opts);
+}
+/** Build the externally-visible Session object backed by mutable token state. */
+function makeSession(initial, opts) {
+    const state = { current: initial };
+    return {
+        get accessToken() {
+            return state.current.accessToken;
+        },
+        get refreshToken() {
+            return state.current.refreshToken;
+        },
+        async refresh() {
+            const fresh = await opts.withTokenLock(async () => {
+                // Re-read disk inside the lock so a peer's recent rotation wins
+                // over our (potentially stale) in-memory copy.
+                const current = (await opts.loadRefreshToken()) ?? state.current.refreshToken;
+                try {
+                    const refreshed = await refreshAccessToken(opts.config, current);
+                    await opts.saveRefreshToken(refreshed.refreshToken);
+                    return refreshed;
+                }
+                catch (err) {
+                    // Bubble transient errors WITHOUT clearing storage — same guard as
+                    // ensureSession to avoid wiping a still-valid token on a network blip.
+                    if (err instanceof OAuthError && err.code === 'oauth_network_error') {
+                        throw err;
+                    }
+                    if (isAlreadyUsedError(err)) {
+                        const reloaded = await opts.loadRefreshToken();
+                        if (reloaded && reloaded !== current) {
+                            try {
+                                const refreshed = await refreshAccessToken(opts.config, reloaded);
+                                await opts.saveRefreshToken(refreshed.refreshToken);
+                                return refreshed;
+                            }
+                            catch (retryErr) {
+                                if (retryErr instanceof OAuthError && retryErr.code === 'oauth_network_error') {
+                                    throw retryErr;
+                                }
+                                // fall through to clearTokens
+                            }
+                        }
+                    }
+                    // Genuinely revoked refresh token — clear stored credentials so
+                    // the next ensureSession run doesn't reload the same dead token
+                    // and burn another round-trip. Symmetric with ensureSession's
+                    // step-2 path. Best-effort: an unwritable HOME shouldn't mask
+                    // the original refresh failure.
+                    await opts.clearTokens().catch(() => { });
+                    throw err;
+                }
+            });
+            state.current = fresh;
+            return fresh.accessToken;
+        },
+    };
+}
+//# sourceMappingURL=oauth.js.map