docs: improve core API doc coverage for review confidence

- add JSDoc to storage locking/fallback transaction helpers
- add JSDoc to request transformer collaboration/config helpers
- clarify legacy lightweight GPT-5 alias default reasoning behavior

Author: ndycode

lib/request/request-transformer.ts

@@ -263,6 +263,9 @@ export function applyFastSessionDefaults(
 	};
 }
 
+/**
+ * Resolves reasoning settings by layering transformed config with body/provider overrides.
+ */
 function resolveReasoningConfig(
 	modelName: string,
 	modelConfig: ConfigOptions,
@@ -283,6 +286,9 @@ function resolveReasoningConfig(
 	return getReasoningConfig(modelName, mergedConfig);
 }
 
+/**
+ * Picks effective text verbosity with body/provider values taking precedence.
+ */
 function resolveTextVerbosity(
 	modelConfig: ConfigOptions,
 	body: RequestBody,
@@ -296,6 +302,9 @@ function resolveTextVerbosity(
 	);
 }
 
+/**
+ * Resolves include fields and always preserves encrypted reasoning continuity payloads.
+ */
 function resolveInclude(modelConfig: ConfigOptions, body: RequestBody): string[] {
 	const providerOpenAI = body.providerOptions?.openai;
 	const base =
@@ -310,6 +319,9 @@ function resolveInclude(modelConfig: ConfigOptions, body: RequestBody): string[]
 	return include;
 }
 
+/**
+ * Parses a collaboration mode token from env/config text.
+ */
 function parseCollaborationMode(value: string | undefined): CollaborationMode | undefined {
 	if (!value) return undefined;
 	const normalized = value.trim().toLowerCase();
@@ -318,6 +330,9 @@ function parseCollaborationMode(value: string | undefined): CollaborationMode |
 	return undefined;
 }
 
+/**
+ * Extracts plain text from mixed message-content payloads.
+ */
 function extractMessageText(content: unknown): string {
 	if (typeof content === "string") return content;
 	if (!Array.isArray(content)) return "";
@@ -332,6 +347,9 @@ function extractMessageText(content: unknown): string {
 		.join("\n");
 }
 
+/**
+ * Detects active collaboration mode using explicit env overrides first, then prompt hints.
+ */
 function detectCollaborationMode(body: RequestBody): CollaborationMode {
 	const envMode =
 		parseCollaborationMode(process.env.CODEX_COLLABORATION_MODE) ??
@@ -362,6 +380,9 @@ function detectCollaborationMode(body: RequestBody): CollaborationMode {
 	return "unknown";
 }
 
+/**
+ * Removes tools that are only valid in plan mode when the request is not in plan mode.
+ */
 function sanitizePlanOnlyTools(tools: unknown, mode: CollaborationMode): unknown {
 	if (!Array.isArray(tools) || mode === "plan") return tools;
 
@@ -385,6 +406,9 @@ function sanitizePlanOnlyTools(tools: unknown, mode: CollaborationMode): unknown
 	return filtered;
 }
 
+/**
+ * Collects runtime tool names from either direct tool entries or function-wrapped definitions.
+ */
 function extractRuntimeToolNames(tools: unknown): string[] {
 	if (!Array.isArray(tools)) return [];
 
@@ -516,6 +540,10 @@ export function getReasoningConfig(
 	// for better coding assistance unless user explicitly requests "none".
 	// - Canonical GPT-5 Codex defaults to high in stable Codex.
 	// - Legacy GPT-5.3/5.2 Codex aliases default to xhigh for backward compatibility.
+	// - Legacy lightweight aliases (gpt-5-mini / gpt-5-nano) intentionally keep a
+	//   minimal default based on the original alias, even though normalization maps
+	//   them to gpt-5.4 which supports higher efforts. Explicit xhigh requests are
+	//   still honored below via supportsRequestedXhigh.
 	const defaultEffort: ReasoningConfig["effort"] = isCodexMini
 		? "medium"
 		: isGpt5Codex
@@ -557,7 +585,7 @@ export function getReasoningConfig(
 	}
 
 	// Normalize "minimal" to "low" for Codex families
-		// Codex CLI presets are low/medium/high (or xhigh for Codex Max / GPT-5.3/5.2 Codex)
+	// Codex CLI presets are low/medium/high (or xhigh for Codex Max / GPT-5.3/5.2 Codex)
 	if (isCodex && effort === "minimal") {
 		effort = "low";
 	}

lib/storage.ts

@@ -108,6 +108,10 @@ export function formatStorageErrorHint(error: unknown, path: string): string {
 
 let storageMutex: Promise<void> = Promise.resolve();
 
+/**
+ * Serializes storage I/O to keep account file reads/writes lock-step and avoid
+ * cross-request races during migration/seeding flows.
+ */
 function withStorageLock<T>(fn: () => Promise<T>): Promise<T> {
   const previousMutex = storageMutex;
   let releaseLock: () => void;
@@ -669,14 +673,24 @@ export async function loadAccounts(): Promise<AccountStorageV3 | null> {
   return withStorageLock(async () => loadAccountsInternal(saveAccountsUnlocked));
 }
 
+/**
+ * Resolves the global (non-project) account storage path.
+ */
 function getGlobalAccountsStoragePath(): string {
   return join(getConfigDir(), ACCOUNTS_FILE_NAME);
 }
 
+/**
+ * Returns true when project-scoped storage is active and a global fallback is meaningful.
+ */
 function shouldUseProjectGlobalFallback(): boolean {
   return Boolean(currentStoragePath && currentProjectRoot);
 }
 
+/**
+ * Loads account data from global storage as a fallback when project storage is missing.
+ * Returns null for missing/unusable global storage and never throws to callers.
+ */
 async function loadGlobalAccountsFallback(): Promise<AccountStorageV3 | null> {
   if (!shouldUseProjectGlobalFallback() || !currentStoragePath) {
     return null;
@@ -721,6 +735,10 @@ async function loadGlobalAccountsFallback(): Promise<AccountStorageV3 | null> {
   }
 }
 
+/**
+ * Core account-loading routine shared by normal reads and transactional storage handlers.
+ * Handles schema normalization, legacy migration, and optional fallback seeding.
+ */
 async function loadAccountsInternal(
   persistMigration: ((storage: AccountStorageV3) => Promise<void>) | null,
 ): Promise<AccountStorageV3 | null> {
@@ -797,6 +815,10 @@ async function loadAccountsInternal(
   }
 }
 
+/**
+ * Writes account storage without acquiring the outer storage mutex.
+ * Callers must already be inside withStorageLock when using this helper directly.
+ */
 async function saveAccountsUnlocked(storage: AccountStorageV3): Promise<void> {
   const path = getStoragePath();
   const uniqueSuffix = `${Date.now()}.${Math.random().toString(36).slice(2, 8)}`;
@@ -847,6 +869,10 @@ async function saveAccountsUnlocked(storage: AccountStorageV3): Promise<void> {
   }
 }
 
+/**
+ * Executes a read-modify-write transaction under the storage lock and exposes
+ * an unlocked persist callback so nested save operations do not deadlock.
+ */
 export async function withAccountStorageTransaction<T>(
   handler: (
     current: AccountStorageV3 | null,