@bitkyc08/opencodex 2.52.0-preview.20260911 → 2.52.0-preview.20260912

package/src/integrations/store.ts

@@ -17,6 +17,7 @@ import {
   clearPruneFailure,
   countSnapshots,
   findOperation,
+  findCommittedOperation,
   listOperations,
   markPruneFailure,
   pruneSnapshots,
@@ -32,6 +33,7 @@ import {
   deleteRecord,
   integrationsDir,
   readRecords,
+  readRecordsStrict,
   writeRecord,
   type OwnershipRecord,
 } from "./ownership";
@@ -41,6 +43,7 @@ export interface IntegrationStateStore {
   /** The integrations directory itself — never a config root to resolve again. */
   readonly root: string;
   readRecords(): Partial<Record<IntegrationClientId, OwnershipRecord>>;
+  readRecordsStrict(): Partial<Record<IntegrationClientId, OwnershipRecord>>;
   putRecord(record: OwnershipRecord): void;
   dropRecord(clientId: IntegrationClientId): void;
   appendJournal(entry: JournalEntry): void;
@@ -48,6 +51,7 @@ export interface IntegrationStateStore {
   retireOperation(record: JournalTombstone): void;
   listOperations(clientId?: IntegrationClientId, limit?: number): JournalEntry[];
   findOperation(opId: string): JournalEntry | null;
+  findCommittedOperation(opId: string): JournalEntry | null;
   captureSnapshot(clientId: IntegrationClientId, opId: string, text: string | null): SnapshotRef;
   readSnapshot(entry: JournalEntry):
     | { kind: "none" }
@@ -79,12 +83,14 @@ export function createIntegrationStateStore(root: string = integrationsDir()): I
   const store: IntegrationStateStore = {
     root: dir,
     readRecords: () => readRecords(dir),
+    readRecordsStrict: () => readRecordsStrict(dir),
     putRecord: record => writeRecord(record, dir),
     dropRecord: clientId => deleteRecord(clientId, dir),
     appendJournal: entry => appendOperation(entry, dir),
     retireOperation: record => appendTombstone(record, dir),
     listOperations: (clientId, limit) => listOperations(clientId, limit, dir),
     findOperation: opId => findOperation(opId, dir),
+    findCommittedOperation: opId => findCommittedOperation(opId, dir),
     captureSnapshot: (clientId, opId, text) => captureSnapshot(clientId, opId, text, dir),
     readSnapshot: entry => readSnapshot(entry, dir),
     countSnapshots: clientId => countSnapshots(clientId, dir),

package/src/integrations/writer.ts

@@ -10,6 +10,8 @@
  * Design of record: devlog/_fin/260802_client_toggle_api/030 and 031.
  */
 import { homedir } from "node:os";
+import { createClineIO, ClineTransactionError } from "./cline-io";
+import { parseClineDocument, serializeClineDocument, preserveClineSelection } from "./cline-document";
 import { dirname } from "node:path";
 import { EXPORT_CLIENTS, type ExportModel, type ManagedContribution } from "../clients/config-export";
 import { shouldInjectApiAuthHeader } from "../codex/inject";
@@ -35,7 +37,29 @@ import { serializeDocument, UnserializableValueError } from "./serialize";
 import { ClientPathError } from "../clients/config-export";
 import { matchesOperationResult, newOpId, type JournalEntry } from "./journal";
 import { createIntegrationStateStore, type IntegrationStateStore } from "./store";
-import { patchYamlFragmentSource, sourcePrunableYamlContainers } from "./omp-yaml-source";
+import {
+  patchYamlFragmentSource,
+  sourcePrunableYamlContainers,
+  yamlFragmentUnsupportedStyle,
+} from "./omp-yaml-source";
+
+/**
+ * "comments or formatting" used to be the only refusal this path could report.
+ * For a flow-style container that names a cause which is not in the file, and
+ * DSH writes that shape itself, so the misdirection was routine rather than
+ * exotic: users went looking for a comment that was never there (#4260).
+ */
+function yamlRefusalReason(
+  source: string,
+  path: readonly string[],
+  configPath: string,
+  outcome: string,
+): string {
+  if (yamlFragmentUnsupportedStyle(source, path)) {
+    return `${configPath} writes ${path.join(".")} as a flow mapping or sequence, a YAML style opencodex will not re-render, so ${outcome}`;
+  }
+  return `${configPath} uses YAML source opencodex cannot patch without risking unrelated comments or formatting, so ${outcome}`;
+}
 import { withIntegrationWriterLock, type IntegrationWriterLockSeams } from "./writer-lock";
 
 export type RefusalReason =
@@ -126,13 +150,19 @@ interface CommitArgs {
  */
 function commit(args: CommitArgs): WriteOutcome {
   const { io, clientId, configPath } = args;
+  let transactionStarted = false;
   try {
+    if (io.beginTransaction) {
+      io.beginTransaction(args);
+      transactionStarted = true;
+    }
     if (args.nextText === null) io.removeFile(configPath);
     else {
       io.mkdirp(dirname(configPath));
       io.writeText(configPath, args.nextText);
     }
   } catch (error) {
+    if (transactionStarted) return compensate(args, error, "could not write both Cline files");
     return refuse(clientId, "write_failed", args.state, messageOf(error), args.snapshotPath);
   }
   try {
@@ -146,6 +176,7 @@ function commit(args: CommitArgs): WriteOutcome {
   } catch (error) {
     return compensate(args, error, "could not append the journal row");
   }
+  io.finishTransaction?.();
   return {
     ok: true,
     changed: true,
@@ -176,6 +207,7 @@ function compensate(args: CommitArgs, cause: unknown, what: string): WriteRefuse
       message: `${what}, and the change could not be rolled back. The file or its ownership record is in an intermediate state; the backup is at ${args.snapshotPath ?? "(none)"}.`,
     };
   }
+  io.finishTransaction?.();
   return refuse(clientId, "write_failed", args.state, `${what}; the change was rolled back. Cause: ${messageOf(cause)}`, args.snapshotPath);
 }
 
@@ -198,7 +230,7 @@ function sourcePreservingFragmentValue(
 /** Shared preflight: detect, gate, read, parse and classify. */
 function preflight(input: IntegrationWriteInput) {
   const store = input.store ?? createIntegrationStateStore();
-  const io = input.io ?? defaultIntegrationIO(store);
+  let io = input.io ?? defaultIntegrationIO(store);
   const clientId = input.clientId;
   const spec = INTEGRATION_CLIENTS[clientId];
   const exportSpec = EXPORT_CLIENTS[clientId];
@@ -224,7 +256,11 @@ function preflight(input: IntegrationWriteInput) {
     const resolved = input.resolvedPaths ?? resolveIntegrationPaths(clientId, input.env, input.home);
     configPath = resolved.configPath;
     detectDir = resolved.detectDir;
+    if (clientId === "cline") io = createClineIO(io, configPath, store, true);
   } catch (error) {
+    if (error instanceof ClineTransactionError) {
+      return { failed: { ...refuse(clientId, "unsafe", "unsafe", error.message, error.snapshotPath), residual: true } } as const;
+    }
     if (!(error instanceof ClientPathError)) throw error;
     return { failed: refuse(clientId, "unsafe", "unsafe", error.message) } as const;
   }
@@ -240,7 +276,7 @@ function preflight(input: IntegrationWriteInput) {
     } as const;
   }
   const before = target.before;
-  const parsed = parseConfig(before, exportSpec.format);
+  const parsed = clientId === "cline" ? parseClineDocument(before) : parseConfig(before, exportSpec.format);
   if (parsed === PARSE_FAILED) {
     return { failed: refuse(clientId, "unsafe", "unsafe",
       `${configPath} could not be parsed, or holds something opencodex cannot rewrite without changing it (a non-finite number, a large integer or a tiny one a rewrite would round, -0, a duplicate member, or nesting deeper than 1000 levels)`) } as const;
@@ -387,6 +423,7 @@ function applyOrRefreshIntegration(
     // every container exists and "did we create this?" is unanswerable.
     created = createdContainerPaths(base, contribution);
     const nextDocument = mergeContribution(base, contribution);
+    if (clientId === "cline") preserveClineSelection(parsed, nextDocument);
     if (spec.sourcePreservingYaml && before !== null) {
       const value = sourcePreservingFragmentValue(contribution, spec.sourcePreservingYaml.path);
       const patched = value === undefined
@@ -399,11 +436,11 @@ function applyOrRefreshIntegration(
           );
       if (patched === null) {
         return refuse(clientId, "unsafe", "unsafe",
-          `${configPath} uses YAML source opencodex cannot patch without risking unrelated comments or formatting, so it was left alone`);
+          yamlRefusalReason(before, spec.sourcePreservingYaml.path, configPath, "it was left alone"));
       }
       text = patched;
     } else {
-      text = serializeDocument(nextDocument, exportSpec.format);
+      text = clientId === "cline" ? serializeClineDocument(nextDocument) : serializeDocument(nextDocument, exportSpec.format);
     }
   } catch (error) {
     if (error instanceof AmbiguousSelectorError) {
@@ -536,7 +573,7 @@ export function disableIntegration(input: IntegrationWriteInput): WriteOutcome {
     : recordedCreated;
   if (prunableCreated === null) {
     return refuse(clientId, "unsafe", "unsafe",
-      `${configPath} uses YAML source opencodex cannot patch without risking unrelated comments or formatting, so nothing was removed`);
+      yamlRefusalReason(before ?? "", spec.sourcePreservingYaml!.path, configPath, "nothing was removed"));
   }
   let doc: unknown;
   let removed: boolean;
@@ -559,11 +596,11 @@ export function disableIntegration(input: IntegrationWriteInput): WriteOutcome {
       }, doc);
       if (patched === null) {
         return refuse(clientId, "unsafe", "unsafe",
-          `${configPath} uses YAML source opencodex cannot patch without risking unrelated comments or formatting, so nothing was removed`);
+          yamlRefusalReason(before, spec.sourcePreservingYaml.path, configPath, "nothing was removed"));
       }
       text = patched;
     } else {
-      text = serializeDocument(doc, exportSpec.format);
+      text = clientId === "cline" ? serializeClineDocument(doc) : serializeDocument(doc, exportSpec.format);
     }
   } catch (error) {
     if (!(error instanceof UnserializableValueError)) throw error;
@@ -593,7 +630,7 @@ export function disableIntegration(input: IntegrationWriteInput): WriteOutcome {
 
 export function restoreIntegration(input: IntegrationRestoreInput): WriteOutcome {
   const store = input.store ?? createIntegrationStateStore();
-  const io = input.io ?? defaultIntegrationIO(store);
+  let io = input.io ?? defaultIntegrationIO(store);
   const entry = store.findOperation(input.opId);
   if (!entry) throw new Error(`unknown operation ${input.opId}`);
   if (entry.clientId !== input.clientId) throw new Error("restore input names a different client than the operation");
@@ -609,6 +646,13 @@ export function restoreIntegration(input: IntegrationRestoreInput): WriteOutcome
     return refuse(clientId, "conflict", "conflict",
       `that operation was recorded for ${configPath}, but this client now resolves to ${resolvedPath}`);
   }
+  if (clientId === "cline") {
+    try { io = createClineIO(io, configPath, store, true); }
+    catch (error) {
+      if (!(error instanceof ClineTransactionError)) throw error;
+      return { ...refuse(clientId, "unsafe", "unsafe", error.message, error.snapshotPath), residual: true };
+    }
+  }
   const snapshot = store.readSnapshot(entry);
   if (snapshot.kind === "expired") {
     return refuse(clientId, "snapshot_expired", "absent", "that backup has expired");

package/src/lab/subject/behavior-fingerprint.ts

@@ -3,7 +3,7 @@ import { jcsStringify } from "../digest";
 import type { LabBehaviorSource, LabBehaviorValues } from "../live/types";
 
 const CLOSED_KEYS = new Set([
-  "wire.adapter", "wire.upstreamProtocol", "wire.responsesPath", "wire.commandCodeVersion", "wire.modelSuffixMode",
+  "wire.adapter", "wire.upstreamProtocol", "wire.responsesPath", "wire.chatCompletionsPath", "wire.commandCodeVersion", "wire.modelSuffixMode",
   "auth.mode", "auth.transport",
   "responses.stateful", "responses.upstreamStreaming", "responses.serviceTier", "responses.fastWireKind", "responses.fastWireValue", "responses.snapshotRepair", "responses.itemIdRepair",
   "limits.contextWindow", "limits.maxInputTokens", "limits.maxOutputTokens",

package/src/lib/abort.ts

@@ -144,3 +144,39 @@ export function cancelBodyOnAbort(body: ReadableStream<Uint8Array> | null, signa
   signal.addEventListener("abort", onAbort, { once: true });
   return () => signal.removeEventListener("abort", onAbort);
 }
+
+/**
+ * Compose multiple AbortSignals into a single signal that aborts when ANY input
+ * aborts. Uses `AbortSignal.any` when available (Node >=20.3 / Bun >=1.0);
+ * falls back to a manual implementation for older runtimes.
+ *
+ * The caller gets a `cleanup` alongside the signal and must call it once the
+ * work it guards has settled. `{ once: true }` only removes a listener that
+ * actually fired, so on the polyfill path a long-lived parent signal - a proxy
+ * session's, say - accumulates one listener per request until it aborts or the
+ * process exits. `signalWithTimeout` in this file has always had that
+ * discipline; this function did not.
+ */
+export function anySignal(signals: AbortSignal[]): { signal: AbortSignal; cleanup: () => void } {
+  const builtin = (AbortSignal as unknown as { any?: (s: AbortSignal[]) => AbortSignal }).any;
+  if (typeof builtin === "function") return { signal: builtin(signals), cleanup: () => {} };
+  const controller = new AbortController();
+  const listeners: Array<[AbortSignal, () => void]> = [];
+  const cleanup = (): void => {
+    for (const [source, handler] of listeners.splice(0)) source.removeEventListener("abort", handler);
+  };
+  const onAbort = (reason: unknown): void => {
+    if (!controller.signal.aborted) controller.abort(reason);
+    cleanup();
+  };
+  for (const s of signals) {
+    if (s.aborted) {
+      onAbort(s.reason);
+      break;
+    }
+    const handler = () => onAbort(s.reason);
+    listeners.push([s, handler]);
+    s.addEventListener("abort", handler);
+  }
+  return { signal: controller.signal, cleanup };
+}

package/src/lib/local-destinations.ts

@@ -7,7 +7,7 @@
  * 1. `localManagementOrigin` — authenticated management discovery/state (`/api/*`). It is
  *    served by the public listener and, on a hub, additionally by the loopback-only
  *    `hub.managementIngress`. Callers must still send a management credential: management
- *    authentication has no loopback bypass (structure/05), and the unauthenticated loopback
+ *    authentication has no loopback bypass (structure/gui-and-management-api.md), and the unauthenticated loopback
  *    listener deliberately does not serve `/api/*` at all.
  * 2. `localInferenceDestination` — the data plane a client wire actually speaks.
  *

package/src/lib/upstream-retry.ts

@@ -16,6 +16,39 @@
  */
 import { clearableDeadline } from "./abort";
 
+/**
+ * Responses the origin may already be executing. RFC 9110 §9.2.2 forbids an intermediary
+ * from automatically repeating a non-idempotent request; when a post-send transport (the
+ * Codex WebSocket relay) settles a gateway status because the origin never acknowledged the
+ * turn, the request body must not be sent again by this process — not by the transient-5xx
+ * layer below, not by a pool account rotation, not by a combo hop. The status is returned
+ * to the caller so the user agent can apply its own retry policy, exactly as it does on the
+ * direct path. The WeakSet is the in-process marker; the structured error codes are the
+ * marker that survives body re-wrapping (combo failure consumption re-parses the JSON).
+ */
+const nonReplayableResponses = new WeakSet<Response>();
+
+export function markResponseNonReplayable(response: Response): void {
+  nonReplayableResponses.add(response);
+}
+
+export function isNonReplayableResponse(response: Response): boolean {
+  return nonReplayableResponses.has(response);
+}
+
+/** Origin never produced a response event; the turn may still be executing. */
+export const UPSTREAM_NO_RESPONSE_CODE = "upstream_no_response";
+/** Transport closed after the send, before any response event. */
+export const UPSTREAM_CLOSED_BEFORE_RESPONSE_CODE = "upstream_closed_before_response";
+const NON_REPLAYABLE_UPSTREAM_CODES: ReadonlySet<string> = new Set([
+  UPSTREAM_NO_RESPONSE_CODE,
+  UPSTREAM_CLOSED_BEFORE_RESPONSE_CODE,
+]);
+
+export function isNonReplayableUpstreamCode(code: unknown): boolean {
+  return typeof code === "string" && NON_REPLAYABLE_UPSTREAM_CODES.has(code);
+}
+
 // 1 initial + 2 retries: the pool may hold more than one stale socket.
 const RESET_RETRY_MAX_ATTEMPTS = 3;
 const RESET_RETRY_BASE_DELAY_MS = 150;
@@ -395,7 +428,9 @@ export async function fetchWithTransientRetry(
   let attemptStart = Date.now();
   let res = await fetchWithResetRetry(countedFetch, { ...opts, attempts: remaining() });
   for (let attempt = 0; sent < budget; attempt++) {
-    if (res.ok || !isTransientUpstreamStatus(res.status)) return res;
+    // A non-replayable gateway status was settled after the request body had already left
+    // for the origin; retrying it here is the automatic resend the marker exists to forbid.
+    if (res.ok || !isTransientUpstreamStatus(res.status) || isNonReplayableResponse(res)) return res;
     // Checked before cancelResponseBodyBestEffort so an already-aborted caller never receives
     // a response whose body we just cancelled.
     if (opts.abortSignal?.aborted) return res;

package/src/oauth/account-quota-rank.ts

@@ -67,6 +67,17 @@ function headroomOf(provider: string, accountId: string): number | null {
   return 100 - Math.max(...percents);
 }
 
+/**
+ * Remaining headroom percent for one account, or null when nothing has measured it.
+ *
+ * Exported for the generic fill-first threshold, which needs the measurement itself rather
+ * than an ordering. Null stays null all the way out: a caller must decide what "unmeasured"
+ * means for its own rule instead of being handed a fabricated 0 or 100.
+ */
+export function accountHeadroomPercent(provider: string, accountId: string): number | null {
+  return headroomOf(provider, accountId);
+}
+
 /** Unknown usage is not exhaustion; Kiro's explicit overage verdict is authoritative. */
 export function isAccountQuotaExhausted(provider: string, accountId: string): boolean {
   const exhaustion = provider === "kiro" ? getKiroAccountExhaustion(`${provider}\u0000${accountId}`) : null;

package/src/oauth/callback-server.ts

@@ -37,6 +37,14 @@ function errorHtml(message: string): string {
 
 export type CallbackResult = { code: string; state: string };
 
+/** Close every response so pooled sockets cannot send the next login to a retired flow. */
+function closingResponse(body: string, status: number, contentType = "text/html"): Response {
+  return new Response(body, {
+    status,
+    headers: { "Content-Type": contentType, "Connection": "close" },
+  });
+}
+
 /**
  * The redirect URI advertised to providers must stay `localhost` (it is what the OAuth
  * apps have registered), but Windows commonly resolves `localhost` to `::1` first while
@@ -177,7 +185,7 @@ export abstract class OAuthCallbackFlow {
   #handleCallback(req: Request, expectedState: string): Response {
     const url = new URL(req.url);
     if (url.pathname !== this.callbackPath) {
-      return new Response("Not Found", { status: 404 });
+      return closingResponse("Not Found", 404, "text/plain");
     }
 
     const code = url.searchParams.get("code");
@@ -214,10 +222,7 @@ export abstract class OAuthCallbackFlow {
       });
     }
 
-    return new Response(ok ? SUCCESS_HTML : errorHtml(errMessage), {
-      status: ok ? 200 : consumeFlow ? 500 : 400,
-      headers: { "Content-Type": "text/html" },
-    });
+    return closingResponse(ok ? SUCCESS_HTML : errorHtml(errMessage), ok ? 200 : consumeFlow ? 500 : 400);
   }
 
   #waitForCallback(expectedState: string): Promise<CallbackResult> {

package/src/oauth/devin/api-base.ts

@@ -0,0 +1,63 @@
+/**
+ * Allowlist for the Cognition/Devin api-server origin.
+ *
+ * RegisterUser returns the tenant's api-server host, and that host then receives
+ * GetUserJwt, GetCascadeModelConfigs and GetChatMessage - the first of which
+ * carries the long-lived api_key. A host taken from the network without
+ * validation turns a spoofed or compromised RegisterUser response into
+ * credential exfiltration, so every value that reaches a request URL or the
+ * credential store passes through here first.
+ *
+ * This lives in its own module rather than in `../devin.ts` because the
+ * credential store imports the validator and `../devin.ts` imports the store's
+ * sibling types; a shared leaf keeps that from becoming a cycle.
+ */
+
+export const DEVIN_DEFAULT_API_SERVER = "https://server.codeium.com";
+
+/**
+ * Return the normalized api-server base URL, or undefined when the input is not
+ * an allowlisted Cognition host.
+ *
+ * Unlike the Copilot equivalent this keeps the path. EU and FedStart tenants are
+ * reached at `https://eu.windsurf.com/_route/api_server`, so the path prefix is
+ * part of the address rather than decoration, and normalizing to the origin
+ * would silently point those accounts at the wrong service.
+ */
+export function validateDevinApiBaseUrl(raw: string | undefined | null): string | undefined {
+  if (raw === undefined || raw === null) return undefined;
+  const trimmed = String(raw).trim();
+  if (!trimmed) return undefined;
+  let parsed: URL;
+  try {
+    parsed = new URL(trimmed);
+  } catch {
+    return undefined;
+  }
+  if (parsed.protocol !== "https:") return undefined;
+  if (parsed.username || parsed.password) return undefined;
+  if (parsed.port && parsed.port !== "443") return undefined;
+  if (parsed.search || parsed.hash) return undefined;
+  const host = parsed.hostname.toLowerCase();
+  if (host === "localhost" || host.endsWith(".localhost")) return undefined;
+  if (/^\d{1,3}(\.\d{1,3}){3}$/.test(host) || host.includes(":")) return undefined;
+  const allowed =
+    host === "server.codeium.com" ||
+    // The shipped client (Devin Desktop 3.9.19,
+    // Contents/Resources/app/extensions/windsurf/dist/extension.js) also names
+    // these two, and a beta account's RegisterUser can return one.
+    host === "server-staging.codeium.com" ||
+    host === "server-beta.codeium.com" ||
+    host === "windsurf.com" ||
+    host.endsWith(".windsurf.com") ||
+    host === "windsurf.fedstart.com";
+  if (!allowed) return undefined;
+  const path = parsed.pathname.replace(/\/+$/, "");
+  if (path && !/^(\/[A-Za-z0-9._-]+)+$/.test(path)) return undefined;
+  return `https://${host}${path}`;
+}
+
+/** Same check, falling back to the default US host when the input is unusable. */
+export function resolveDevinApiBaseUrl(raw: string | undefined | null): string {
+  return validateDevinApiBaseUrl(raw) ?? DEVIN_DEFAULT_API_SERVER;
+}

package/src/oauth/devin/login.ts

@@ -0,0 +1 @@
+export { loginDevin } from "../devin";

package/src/oauth/devin/register-user.ts

@@ -0,0 +1,186 @@
+/**
+ * Exchange a Firebase ID token for a long-lived Cognition/Devin API key.
+ *
+ * This calls the same Connect-RPC endpoint the Devin desktop client uses
+ * after browser sign-in completes:
+ *
+ *   POST https://register.windsurf.com/exa.seat_management_pb.SeatManagementService/RegisterUser
+ *   Content-Type: application/json
+ *   Body: { "firebase_id_token": "<jwt>" }
+ *
+ * Connect-RPC happily accepts plain JSON over HTTPS (no gRPC framing required),
+ * so we skip @connectrpc/connect entirely and use `fetch`. The response shape
+ * matches `exa.seat_management_pb.RegisterUserResponse`:
+ *
+ *   { api_key, name, api_server_url, redirect_url, team_options[] }
+ */
+
+import type { OAuthLoginResult, WindsurfRegion } from './types.js';
+import { anySignal } from '../../lib/abort.js';
+import { validateDevinApiBaseUrl } from './api-base.js';
+
+interface RegisterUserResponseJson {
+  api_key?: string;
+  name?: string;
+  api_server_url?: string;
+  redirect_url?: string;
+  team_options?: unknown[];
+}
+
+interface ConnectErrorJson {
+  code?: string;
+  message?: string;
+}
+
+export class WindsurfRegistrationError extends Error {
+  readonly status: number;
+  readonly connectCode?: string;
+  readonly traceId?: string;
+
+  constructor(message: string, status: number, connectCode?: string, traceId?: string) {
+    super(message);
+    this.name = 'WindsurfRegistrationError';
+    this.status = status;
+    this.connectCode = connectCode;
+    this.traceId = traceId;
+  }
+}
+
+const TRACE_ID_RE = /\(trace ID: ([0-9a-f]+)\)/i;
+
+/**
+ * Connect error codes that are safe to repeat to the user.
+ *
+ * The message body is not: a Connect error can echo the request, and the
+ * request here is the Firebase ID token. That message reaches CLI output and
+ * /api/logs, and redactSecretString does not recognise a bare JWT, so the code
+ * is the only part of an error body that leaves this function.
+ */
+const SAFE_CONNECT_CODES = new Set([
+  'canceled', 'unknown', 'invalid_argument', 'deadline_exceeded', 'not_found', 'already_exists',
+  'permission_denied', 'resource_exhausted', 'failed_precondition', 'aborted', 'out_of_range',
+  'unimplemented', 'internal', 'unavailable', 'data_loss', 'unauthenticated',
+]);
+
+function safeConnectCode(value: unknown): string | undefined {
+  return typeof value === 'string' && SAFE_CONNECT_CODES.has(value) ? value : undefined;
+}
+
+/**
+ * Exchange the Firebase ID token for a Windsurf API key.
+ *
+ * `firebaseIdToken` is the `access_token` (or `firebase_id_token`) value the
+ * Windsurf sign-in page returns in the OAuth callback URL — we treat it as
+ * opaque.
+ */
+export async function registerUser(
+  firebaseIdToken: string,
+  region: WindsurfRegion,
+  abortSignal?: AbortSignal,
+): Promise<OAuthLoginResult> {
+  if (!firebaseIdToken) {
+    throw new WindsurfRegistrationError('Empty firebase_id_token', 0, 'invalid_argument');
+  }
+
+  // The register host reaches the network holding the Firebase ID token, so it
+  // passes the same allowlist as the api-server host rather than being trusted
+  // because it came from a config object.
+  const registerBase = validateDevinApiBaseUrl(region.registerApiServerUrl);
+  if (!registerBase) {
+    throw new WindsurfRegistrationError(
+      'Refusing to send the sign-in token to a non-Cognition register host.',
+      0,
+      'permission_denied',
+    );
+  }
+  const url = `${registerBase}/exa.seat_management_pb.SeatManagementService/RegisterUser`;
+
+  // 30s internal timeout — RegisterUser responds in ~200ms in steady state.
+  // CLI users on flaky networks need bounded waits or the sign-in command
+  // hangs forever. Compose with the caller's signal via a small polyfill
+  // (`anySignal`) because Node 18 / older Bun lack AbortSignal.any; the
+  // previous fallback `combinedSignal = abortSignal` would drop the
+  // timeout entirely on those runtimes.
+  const timeoutSignal = AbortSignal.timeout(30_000);
+  const composed = abortSignal ? anySignal([abortSignal, timeoutSignal]) : undefined;
+  const combinedSignal: AbortSignal = composed?.signal ?? timeoutSignal;
+
+  let response: Response;
+  try {
+    response = await fetch(url, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      // Connect protocol version header — not strictly required for JSON, but
+      // matches what the official Connect clients send and avoids accidental
+      // routing into a non-Connect HTTP handler.
+      'Connect-Protocol-Version': '1',
+    },
+    body: JSON.stringify({ firebase_id_token: firebaseIdToken }),
+    // A 307/308 would replay this POST, and its body is the sign-in token, at
+    // whatever host Location names. Fail instead of following.
+    redirect: 'error',
+    signal: combinedSignal,
+    });
+  } finally {
+    // Detach from the caller's signal; it can outlive this one exchange.
+    composed?.cleanup();
+  }
+
+  const text = await response.text();
+
+  if (!response.ok) {
+    let connectCode: string | undefined;
+    let traceId: string | undefined;
+    try {
+      const errJson = JSON.parse(text) as ConnectErrorJson;
+      connectCode = safeConnectCode(errJson.code);
+      // The trace id is an opaque server identifier and is the one part of the
+      // message worth keeping for a support conversation.
+      traceId = typeof errJson.message === 'string' ? errJson.message.match(TRACE_ID_RE)?.[1] : undefined;
+    } catch {
+      // Non-JSON error body. It stays unread; only the status is reported.
+    }
+    const message = `RegisterUser failed (HTTP ${response.status}${connectCode ? `, ${connectCode}` : ''}${traceId ? `, trace ${traceId}` : ''})`;
+    throw new WindsurfRegistrationError(message, response.status, connectCode, traceId);
+  }
+
+  let parsed: RegisterUserResponseJson;
+  try {
+    parsed = JSON.parse(text) as RegisterUserResponseJson;
+  } catch {
+    throw new WindsurfRegistrationError(
+      // The body is not echoed: a 200 that fails to parse can still contain the
+      // key or the token that produced it.
+      `RegisterUser returned 200 with a body that is not JSON (${text.length} bytes)`,
+      response.status,
+      'internal',
+    );
+  }
+
+  const apiKey = parsed.api_key;
+  // Empty `api_server_url` is normal for single-tenant accounts — the desktop
+  // extension's `getApiServerUrl` helper falls back to the configured default
+  // when this is empty/missing. We mirror that behavior here.
+  const apiServerUrl = parsed.api_server_url && parsed.api_server_url.length > 0
+    ? parsed.api_server_url
+    : 'https://server.codeium.com';
+
+  if (!apiKey) {
+    throw new WindsurfRegistrationError(
+      'RegisterUser returned 200 but api_key was empty',
+      response.status,
+      'malformed_response',
+    );
+  }
+  // `name` is optional in the response — default it instead of failing login.
+  // src/oauth/devin.ts uses it only as a display label for the account email.
+  const name = parsed.name && parsed.name.length > 0 ? parsed.name : 'Devin account';
+
+  return {
+    apiKey,
+    name,
+    apiServerUrl,
+    redirectUrl: parsed.redirect_url,
+  };
+}