@code-yeongyu/senpi-ai 2026.11.3-1 → 2026.11.3-3

package/dist/api/anthropic-messages.js

@@ -30,7 +30,8 @@ import { sendWithForcedToolChoiceFallback } from "../utils/tool-choice-fallback.
 import { resolveRootObjectSchema } from "../utils/tool-schema-compat.js";
 import { getCurrentTools, getDeclaredTools, getInitialSystemMessage, hasToolRedefinitions, normalizeContext, resolveTranscript, } from "../utils/transcript.js";
 import { isAnthropicWebSearchReplayBlock, isReplayableAnthropicProviderNativeBlock, } from "./anthropic-native-replay-blocks.js";
-import { logAnthropicRequestShape } from "./anthropic-request-shape-log.js";
+import { logAnthropicRecovery, logAnthropicRequestShape } from "./anthropic-request-shape-log.js";
+import { acceptsThinkingBinding, bindReplayedThinking, isThinkingBindingControlRefusedError, isThinkingBindingMismatchError, replaysSignedThinking, THINKING_BINDING_RECOVERY_DIAGNOSTIC, ThinkingBindingRecovery, thinkingBindingUnrecoverableError, } from "./anthropic-thinking-binding.js";
 import { sanitizeAnthropicToolPairs } from "./anthropic-tool-pairs.js";
 import { demoteToolReferenceReplay, demoteUnavailableToolReferences } from "./anthropic-tool-references.js";
 import { demoteExpiredWebSearchReplay, expiredWebSearchReplayIds, isExpiredWebSearchContentError, } from "./anthropic-web-search-expiry.js";
@@ -951,11 +952,11 @@ export const stream = (model, context, options) => {
                     });
                 }
                 const cacheRetention = resolveCacheRetention(options?.cacheRetention ?? model.cacheRetention, options?.env, "short");
-                const cacheSessionId = cacheRetention === "none" ? undefined : options?.sessionId;
+                const affinityKey = cacheRetention === "none" ? undefined : (options?.sessionAffinityKey ?? options?.sessionId);
                 openClient = () => {
                     client = createClient(model, apiKey, options?.interleavedThinking ?? true, shouldUseFineGrainedToolStreamingBeta(model, normalizedContext), options?.refusalFallbacks !== undefined && configuredBetaHeader(model, options) !== null, optionsHeaders, getAnthropicCompat(model).supportsGzipRequestBody
                         ? withGzipRequestBodies(options?.fetch)
-                        : options?.fetch, copilotDynamicHeaders, cacheSessionId, options?.env, federation);
+                        : options?.fetch, copilotDynamicHeaders, affinityKey, options?.env, federation);
                 };
                 openClient();
             }
@@ -973,9 +974,14 @@ export const stream = (model, context, options) => {
                         expiredSearchIds.add(key.slice(expiredSearchPrefix.length));
                 }
             }
