pi-multikey 1.7.1 → 1.8.0

package/README.md

@@ -29,7 +29,7 @@ pi install /path/to/multikey
 /multikey → Add pool… → Preset: B.AI → paste keys one per line (blank line to finish)
 ```
 
-After picking the preset, the endpoint, compat, and all 6 model definitions are wired up automatically. Models are available directly as `bai/<model-id>`, e.g. `bai/deepseek-v4-flash`.
+After picking the preset, the endpoint, compat, and all 4 model definitions are wired up automatically. Models are available directly as `bai/<model-id>`, e.g. `bai/hy3`.
 
 ## Presets
 
@@ -37,8 +37,6 @@ Built-in presets decouple "model settings" from "keys". The data comes from b.ai
 
 | Model | ctx / max-out | Modalities | Supported thinking levels |
 |---|---|---|---|
-| deepseek-v4-flash | 1M / 384K | text | off · low · high · max |
-| deepseek-v4-flash-vision-exp | 1M / 384K | text+image | off · low · high · max |
 | hy3 | 256K / 128K | text | off · low · high |
 | mimo-v2.5 | 1M / 128K | text+image | off · high (official: low/medium/high behave identically) |
 | qwen3.8-flash | 1M / 131K | text+image | off · low · medium · xhigh |
@@ -48,25 +46,77 @@ Built-in presets decouple "model settings" from "keys". The data comes from b.ai
 
 ### OpenCode Zen (free tier)
 
-Endpoint `https://opencode.ai/zen/v1`; keys from [opencode.ai/auth](https://opencode.ai/auth) → workspace Keys. Context / max-output are the **Zen free-tier serving limits** (consistent across models.dev `opencode` provider + pi's built-in opencode catalog); the raw models are bigger — MiMo V2.5 = 1M ctx, Hy3 = 262K ctx. `muse-spark-1.2-contributor-free` uses the OpenAI **Responses** API endpoint; the other seven use chat completions.
+Endpoint `https://opencode.ai/zen/v1`; keys from [opencode.ai/auth](https://opencode.ai/auth) → workspace Keys. Context / max-output are the **Zen free-tier serving limits** (opencode.ai/docs/zen); the raw models are bigger — MiMo V2.5 = 1M ctx. `muse-spark-1.3-contributor-free` uses the OpenAI **Responses** API endpoint; the other five use chat completions.
 
-Requests to this endpoint automatically carry the `User-Agent` header that opencode.ai expects (`opencode/1.15.0 ai-sdk/provider-utils/4.0.23 runtime/bun/1.3.13`) — appended whenever a pool's baseUrl is `https://opencode.ai/zen/v1`, on both probes and live requests.
+Requests to this endpoint impersonate the official OpenCode client, on both probes and live requests, whenever a pool's baseUrl is `https://opencode.ai/zen/v1`:
+
+| Header | Value | Lifetime |
+|---|---|---|
+| `x-opencode-client` | `tui` | constant |
+| `User-Agent` | `opencode/0.1.50 ai-sdk/openai-compatible/3.0.41` | constant |
+| `x-opencode-session` | `ses_` + 12 hex + 14 base62 | one per pi conversation; regenerated on `/new`, resume and fork |
+| `x-opencode-request` | v4 UUID | one per machine, persisted as `deviceId` in `multikey.json` |
+
+The session id reproduces OpenCode's own `Identifier.create()`: the first 12 hex chars encode `timestamp_ms * 0x1000 + counter` bitwise-NOTed (descending), so newer conversations sort first, and the counter resets whenever the millisecond changes.
 
 | Model | ctx / max-out | Modalities | Supported thinking levels |
 |---|---|---|---|
 | big-pickle | 200K / 32K | text | always-on (no thinkingLevelMap, like pi's catalog) |
-| deepseek-v4-flash-free | 200K / 128K | text | off · low · high · max (mirrors b.ai's deepseek-v4-flash) |
 | mimo-v2.5-free | 200K / 32K | text+image | always-on (no thinkingLevelMap) |
-| hy3-free | 190K / 64K | text | low · medium · high (no off) |
-| ling-3.0-flash-fin-free | 256K / 32K | text | always-on (no thinkingLevelMap) |
+| ling-3.0-flash-fin-free | 262K / 32K | text | always-on (no thinkingLevelMap) |
 | nemotron-3-ultra-free | 1M / 128K | text | always-on (no thinkingLevelMap) |
-| nemotron-3.5-lightning-free | 256K / 256K | text | always-on (no thinkingLevelMap) |
-| muse-spark-1.2-contributor-free | 1M / 128K | text+image | minimal · low · medium · high · xhigh (no off, Responses API) |
+| nemotron-3.5-lightning-free | 262K / 262K | text | always-on (no thinkingLevelMap) |
+| muse-spark-1.3-contributor-free | 1M / 131K | text+image | always-on (no reasoning_options; Responses API) |
+
+> All six models are free (zero per-token cost) for a limited time while OpenCode collects feedback; data may be used to improve the models (Nemotron free endpoints are NVIDIA trials; Muse Spark Contributor models grant Meta training permission — don't send confidential data).
+>
+> Removed from the preset over time as the free list changed: `deepseek-v4-flash-free` (now **paid** on Zen), `hy3-free` (no longer offered free), and `muse-spark-1.2-contributor-free` (legacy 1.3 predecessor).
+
+### Cline Free (free tier)
+
+Endpoint `https://api.cline.bot/api/v1` (OpenAI-compatible chat completions). Cline periodically offers free models on its usage-billing API — no static API key exists; access is tied to a **Cline account** via OAuth. The preset therefore collects a credential instead of keys:
+
+- **Sign in with Cline (device flow)** — a WorkOS device code is shown; approve it in the browser at the given URL. The refresh token is stored in `multikey.json` and access tokens are minted/rotated automatically before each request and again on 401. This is the recommended path: pasted tokens rot, device-flow tokens don't.
+- **Paste a Cline access token** — from `~/.cline/data/secrets.json` (or the Cline CLI's storage). Works until the token expires, then must be replaced manually.
+
+Requests to this endpoint send the same client-identity headers the official Cline CLI sends, on probes and live requests alike:
 
-> All eight models are free (zero per-token cost) for a limited time while OpenCode collects feedback; data may be used to improve the models (Nemotron free endpoints are NVIDIA trials — don't send confidential data).
+| Header | Value |
+|---|---|
+| `HTTP-Referer` / `X-Title` | `https://cline.bot` / `Cline` |
+| `X-CLIENT-TYPE` / `X-CLIENT-VERSION` | `cline-cli` / CLI version |
+| `User-Agent` | `Cline/<version>` |
+| `X-PLATFORM` / `X-PLATFORM-VERSION` | `cli` / CLI version |
+| `X-CORE-VERSION` | SDK core version |
+| `X-IS-MULTIROOT` | `false` |
+| `X-Task-ID` | v4 UUID, one per pi conversation (regenerated on `/new`, resume, fork) |
+
+Quota semantics differ from every other pool: Cline enforces a **daily, per-account, per-model** limit answered with `429 "Daily free limit reached on model X. Try again in 23h 59m"`. multikey classifies this as its own outcome — the key cools down until the server-reported reset time (shown as `cooldown 24h (daily limit)` in the status view) instead of the 20s 429 rotation, which would be meaningless here.
+
+| Model | ctx / max-out | Notes |
+|---|---|---|
+| deepseek/deepseek-v4-flash | 1M / 131K | thinking levels not yet probed |
+| meituan/longcat-2.0 | 1M / 131K | thinking levels not yet probed |
+| poolside/laguna-s-2.1:free | 128K / 16K | limits unpublished; safe defaults |
+| z-ai/glm-5.2:free | 200K / 131K | thinking levels not yet probed |
+
+> The free lineup **rotates**: retired ids answer `"model not found"`. New models appear via `GET /models` (public) — or accept the one-time preset-sync prompt when this preset ships an updated list. Context/output numbers are best-effort (server-enforced); tune them per model in `multikey.json`.
+>
+> **Single-account by design.** A Cline account is meant to be used from the official IDE extension / CLI, not third-party API clients, and multi-account rotation to dodge the daily quota would violate Cline's terms. The integration exists to use *your own* account's free quota from pi; the client headers identify requests as coming from a Cline-style client. Use it accordingly.
 
 To add a preset: append one entry to the `PRESETS` array in `presets.ts`.
 
+### Preset sync
+
+Pools created from a preset are tracked: `poolFromPreset` stamps a `_preset` marker (preset id + a fingerprint of the model list) into `multikey.json`.
+
+- When a shipped preset changes (models added/removed, spec tweaks), pi asks **once** at session start: "Built-in presets changed for pool(s) … — review and align now?"
+- **Align** replaces the pool's model list with the preset's; keys, endpoint, and settings are kept. **Keep my models** — or Esc, or even a crash mid-prompt — mutes that version: the offered fingerprint is persisted *before* the dialog shows, so the same version never re-prompts.
+- When the preset changes **again** (new fingerprint), you're asked once more. Each version gets exactly one ask.
+- Hand-tuned models never trigger the automatic prompt (the preset hasn't changed since your last sync); they stay reachable via `/multikey → Check preset updates…`, which is always available regardless of muting.
+- Legacy pools (created before tracking existed) are matched by `baseUrl` and adopted into tracking the same way.
+- The fingerprint covers the preset's **models only** — compat/API/description changes don't trigger prompts.
+
 ## Configuration
 
 `~/.pi/agent/multikey.json`. On first run it auto-discovers mergeable pools from `~/.pi/agent/models.json` (≥2 providers sharing a baseUrl = you copying the provider per key), and also picks up providers pointing at `api.b.ai`; if nothing is found it generates an empty config.
@@ -75,7 +125,7 @@ To add a preset: append one entry to the `PRESETS` array in `presets.ts`.
 {
   "pools": [
     {
-      "id": "bai",                          // provider id in pi → bai/deepseek-v4-flash
+      "id": "bai",                          // provider id in pi → bai/hy3
       "name": "B.AI (Key Pool)",
       "baseUrl": "https://api.b.ai/v1",
       "api": "openai-completions",
@@ -85,7 +135,9 @@ To add a preset: append one entry to the `PRESETS` array in `presets.ts`.
       "invalidKeyCooldownMs": 600000,       // 401/403 cooldown
       "keys": [
         { "key": "sk-...", "label": "key-1", "enabled": true },
-        { "key": "sk-...", "label": "key-2", "enabled": true }
+        { "key": "sk-...", "label": "key-2", "enabled": true },
+        { "key": "<access token>", "label": "cline-account", "enabled": true,
+          "credential": { "kind": "cline-oauth", "refreshToken": "...", "accessToken": "...", "expiresAt": 1735689600000 } }
       ],
       "models": [ "…preset or hand-configured model definitions…" ]
     }
@@ -147,8 +199,10 @@ Set `agentOverrides` in `settings.json` to the pool provider:
 - The extension registers a provider via `pi.registerProvider()` with a custom `streamSimple`.
 - Each request leases one key from the pool (`options.apiKey` overrides), and once the HTTP response headers arrive:
   - 429 → that key is cooled down (default 20s, honoring `retry-after`) and the request immediately retries with the next key (no duplicated output);
-  - 401/403 → that key gets a long cooldown (default 10 minutes) and the request retries with the next key;
+  - Cline daily free limit (429 + `"free limit reached on model"` in the body) → that key cools down until the server-reported reset time (hours, not seconds) and the request retries with the next key;
+  - 401/403 → that key gets a long cooldown (default 10 minutes) and the request retries with the next key; for OAuth-backed keys (Cline), a 401 first forces one token refresh + same-key retry before any cooldown;
   - other errors → handed back to pi's own retry mechanism.
+- OAuth-backed keys (Cline accounts) resolve a fresh access token from their stored refresh token before every request (single-flight per account, so concurrent subagents share one refresh), and every rotation of the refresh token is persisted back to `multikey.json`.
 - Only when every key is exhausted does it surface the 429 upward, letting pi's own backoff retry as a safety net (by then the earliest cooldown has usually expired).
 
 ## Security note

package/README.zh.md

@@ -27,8 +27,8 @@ pi install /path/to/multikey
 /multikey → Add pool… → Preset: B.AI → 逐行粘贴 key（一行一个，留空结束）
 ```
 
-选 preset 后 endpoint、compat、6 个模型的全部设定自动就位，模型通过
-`bai/<model-id>` 直接可用，例如 `bai/deepseek-v4-flash`。
+选 preset 后 endpoint、compat、4 个模型的全部设定自动就位，模型通过
+`bai/<model-id>` 直接可用，例如 `bai/hy3`。
 
 ## Presets
 
@@ -38,8 +38,6 @@ DeepSeek / Tencent / 小米官方文档，并对每个 thinking 档位做过实
 
 | 模型 | ctx / max-out | 模态 | 生效 thinking 档位 |
 |---|---|---|---|
-| deepseek-v4-flash | 1M / 384K | text | off · low · high · max |
-| deepseek-v4-flash-vision-exp | 1M / 384K | text+image | off · low · high · max |
 | hy3 | 256K / 128K | text | off · low · high |
 | mimo-v2.5 | 1M / 128K | text+image | off · high（官方：low/medium/high 行为相同） |
 | qwen3.8-flash | 1M / 131K | text+image | off · low · medium · xhigh |
@@ -52,27 +50,46 @@ DeepSeek / Tencent / 小米官方文档，并对每个 thinking 档位做过实
 ### OpenCode Zen（免费层）
 
 端点 `https://opencode.ai/zen/v1`；密钥从 [opencode.ai/auth](https://opencode.ai/auth) → workspace Keys 获取。
-上下文/最大输出为 **Zen 免费层限制**（models.dev `opencode` provider 与 pi 内置 opencode 目录一致）；
-原始模型更大——MiMo V2.5 = 1M ctx，Hy3 = 262K ctx。
-`muse-spark-1.2-contributor-free` 使用 OpenAI **Responses** API；其余七个使用 chat completions。
+上下文/最大输出为 **Zen 免费层限制**（opencode.ai/docs/zen）；原始模型更大——MiMo V2.5 = 1M ctx。
+`muse-spark-1.3-contributor-free` 使用 OpenAI **Responses** API；其余五个使用 chat completions。
 
-对该端点的请求会自动携带 opencode.ai 期望的 `User-Agent` 头（`opencode/1.15.0 ai-sdk/provider-utils/4.0.23 runtime/bun/1.3.13`）——只要 pool 的 baseUrl 是 `https://opencode.ai/zen/v1`，探测和真实请求都会附加。
+只要 pool 的 baseUrl 是 `https://opencode.ai/zen/v1`，探测和真实请求都会伪装成官方 OpenCode 客户端：
+
+| 请求头 | 值 | 生命周期 |
+|---|---|---|
+| `x-opencode-client` | `tui` | 常量 |
+| `User-Agent` | `opencode/0.1.50 ai-sdk/openai-compatible/3.0.41` | 常量 |
+| `x-opencode-session` | `ses_` + 12 位十六进制 + 14 位 base62 | 每个 pi 会话一个；`/new`、resume、fork 时重新生成 |
+| `x-opencode-request` | v4 UUID | 每台机器一个，作为 `deviceId` 持久化在 `multikey.json` |
+
+session id 复现了 OpenCode 自己的 `Identifier.create()`：前 12 位十六进制编码 `timestamp_ms * 0x1000 + counter` 后按位取反（降序），因此新会话排序在前；计数器仅在毫秒变化时重置。
 
 | 模型 | ctx / max-out | 模态 | 生效 thinking 档位 |
 |---|---|---|---|
 | big-pickle | 200K / 32K | text | 始终思考（无 thinkingLevelMap，与 pi 内置目录一致） |
-| deepseek-v4-flash-free | 200K / 128K | text | off · low · high · max（沿用 b.ai preset 的 deepseek-v4-flash） |
 | mimo-v2.5-free | 200K / 32K | text+image | 始终思考（无 thinkingLevelMap） |
-| hy3-free | 190K / 64K | text | low · medium · high（无 off） |
-| ling-3.0-flash-fin-free | 256K / 32K | text | 始终思考（无 thinkingLevelMap） |
+| ling-3.0-flash-fin-free | 262K / 32K | text | 始终思考（无 thinkingLevelMap） |
 | nemotron-3-ultra-free | 1M / 128K | text | 始终思考（无 thinkingLevelMap） |
-| nemotron-3.5-lightning-free | 256K / 256K | text | 始终思考（无 thinkingLevelMap） |
-| muse-spark-1.2-contributor-free | 1M / 128K | text+image | minimal · low · medium · high · xhigh（无 off，Responses API） |
+| nemotron-3.5-lightning-free | 262K / 262K | text | 始终思考（无 thinkingLevelMap） |
+| muse-spark-1.3-contributor-free | 1M / 131K | text+image | 始终思考（无 reasoning_options；Responses API） |
 
-> 以上八个模型在 OpenCode 收集反馈期间均免费（零 token 费用）；数据可能用于改进模型（Nemotron 免费端点为 NVIDIA 试用——请勿提交机密数据）。
+> 以上六个模型在 OpenCode 收集反馈期间均免费（零 token 费用）；数据可能用于改进模型（Nemotron 免费端点为 NVIDIA 试用；Muse Spark Contributor 模型授权 Meta 用于训练——请勿提交机密数据）。
+>
+> 免费列表变化后已从 preset 移除：`deepseek-v4-flash-free`（在 Zen 上已转为**付费**）、`hy3-free`（不再提供免费层）、`muse-spark-1.2-contributor-free`（1.3 的前身遗留变体）。
 
 新增 preset：在 `presets.ts` 的 `PRESETS` 数组里加一项即可。
 
+### Preset 同步
+
+从 preset 创建的池会被追踪：`poolFromPreset` 会在 `multikey.json` 里写入 `_preset` 标记（preset id + 模型列表的指纹）。
+
+- 内置 preset 变化（模型增删、参数调整）后，pi 会在会话启动时**只询问一次**：“内置 preset 已变化……是否立即对齐？”
+- **Align** 用 preset 的模型列表替换池的模型；密钥、endpoint、其他设置保留。**Keep my models**——以及 Esc、甚至提示中途崩溃——都会静音该版本：提供的指纹在弹窗**之前**就已持久化，同一版本绝不会重复询问。
+- preset **再次**变化（新指纹）时会再询问一次。每个版本恰好一次。
+- 手动调过参数的池不会触发自动询问（自上次同步后 preset 没变）；它们始终可以通过 `/multikey → Check preset updates…` 检查，该入口不受静音影响。
+- 旧版本创建的池（早于追踪功能）按 `baseUrl` 匹配并以同样方式纳入追踪。
+- 指纹只覆盖 preset 的**模型列表**——compat/API/描述变化不会触发询问。
+
 ## 配置
 
 `~/.pi/agent/multikey.json`。首次运行时会从 `~/.pi/agent/models.json` 自动发现
@@ -83,7 +100,7 @@ DeepSeek / Tencent / 小米官方文档，并对每个 thinking 档位做过实
 {
   "pools": [
     {
-      "id": "bai",                          // pi 里的 provider id → bai/deepseek-v4-flash
+      "id": "bai",                          // pi 里的 provider id → bai/hy3
       "name": "B.AI (Key Pool)",
       "baseUrl": "https://api.b.ai/v1",
       "api": "openai-completions",

package/cline-auth.ts

@@ -0,0 +1,242 @@
+/**
+ * Cline account authentication: WorkOS device flow + access token refresh.
+ *
+ * Cline's free models are tied to a Cline account (no static API keys), so a
+ * pool key can carry a `credential: { kind: "cline-oauth", refreshToken }`
+ * instead of a long-lived secret. Endpoints/port/response shapes are ported
+ * from the cline SDK (sdk/packages/core/src/auth/cline.ts, production env).
+ *
+ * Flow:
+ *   1. POST api.workos.com/user_management/authorize/device  → device + user code
+ *   2. User opens the verification URL in a browser and approves
+ *   3. Poll api.workos.com/user_management/authenticate      → WorkOS tokens
+ *   4. POST api.cline.bot/api/v1/auth/register               → Cline tokens
+ *   5. Refresh: POST api.cline.bot/api/v1/auth/refresh
+ *
+ * Tokens rotate on every refresh (the refresh token in the response replaces
+ * the old one), so callers must persist the result — stream.ts does this via
+ * KeyPool.applyClineCredential + the config save hook.
+ */
+
+import type { KeyCredential } from "./config.ts";
+
+const WORKOS_API_BASE_URL = "https://api.workos.com";
+const WORKOS_DEVICE_AUTHORIZATION_PATH = "/user_management/authorize/device";
+const WORKOS_AUTHENTICATE_PATH = "/user_management/authenticate";
+/** WorkOS client id of the official Cline CLI (production environment). */
+const WORKOS_CLIENT_ID = "client_01K3A541FN8TA3EPPHTD2325AR";
+
+const CLINE_API_BASE_URL = "https://api.cline.bot";
+const CLINE_REGISTER_PATH = "/api/v1/auth/register";
+const CLINE_REFRESH_PATH = "/api/v1/auth/refresh";
+
+const REQUEST_TIMEOUT_MS = 30_000;
+const DEVICE_AUTH_EXPIRES_IN_SECONDS = 300;
+const DEVICE_AUTH_INTERVAL_SECONDS = 5;
+/** Refresh this long before expiry so requests never race the clock. */
+export const REFRESH_BUFFER_MS = 5 * 60_000;
+
+/** Headers sent to Cline API auth endpoints (same client identity as chat requests). */
+function clineAuthHeaders(): Record<string, string> {
+	return { "Content-Type": "application/json", "User-Agent": "Cline/3.0.61" };
+}
+
+export interface ClineTokenUpdate {
+	/** New access token (stored as the key's `key` value). */
+	accessToken: string;
+	/** Replacement refresh token; WorkOS/Cline rotate it on every refresh. */
+	refreshToken: string;
+	/** Access token expiry in epoch ms, when the server reports one. */
+	expiresAt?: number;
+}
+
+interface ClineTokenResponse {
+	success: boolean;
+	data?: {
+		accessToken?: string;
+		refreshToken?: string;
+		expiresAt?: string;
+	};
+}
+
+function parseExpiresAt(value: string | undefined): number | undefined {
+	if (!value) return undefined;
+	const ms = Date.parse(value);
+	return Number.isFinite(ms) ? ms : undefined;
+}
+
+function requireClineTokens(payload: ClineTokenResponse, message: string): ClineTokenUpdate {
+	const accessToken = payload.data?.accessToken;
+	const refreshToken = payload.data?.refreshToken;
+	if (!payload.success || !accessToken || !refreshToken) {
+		throw new Error(message);
+	}
+	return { accessToken, refreshToken, expiresAt: parseExpiresAt(payload.data?.expiresAt) };
+}
+
+/** True when the stored access token is missing, expired, or inside the refresh buffer. */
+export function isClineTokenStale(credential: KeyCredential, bufferMs = REFRESH_BUFFER_MS): boolean {
+	if (!credential.accessToken) return true;
+	if (credential.expiresAt === undefined) return false; // unknown expiry: use until a 401 says otherwise
+	return credential.expiresAt - Date.now() <= bufferMs;
+}
+
+/** Exchange a refresh token for a fresh access (+ rotated refresh) token. */
+export async function refreshClineToken(refreshToken: string): Promise<ClineTokenUpdate> {
+	const response = await fetch(`${CLINE_API_BASE_URL}${CLINE_REFRESH_PATH}`, {
+		method: "POST",
+		headers: clineAuthHeaders(),
+		body: JSON.stringify({ refreshToken, grantType: "refresh_token" }),
+		signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+	});
+	if (!response.ok) {
+		const text = await response.text().catch(() => "");
+		throw new Error(`Cline token refresh failed: HTTP ${response.status}${text ? ` — ${text.slice(0, 200)}` : ""}`);
+	}
+	const payload = (await response.json().catch(() => ({}))) as ClineTokenResponse;
+	return requireClineTokens(payload, "Invalid Cline token refresh response");
+}
+
+// Single-flight per refresh token: concurrent subagents hitting the same
+// account must share one in-flight refresh instead of racing each other.
+const inFlight = new Map<string, Promise<ClineTokenUpdate>>();
+
+/**
+ * Return a usable access token for the credential, refreshing when stale.
+ * Pass `force` after a 401 to refresh even if the token looks valid.
+ */
+export async function ensureClineAccessToken(
+	credential: KeyCredential,
+	options?: { force?: boolean },
+): Promise<ClineTokenUpdate & { refreshed: boolean }> {
+	const force = options?.force === true;
+	if (!force && !isClineTokenStale(credential) && credential.accessToken) {
+		return { accessToken: credential.accessToken, refreshToken: credential.refreshToken, expiresAt: credential.expiresAt, refreshed: false };
+	}
+	const existing = inFlight.get(credential.refreshToken);
+	if (existing) return { ...(await existing), refreshed: true };
+	const task = refreshClineToken(credential.refreshToken).finally(() => {
+		inFlight.delete(credential.refreshToken);
+	});
+	inFlight.set(credential.refreshToken, task);
+	return { ...(await task), refreshed: true };
+}
+// ── Device flow (initial sign-in) ───────────────────────────────────────────
+
+interface WorkOSDeviceAuthorizationResponse {
+	device_code?: string;
+	user_code?: string;
+	verification_uri?: string;
+	verification_uri_complete?: string;
+	expires_in?: number;
+	interval?: number;
+	error?: string;
+	error_description?: string;
+}
+
+interface WorkOSTokenResponse {
+	access_token?: string;
+	refresh_token?: string;
+	token_type?: string;
+	error?: string;
+	error_description?: string;
+}
+
+const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));
+
+/**
+ * Interactive sign-in: request a device code, hand the verification URL to
+ * `onAuthInfo` (awaited, so the UI can show it before polling starts), poll
+ * WorkOS until the user approves, then exchange for Cline tokens.
+ */
+export async function loginClineDeviceFlow(options: {
+	/** Awaited once the verification URL/user code are known (e.g. show a dialog). */
+	onAuthInfo: (info: { url: string; userCode: string }) => Promise<void>;
+	/** Optional progress lines while polling (e.g. append to a progress panel). */
+	onProgress?: (message: string) => void;
+}): Promise<ClineTokenUpdate> {
+	const authResponse = await fetch(`${WORKOS_API_BASE_URL}${WORKOS_DEVICE_AUTHORIZATION_PATH}`, {
+		method: "POST",
+		headers: { "Content-Type": "application/x-www-form-urlencoded" },
+		body: new URLSearchParams({ client_id: WORKOS_CLIENT_ID }),
+		signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+	});
+	const device = (await authResponse.json().catch(() => ({}))) as WorkOSDeviceAuthorizationResponse;
+	if (!authResponse.ok || !device.device_code || !device.user_code || !device.verification_uri) {
+		const detail = device.error_description ?? (authResponse.ok ? "invalid WorkOS response" : `HTTP ${authResponse.status}`);
+		throw new Error(`Cline device authorization failed: ${detail}`);
+	}
+
+	await options.onAuthInfo({
+		url: device.verification_uri_complete ?? device.verification_uri,
+		userCode: device.user_code,
+	});
+
+	const expiresInSeconds = device.expires_in ?? DEVICE_AUTH_EXPIRES_IN_SECONDS;
+	const deadline = Date.now() + expiresInSeconds * 1000;
+	let intervalSeconds = Math.max(1, device.interval ?? DEVICE_AUTH_INTERVAL_SECONDS);
+	let workosTokens: { access: string; refresh: string } | undefined;
+
+	while (Date.now() <= deadline) {
+		const pollResponse = await fetch(`${WORKOS_API_BASE_URL}${WORKOS_AUTHENTICATE_PATH}`, {
+			method: "POST",
+			headers: { "Content-Type": "application/x-www-form-urlencoded" },
+			body: new URLSearchParams({
+				grant_type: "urn:ietf:params:oauth:grant-type:device_code",
+				device_code: device.device_code,
+				client_id: WORKOS_CLIENT_ID,
+			}),
+			signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+		});
+		const payload = (await pollResponse.json().catch(() => ({}))) as WorkOSTokenResponse;
+		if (pollResponse.ok) {
+			if (!payload.access_token || !payload.refresh_token) {
+				throw new Error("Invalid WorkOS token response");
+			}
+			workosTokens = { access: payload.access_token, refresh: payload.refresh_token };
+			break;
+		}
+		switch (payload.error) {
+			case "authorization_pending":
+				options.onProgress?.("Waiting for browser authentication confirmation…");
+				await sleep(intervalSeconds * 1000);
+				break;
+			case "slow_down":
+				intervalSeconds += 1;
+				await sleep(intervalSeconds * 1000);
+				break;
+			case "access_denied":
+			case "expired_token":
+			case "invalid_grant":
+				throw new Error(`Cline authorization failed: ${payload.error_description ?? payload.error}`);
+			default:
+				throw new Error(`WorkOS token polling failed: HTTP ${pollResponse.status}${payload.error_description ? ` — ${payload.error_description}` : ""}`);
+		}
+	}
+	if (!workosTokens) throw new Error("WorkOS device authorization timed out");
+
+	// Exchange the WorkOS tokens for Cline account tokens.
+	const registerResponse = await fetch(`${CLINE_API_BASE_URL}${CLINE_REGISTER_PATH}`, {
+		method: "POST",
+		headers: clineAuthHeaders(),
+		body: JSON.stringify({ accessToken: workosTokens.access, refreshToken: workosTokens.refresh }),
+		signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+	});
+	if (!registerResponse.ok) {
+		const text = await registerResponse.text().catch(() => "");
+		throw new Error(`Cline token registration failed: HTTP ${registerResponse.status}${text ? ` — ${text.slice(0, 200)}` : ""}`);
+	}
+	const payload = (await registerResponse.json().catch(() => ({}))) as ClineTokenResponse;
+	return requireClineTokens(payload, "Invalid Cline token registration response");
+}
+
+/** Human-readable expiry line for the TUI (token state only; quota lives server-side). */
+export function describeClineCredential(credential: KeyCredential): string {
+	if (credential.expiresAt === undefined) return "token expiry unknown";
+	const remaining = credential.expiresAt - Date.now();
+	if (remaining <= 0) return `token expired ${Math.round(-remaining / 60_000)}m ago`;
+	if (remaining < 90_000) return `token expires in ${Math.round(remaining / 1000)}s`;
+	if (remaining < 90 * 60_000) return `token expires in ${Math.round(remaining / 60_000)}m`;
+	return `token expires in ${Math.round(remaining / 3_600_000)}h`;
+}
+