+            const thinkingRecovery = new ThinkingBindingRecovery(fallbackKey);
             let lastSentParams;
             const createRequest = async () => {
-                let params = buildParams(model, normalizedContext, options, unsignedThinkingReplay);
+                const replay = thinkingRecovery.strip(normalizedContext);
+                let params = buildParams(model, replay.context, options, unsignedThinkingReplay, {
+                    bindReplayedThinking: thinkingRecovery.bindingAllowed,
+                    replayedThinkingRemoved: replay.removed,
+                });
                 const nextParams = await options?.onPayload?.(params, model);
                 if (nextParams !== undefined) {
                     params = nextParams;
@@ -1029,6 +1035,30 @@ export const stream = (model, context, options) => {
                 }
                 return newlyExpired.length > 0;
             };
+            const thinkingBindingFailure = (error) => attachProviderDiagnostic(thinkingBindingUnrecoverableError(error), anthropicProviderDiagnosticFromError(error));
+            // senpi#5587: rebuild once on the same model without the signed thinking the API bound elsewhere.
+            const recoverThinkingBinding = async (error) => {
+                const removed = thinkingRecovery.rejectReplayedThinking(normalizedContext.messages);
+                if (removed === 0)
+                    throw thinkingBindingFailure(error);
+                appendAssistantMessageDiagnostic(output, {
+                    type: THINKING_BINDING_RECOVERY_DIAGNOSTIC,
+                    timestamp: Date.now(),
+                    details: {
+                        removedThinkingBlocks: removed,
+                        message: "Retried without earlier reasoning the provider bound to a different conversation.",
+                    },
+                });
+                logAnthropicRecovery(model, "thinking_binding_mismatch", { removedThinkingBlocks: removed });
+                try {
+                    return await createRequest();
+                }
+                catch (retryError) {
+                    if (isThinkingBindingMismatchError(retryError))
+                        throw thinkingBindingFailure(retryError);
+                    throw retryError;
+                }
+            };
             const createRequestDemotingExpiredSearches = async () => {
                 try {
                     return await createRequest();
@@ -1058,6 +1088,14 @@ export const stream = (model, context, options) => {
                                 toolReferenceReplayFallbacks.add(fallbackKey);
                             return createRequest();
                         }
+                        if (isThinkingBindingControlRefusedError(error) &&
+                            thinkingRecovery.bindingAllowed &&
+                            model.compat?.supportsMidConvoEffort !== true) {
+                            thinkingRecovery.refuseBinding();
+                            return createRequest();
+                        }
+                        if (isThinkingBindingMismatchError(error))
+                            return recoverThinkingBinding(error);
                         if (markNewlyExpiredSearches(error))
                             return createRequestDemotingExpiredSearches();
                         throw error;
@@ -1564,7 +1602,7 @@ export const streamSimple = (model, context, options) => {
         thinkingBudgetTokens: Math.min(adjusted.thinkingBudget, Math.max(0, maxTokens - 1024)),
     });
 };
-function createClient(model, apiKey, interleavedThinking, useFineGrainedToolStreamingBeta, useServerSideFallbackBeta, optionsHeaders, fetch, dynamicHeaders, sessionId, env, federation) {
+function createClient(model, apiKey, interleavedThinking, useFineGrainedToolStreamingBeta, useServerSideFallbackBeta, optionsHeaders, fetch, dynamicHeaders, affinityKey, env, federation) {
     // Adaptive thinking models have interleaved thinking built in, so skip the beta header.
     const needsInterleavedBeta = interleavedThinking && !supportsAdaptiveThinking(model);
     const betaFeatures = [];
@@ -1614,11 +1652,11 @@ function createClient(model, apiKey, interleavedThinking, useFineGrainedToolStre
     // API key, header-owned auth, or workload identity federation.
     const affinityCompat = getAnthropicCompat(model);
     const sessionAffinityHeaders = {};
-    if (sessionId && affinityCompat.sendSessionAffinityHeaders) {
+    if (affinityKey && affinityCompat.sendSessionAffinityHeaders) {
         // OpenRouter routes prompt-cache affinity through its own header name and
         // rejects x-session-affinity (earendil-works/pi#9102).
         const header = affinityCompat.sessionAffinityFormat === "openrouter" ? "x-session-id" : "x-session-affinity";
-        sessionAffinityHeaders[header] = sessionId;
+        sessionAffinityHeaders[header] = affinityKey;
     }
     const defaultHeaders = sanitizeAdaptiveThinkingHeaders(model, mergeClientHeaders(model, {
         accept: "application/json",
@@ -1715,7 +1753,7 @@ function defaultOptionalBetas(model, context, options) {
         features.push(SERVER_SIDE_FALLBACK_BETA);
     return features;
 }
-function buildParams(model, context, options, unsignedThinkingReplay = getAnthropicCompat(model).unsignedThinkingReplay) {
+function buildParams(model, context, options, unsignedThinkingReplay = getAnthropicCompat(model).unsignedThinkingReplay, replay = { bindReplayedThinking: false, replayedThinkingRemoved: false }) {
     const compat = getAnthropicCompat(model);
     const { cacheControl } = getCacheControl(model, options?.cacheRetention ?? model.cacheRetention, options?.env);
     const initialSystemMessage = getInitialSystemMessage(context.messages);
@@ -1766,9 +1804,17 @@ function buildParams(model, context, options, unsignedThinkingReplay = getAnthro
     const deferredToolNames = new Set(deferredTools.map((tool) => tool.name));
     const activeEffort = managedEffortForRequest(model, options) ?? "high";
     const sendFallbacks = options?.refusalFallbacks !== undefined && !betasSuppressed;
+    // senpi#5587: any Claude request replaying signed thinking asks the API to drop a block bound elsewhere.
+    const bindsReplayedThinking = !midConvoEffort &&
+        !betasSuppressed &&
+        replay.bindReplayedThinking &&
+        options?.thinkingEnabled === true &&
+        model.reasoning &&
+        acceptsThinkingBinding(model) &&
+        replaysSignedThinking(conversationMessages);
     const betaFeatures = getBetaFeatures(model, context, {
         midConvoEffort,
-        thinkingBinding: midConvoEffort && options?.thinkingEnabled !== false,
+        thinkingBinding: (midConvoEffort && options?.thinkingEnabled !== false) || bindsReplayedThinking,
         nativeToolChanges,
         refusalFallbacks: sendFallbacks,
     }, options);
@@ -1882,9 +1928,11 @@ function buildParams(model, context, options, unsignedThinkingReplay = getAnthro
     // cache - degrading here re-wrote the whole cached prefix on each tool
     // continuation (the "cache misses every second prompt" report).
     if (params.thinking?.type === "enabled" &&
-        finalAssistantTurnIsForeign(context.messages) &&
+        (finalAssistantTurnIsForeign(context.messages) || replay.replayedThinkingRemoved) &&
         finalAssistantTurnStartsWithToolUse(params.messages))
         disableThinkingForRequest(params, model, compat);
+    if (bindsReplayedThinking)
+        bindReplayedThinking(params);
     if (options?.metadata) {
         const userId = options.metadata.user_id;
         if (typeof userId === "string") {

package/dist/api/anthropic-request-shape-log.d.ts

@@ -20,5 +20,10 @@ export declare function logAnthropicRequestShape(model: {
 }, params: {
     readonly messages?: unknown;
 }, env?: Readonly<Record<string, string | undefined>>, appendFile?: AppendFile | undefined): void;
+/** One line per request rebuilt after a provider rejection, beside the skeletons of both attempts. */
+export declare function logAnthropicRecovery(model: {
+    readonly provider: string;
+    readonly id: string;
+}, recovery: string, details: Readonly<Record<string, number>>, env?: Readonly<Record<string, string | undefined>>): void;
 export {};
 //# sourceMappingURL=anthropic-request-shape-log.d.ts.map

package/dist/api/anthropic-request-shape-log.js

@@ -47,4 +47,15 @@ export function logAnthropicRequestShape(model, params, env = processEnv(), appe
     };
     append(path, `${JSON.stringify(record)}\n`);
 }
+/** One line per request rebuilt after a provider rejection, beside the skeletons of both attempts. */
+export function logAnthropicRecovery(model, recovery, details, env = processEnv()) {
+    const path = env[REQUEST_SHAPE_LOG_ENV];
+    if (path === undefined || path.length === 0)
+        return;
+    const append = resolveAppendFile();
+    if (append === undefined)
+        return;
+    const record = { ts: new Date().toISOString(), provider: model.provider, model: model.id, recovery, ...details };
+    append(path, `${JSON.stringify(record)}\n`);
+}
 //# sourceMappingURL=anthropic-request-shape-log.js.map

package/dist/api/anthropic-thinking-binding.d.ts

@@ -0,0 +1,28 @@
+import type { Context, Message, Model } from "../types.ts";
+export declare const THINKING_BINDING_RECOVERY_DIAGNOSTIC = "anthropic_thinking_binding_recovery";
+export declare function isThinkingBindingMismatchError(error: unknown): error is Error;
+export declare function isThinkingBindingMismatchText(text: string): boolean;
+/** A 400 refusing the binding control itself, as opposed to the mismatch it guards against. */
+export declare function isThinkingBindingControlRefusedError(error: unknown): error is Error;
+/** The binding controls are an Anthropic API feature: only Claude models, on any route that serves them. */
+export declare function acceptsThinkingBinding(model: Pick<Model<"anthropic-messages">, "id">): boolean;
+export declare function replaysSignedThinking(messages: readonly Message[]): boolean;
+export declare function bindReplayedThinking<T extends {
+    thinking?: unknown;
+}>(params: T): void;
+export declare class ThinkingBindingRecovery {
+    private readonly localTurns;
+    private localBindingRefused;
+    private readonly sessionKey;
+    constructor(sessionKey: string | undefined);
+    get bindingAllowed(): boolean;
+    refuseBinding(): void;
+    private isRejected;
+    rejectReplayedThinking(messages: readonly Message[]): number;
+    strip<C extends Context>(context: C): {
+        context: C;
+        removed: boolean;
+    };
+}
+export declare function thinkingBindingUnrecoverableError(cause: Error): Error;
+//# sourceMappingURL=anthropic-thinking-binding.d.ts.map

package/dist/api/anthropic-thinking-binding.js

@@ -0,0 +1,141 @@
+import { registerSessionResourceCleanup } from "../session-resources.js";
+/**
+ * A signed `thinking` block is bound to the conversation prefix it was minted under (senpi#5587). History
+ * that carries a block from another prefix (a restored or transplanted transcript, a route that served an
+ * earlier turn from another account) is refused before the first token:
+ * "messages.1.content.0: Invalid `signature` in `thinking` block. The block is bound to a different
+ * conversation." The block is stored in the session, so every replay repeats the refusal.
+ *
+ * Two layers keep such a session usable:
+ * - Where the API accepts it, a request that replays signed thinking asks the API to drop a mismatched
+ *   block (`thinking.block_binding.prefix_mismatch_behavior: "drop_block"`).
+ * - On exactly this 400 the request is rebuilt once, on the same model, without the replayed signed
+ *   thinking; user text, tool calls and tool results are untouched. The removed turns are remembered per
+ *   session, base URL and model, so later turns stay consistent with the prefix the retry was answered
+ *   under and do not hit the 400 again.
+ */
+const BOUND_TO_DIFFERENT_CONVERSATION = /Invalid `signature` in `thinking` block\. The block is bound to a different conversation/i;
+// A transport that does not know the binding controls names the field or the beta in its 400.
+const BINDING_CONTROL_NAMED = /block_binding|thinking-binding-controls/i;
+export const THINKING_BINDING_RECOVERY_DIAGNOSTIC = "anthropic_thinking_binding_recovery";
+function statusOf(error) {
+    return typeof error === "object" && error !== null && "status" in error
+        ? error.status
+        : undefined;
+}
+export function isThinkingBindingMismatchError(error) {
+    return error instanceof Error && statusOf(error) === 400 && BOUND_TO_DIFFERENT_CONVERSATION.test(error.message);
+}
+export function isThinkingBindingMismatchText(text) {
+    return BOUND_TO_DIFFERENT_CONVERSATION.test(text);
+}
+/** A 400 refusing the binding control itself, as opposed to the mismatch it guards against. */
+export function isThinkingBindingControlRefusedError(error) {
+    return (error instanceof Error &&
+        statusOf(error) === 400 &&
+        BINDING_CONTROL_NAMED.test(error.message) &&
+        !BOUND_TO_DIFFERENT_CONVERSATION.test(error.message));
+}
+/** The binding controls are an Anthropic API feature: only Claude models, on any route that serves them. */
+export function acceptsThinkingBinding(model) {
+    return /claude/i.test(model.id);
+}
+function signedThinkingCount(message) {
+    if (message.role !== "assistant")
+        return 0;
+    let count = 0;
+    for (const block of message.content) {
+        if (block.type === "thinking" && (block.thinkingSignature?.length ?? 0) > 0)
+            count++;
+    }
+    return count;
+}
+export function replaysSignedThinking(messages) {
+    return messages.some((message) => signedThinkingCount(message) > 0);
+}
+export function bindReplayedThinking(params) {
+    const thinking = params.thinking;
+    if (typeof thinking !== "object" || thinking === null)
+        return;
+    const config = thinking;
+    if (config.type !== "adaptive" && config.type !== "enabled")
+        return;
+    if (config.block_binding !== undefined)
+        return;
+    params.thinking = { ...config, block_binding: { prefix_mismatch_behavior: "drop_block" } };
+}
+// `${sessionKey}\u0000${messageKey}` of assistant turns whose signed thinking was removed after this 400.
+const rejectedThinkingTurns = new Set();
+// Session keys whose transport refused the binding controls.
+const bindingRefusedSessions = new Set();
+registerSessionResourceCleanup((sessionId) => {
+    if (sessionId === undefined) {
+        rejectedThinkingTurns.clear();
+        bindingRefusedSessions.clear();
+        return;
+    }
+    const prefix = `${sessionId}\u0000`;
+    for (const keys of [rejectedThinkingTurns, bindingRefusedSessions]) {
+        for (const key of keys) {
+            if (key.startsWith(prefix))
+                keys.delete(key);
+        }
+    }
+});
+function turnKey(message) {
+    return message.role === "assistant" ? (message.responseId ?? `${message.model}@${message.timestamp}`) : "";
+}
+export class ThinkingBindingRecovery {
+    constructor(sessionKey) {
+        this.localTurns = new Set();
+        this.localBindingRefused = false;
+        this.sessionKey = sessionKey;
+    }
+    get bindingAllowed() {
+        if (this.localBindingRefused)
+            return false;
+        return this.sessionKey === undefined || !bindingRefusedSessions.has(this.sessionKey);
+    }
+    refuseBinding() {
+        this.localBindingRefused = true;
+        if (this.sessionKey !== undefined)
+            bindingRefusedSessions.add(this.sessionKey);
+    }
+    isRejected(message) {
+        const key = turnKey(message);
+        if (this.localTurns.has(key))
+            return true;
+        return this.sessionKey !== undefined && rejectedThinkingTurns.has(`${this.sessionKey}\u0000${key}`);
+    }
+    rejectReplayedThinking(messages) {
+        let blocks = 0;
+        for (const message of messages) {
+            const count = signedThinkingCount(message);
+            if (count === 0 || this.isRejected(message))
+                continue;
+            blocks += count;
+            const key = turnKey(message);
+            this.localTurns.add(key);
+            if (this.sessionKey !== undefined)
+                rejectedThinkingTurns.add(`${this.sessionKey}\u0000${key}`);
+        }
+        return blocks;
+    }
+    strip(context) {
+        let removed = false;
+        const messages = context.messages.map((message) => {
+            if (message.role !== "assistant" || signedThinkingCount(message) === 0 || !this.isRejected(message)) {
+                return message;
+            }
+            removed = true;
+            const content = message.content.filter((block) => !(block.type === "thinking" && (block.thinkingSignature?.length ?? 0) > 0));
+            return { ...message, content };
+        });
+        return removed ? { context: { ...context, messages }, removed } : { context, removed };
+    }
+}
+export function thinkingBindingUnrecoverableError(cause) {
+    const error = new Error(`Anthropic rejected this session's earlier reasoning as bound to a different conversation, and the request rebuilt without it was rejected too. Start a new session to continue. (${cause.message})`, { cause });
+    return Object.assign(error, { status: 400 });
+}
+//# sourceMappingURL=anthropic-thinking-binding.js.map

package/dist/api/lazy.js

@@ -1,9 +1,11 @@
+import { readProviderDiagnostic } from "../provider-diagnostic.js";
 import { assistantEvents, pushAssistantProgress, setAssistantReader } from "../utils/assistant-capture.js";
 import { AssistantMessageEventStream } from "../utils/event-stream.js";
 import { isOAuthRefreshUnavailableError } from "../utils/oauth-refresh-error.js";
 import { describeReplacedInstall } from "../utils/provider-failure-description.js";
 import { OAUTH_REFRESH_UNAVAILABLE_DIAGNOSTIC } from "../utils/retry.js";
 function createSetupErrorMessage(model, error) {
+    const providerDiagnostic = readProviderDiagnostic(error);
     return {
         role: "assistant",
         content: [],
@@ -20,6 +22,7 @@ function createSetupErrorMessage(model, error) {
         },
         stopReason: "error",
         errorMessage: describeReplacedInstall(error) ?? (error instanceof Error ? error.message : String(error)),
+        ...(providerDiagnostic === undefined ? {} : { providerDiagnostic }),
         ...(isOAuthRefreshUnavailableError(error)
             ? {
                 diagnostics: [

package/dist/api/simple-options.js

@@ -118,6 +118,7 @@ export function buildBaseOptions(model, context, options, apiKey) {
         transport: options?.transport,
         cacheRetention: options?.cacheRetention ?? model.cacheRetention,
         sessionId: options?.sessionId,
+        sessionAffinityKey: options?.sessionAffinityKey,
         headers: options?.headers,
         extraBody: options?.extraBody,
         onPayload: options?.onPayload,

package/dist/auth/oauth/openai-chatgpt.d.ts

@@ -4,6 +4,30 @@
  * This public-client flow uses no client secret and sends the resulting user
  * access token directly to api.openai.com.
  */
-import type { OAuthAuth } from "../types.ts";
-export declare const openaiChatGPTOAuth: OAuthAuth;
+import type { LoginOptions, LogoutOptions, OAuthCredential, OAuthRevocationResult, ProviderAuthInteraction } from "../types.ts";
+declare function refreshAccessToken(credential: OAuthCredential, signal: AbortSignal): Promise<OAuthCredential>;
+declare function revokeSession(credential: OAuthCredential, options?: LogoutOptions): Promise<OAuthRevocationResult>;
+declare function loginOpenAIChatGPT(interaction: ProviderAuthInteraction, options?: LoginOptions & {
+    readonly preferredCallbackPort?: number;
+}): Promise<OAuthCredential>;
+export declare const openaiChatGPTOAuth: {
+    name: string;
+    isSubscription: true;
+    loginLabel: string;
+    login: typeof loginOpenAIChatGPT;
+    refresh: typeof refreshAccessToken;
+    revoke: typeof revokeSession;
+    check({ credential }: {
+        ctx: import("../types.ts").AuthContext;
+        credential?: OAuthCredential;
+        signal: AbortSignal;
+    }): Promise<{
+        type: "oauth";
+        source: string;
+    } | undefined>;
+    toAuth(credential: OAuthCredential): Promise<{
+        apiKey: string;
+    }>;
+};
+export {};
 //# sourceMappingURL=openai-chatgpt.d.ts.map

package/dist/auth/oauth/openai-chatgpt.js

@@ -6,9 +6,8 @@
  */
 import { randomBytes } from "node:crypto";
 import { createServer } from "node:http";
-import { oauthErrorHtml, oauthSuccessHtml } from "../../utils/oauth-page.js";
+import { configuredOAuthBrandName, oauthErrorHtml, oauthSuccessHtml } from "../../utils/oauth-page.js";
 import { OAuthTokenEndpointError } from "../../utils/oauth-refresh-error.js";
-import { getProviderEnvValue } from "../../utils/provider-env.js";
 import { getWireIdentity } from "../../wire-identity.js";
 import { generatePKCE } from "./pkce.js";
 // every login registers a new client with this ID; OpenAI returns the issued client ID in the callback
@@ -18,7 +17,7 @@ const AUTHORIZE_URL = "https://auth.openai.com/api/accounts/authorize";
 const TOKEN_URL = "https://auth.openai.com/api/accounts/oauth/token";
 const DISCOVERY_URL = "https://auth.openai.com/.well-known/openid-configuration";
 const RESOURCE = "https://api.openai.com/v1";
-const CALLBACK_HOST = getProviderEnvValue("PI_OAUTH_CALLBACK_HOST") || "127.0.0.1";
+const CALLBACK_HOST = "127.0.0.1";
 const CALLBACK_PORT = 1455;
 const CALLBACK_PATH = "/auth/callback";
 const REDIRECT_URI = `http://127.0.0.1:${CALLBACK_PORT}${CALLBACK_PATH}`;
@@ -43,7 +42,7 @@ function authorizationResultFromCallback(url, expectedState) {
         throw new Error("OpenAI OAuth registration callback did not contain an issued client ID");
     return { code, clientId };
 }
-function authorizationResultFromManualInput(input, expectedState) {
+function authorizationResultFromManualInput(input, expectedState, redirectUri) {
     let url;
     try {
         url = new URL(input.trim());
@@ -51,9 +50,9 @@ function authorizationResultFromManualInput(input, expectedState) {
     catch {
         throw new Error("Paste the full callback URL from the browser");
     }
-    const expected = new URL(REDIRECT_URI);
+    const expected = new URL(redirectUri);
     if (url.origin !== expected.origin || url.pathname !== expected.pathname) {
-        throw new Error(`The pasted callback URL must start with ${REDIRECT_URI}`);
+        throw new Error(`The pasted callback URL must start with ${redirectUri}`);
     }
     const error = url.searchParams.get("error");
     if (error)
@@ -64,8 +63,9 @@ function sendHtml(response, status, body) {
     response.writeHead(status, { "Content-Type": "text/html; charset=utf-8" });
     response.end(body);
 }
-function startCallbackServer(expectedState) {
+function startCallbackServer(expectedState, preferredPort) {
     return new Promise((resolve, reject) => {
+        let redirectUri = REDIRECT_URI;
         let resolveResult;
         let rejectResult;
         const result = new Promise((resolveAuthorization, rejectAuthorization) => {
@@ -74,7 +74,7 @@ function startCallbackServer(expectedState) {
         });
         const server = createServer((request, response) => {
             try {
-                const url = new URL(request.url || "", REDIRECT_URI);
+                const url = new URL(request.url || "", redirectUri);
                 if (url.pathname !== CALLBACK_PATH) {
                     sendHtml(response, 404, oauthErrorHtml("Callback route not found."));
                     return;
@@ -101,12 +101,30 @@ function startCallbackServer(expectedState) {
                 sendHtml(response, 500, oauthErrorHtml("Internal error while processing the callback."));
             }
         });
-        server.once("error", reject);
-        server.listen(CALLBACK_PORT, CALLBACK_HOST, () => {
+        const onListening = () => {
+            server.removeListener("error", onBindError);
             server.removeListener("error", reject);
+            const address = server.address();
+            if (!address || typeof address === "string") {
+                server.close();
+                reject(new Error("OpenAI OAuth callback server did not bind to TCP"));
+                return;
+            }
+            redirectUri = `http://${CALLBACK_HOST}:${address.port}${CALLBACK_PATH}`;
             server.on("error", rejectResult);
-            resolve({ server, result });
-        });
+            resolve({ server, result, redirectUri });
+        };
+        const onBindError = (error) => {
+            server.removeListener("listening", onListening);
+            if (error.code !== "EADDRINUSE") {
+                reject(error);
+                return;
+            }
+            server.once("error", reject);
+            server.listen(0, CALLBACK_HOST, onListening);
+        };
+        server.once("error", onBindError);
+        server.listen(preferredPort, CALLBACK_HOST, onListening);
     });
 }
 async function requestToken(body, signal) {
@@ -155,13 +173,13 @@ function credentialFromTokenResponse(token, clientId) {
         scopes,
     };
 }
-async function exchangeAuthorizationCode(code, verifier, clientId, signal) {
+async function exchangeAuthorizationCode(code, verifier, clientId, redirectUri, signal) {
     const token = await requestToken(new URLSearchParams({
         grant_type: "authorization_code",
         client_id: clientId,
         code,
         code_verifier: verifier,
-        redirect_uri: REDIRECT_URI,
+        redirect_uri: redirectUri,
         resource: RESOURCE,
     }), signal);
     // Pi does not use the ID token to identify the user or read profile data.
@@ -267,7 +285,7 @@ async function loginOpenAIChatGPT(interaction, options) {
     const nonce = randomValue();
     let callback;
     try {
-        callback = await startCallbackServer(state);
+        callback = await startCallbackServer(state, options?.preferredCallbackPort ?? CALLBACK_PORT);
     }
     catch (error) {
         interaction.notify({
@@ -275,13 +293,15 @@ async function loginOpenAIChatGPT(interaction, options) {
             message: `Could not listen on ${REDIRECT_URI}; paste the final redirect URL to continue. ${error instanceof Error ? error.message : String(error)}`,
         });
     }
+    const redirectUri = callback?.redirectUri ?? REDIRECT_URI;
     const authorizationUrl = new URL(AUTHORIZE_URL);
     authorizationUrl.search = new URLSearchParams({
         client_id: DYNAMIC_CLIENT_ID,
-        agent_name_hint: options?.appName ?? getWireIdentity(),
+        // Display metadata on OpenAI's consent screen (the user can edit it); not tied to the issued client ID.
+        agent_name_hint: options?.appName ?? configuredOAuthBrandName() ?? getWireIdentity(),
         ext_agent_host_id: hostId,
         response_type: "code",
-        redirect_uri: REDIRECT_URI,
+        redirect_uri: redirectUri,
         resource: RESOURCE,
         scope: SCOPE,
         state,
@@ -299,14 +319,14 @@ async function loginOpenAIChatGPT(interaction, options) {
         .prompt({
         type: "manual_code",
         message: "Complete login in your browser, or paste the final redirect URL here:",
-        placeholder: REDIRECT_URI,
+        placeholder: redirectUri,
         signal: AbortSignal.any([manualAbort.signal, interaction.signal]),
     })
-        .then((input) => authorizationResultFromManualInput(input, state));
+        .then((input) => authorizationResultFromManualInput(input, state, redirectUri));
     try {
         const result = await (callback ? Promise.race([callback.result, manualCode]) : manualCode);
         interaction.notify({ type: "progress", message: "Exchanging authorization code for tokens..." });
-        return await exchangeAuthorizationCode(result.code, verifier, result.clientId, interaction.signal);
+        return await exchangeAuthorizationCode(result.code, verifier, result.clientId, redirectUri, interaction.signal);
     }
     catch (error) {
         if (interaction.signal.aborted)

package/dist/auth/oauth-refresh.d.ts

@@ -9,7 +9,9 @@
  * re-acquires the lock and compare-and-swaps on the slot's refresh token, so a
  * slot rotated meanwhile by another process is adopted instead of overwritten.
  *
- * Within a process, concurrent refreshes of the same slot join one exchange.
+ * Persistent stores inject a session-scoped lock around read/exchange/write so
+ * two processes cannot consume the same rotating token. Within a process,
+ * concurrent refreshes of the same slot join one exchange.
  * Waiters that own the exchange (per-request resolution) cancel it once none of
  * them is waiting; the catalog-refresh lane joins without owning it, so a
  * superseded catalog refresh stops waiting but never aborts the exchange.