Merge remote-tracking branch 'origin/main' into fix/openai-cache-write-tiers

Main's docs cleanup (#4504) moved the prompt caching docs under
per-provider sections; the OpenAI paragraphs now live under
OpenAI models > Prompt Caching.

Co-Authored-By: Claude Opus 5.5 <[email protected]>

src/backend/clients/event/types.ts

@@ -861,6 +861,12 @@ export type EventMap = {
     /** One access token was revoked; only its own connections should drop. */
     'auth.access-token.revoked': { token_uid: string };
 
+    /** Same-cluster eviction for raw realtime WebSockets. */
+    'pubsub.realtime.auth-revoked': {
+        sessionUids?: string[];
+        tokenUid?: string;
+    };
+
     /**
      * A grant was withdrawn, so whatever was standing on it has to be settled
      * rather than left to fail its next check.

src/backend/controllers/puterai/PuterAIController.shapes.test.ts

@@ -201,6 +201,7 @@ describe('PuterAIController.openaiResponses parameter forwarding', () => {
                     context_management: [{ type: 'compaction' }],
                     prompt_cache_key: 'ck',
                     prompt_cache_retention: '24h',
+                    prompt_cache_options: { ttl: '12h', prewarm: true },
                     store: true,
                     truncation: 'auto',
                     service_tier: 'default',
@@ -226,6 +227,9 @@ describe('PuterAIController.openaiResponses parameter forwarding', () => {
             context_management: [{ type: 'compaction' }],
             prompt_cache_key: 'ck',
             prompt_cache_retention: '24h',
+            // Forwarded as sent; the provider keeps only the fields it
+            // accepts.
+            prompt_cache_options: { ttl: '12h', prewarm: true },
             // forced false regardless of the client's request.
             store: false,
             truncation: 'auto',
@@ -359,13 +363,18 @@ describe('PuterAIController.openaiResponses input normalization', () => {
                 role: 'user',
                 content: [
                     'a bare string part',
-                    { type: 'input_text', text: 'typed text' },
+                    {
+                        type: 'input_text',
+                        text: 'typed text',
+                        prompt_cache_breakpoint: { mode: 'explicit', ttl: '12h' },
+                    },
                     { type: 'output_text', text: 'echoed text' },
                     {
                         type: 'input_image',
                         detail: 'high',
                         image_url: 'https://img.test/a.png',
                         file_id: 'file_img',
+                        prompt_cache_breakpoint: { mode: 'explicit' },
                     },
                     { type: 'input_audio', input_audio: { data: 'AAA' } },
                     {
@@ -386,13 +395,18 @@ describe('PuterAIController.openaiResponses input normalization', () => {
                 role: 'user',
                 content: [
                     { type: 'text', text: 'a bare string part' },
-                    { type: 'text', text: 'typed text' },
+                    {
+                        type: 'text',
+                        text: 'typed text',
+                        prompt_cache_breakpoint: { mode: 'explicit', ttl: '12h' },
+                    },
                     { type: 'text', text: 'echoed text' },
                     {
                         type: 'image_url',
                         detail: 'high',
                         image_url: { url: 'https://img.test/a.png' },
                         file_id: 'file_img',
+                        prompt_cache_breakpoint: { mode: 'explicit' },
                     },
                     { type: 'input_audio', input_audio: { data: 'AAA' } },
                     {
@@ -639,6 +653,33 @@ describe('PuterAIController.openaiResponses output items', () => {
 // -- /openai/v1/chat/completions edges -------------------------------
 
 describe('PuterAIController.openaiChatCompletions translation edges', () => {
+    it('forwards the prompt-cache fields to the driver', async () => {
+        const completeSpy = stubChatComplete({
+            message: { role: 'assistant', content: 'ok' },
+        });
+
+        const { res } = makeRes();
+        await controller.openaiChatCompletions(
+            makeReq({
+                body: {
+                    model: 'gpt-test',
+                    messages: [{ role: 'user', content: 'hi' }],
+                    prompt_cache_key: 'ck',
+                    prompt_cache_retention: 'in_memory',
+                    prompt_cache_options: { ttl: '30m' },
+                },
+            }),
+            res,
+        );
+
+        const args = completeSpy.mock.calls[0]![0] as Record<string, unknown>;
+        expect(args).toMatchObject({
+            prompt_cache_key: 'ck',
+            prompt_cache_retention: 'in_memory',
+            prompt_cache_options: { ttl: '30m' },
+        });
+    });
+
     it('derives tool_calls from tool_use content blocks when the message has none', async () => {
         stubChatComplete({
             message: {

src/backend/controllers/puterai/PuterAIController.ts

@@ -447,6 +447,7 @@ export class PuterAIController extends PuterController {
                           body.reasoning_effort as ICompleteArguments['reasoning_effort'],
                   }
                 : {}),
+            ...promptCacheArgsFromBody(body),
             ...openaiCompatProvider(body),
             ...(body.fallback === false ? { fallback: false } : {}),
         };
@@ -842,15 +843,7 @@ export class PuterAIController extends PuterController {
                           body.compaction as ICompleteArguments['compaction'],
                   }
                 : {}),
-            ...(body.prompt_cache_key
-                ? { prompt_cache_key: String(body.prompt_cache_key) }
-                : {}),
-            ...(body.prompt_cache_retention
-                ? {
-                      prompt_cache_retention:
-                          body.prompt_cache_retention as ICompleteArguments['prompt_cache_retention'],
-                  }
-                : {}),
+            ...promptCacheArgsFromBody(body),
             // forced off regardless of what the caller sent — OpenAI
             // defaults `store` to true, which would persist state server-side
             // on OpenAI's end that this route gives no way to retrieve.
@@ -1343,6 +1336,33 @@ const openaiCompatProvider = (
     return { provider: DEFAULTS.openaiChat };
 };
 
+/**
+ * The prompt-cache fields both OpenAI-shaped routes forward as sent; the
+ * provider checks the values.
+ */
+const promptCacheArgsFromBody = (
+    body: Record<string, unknown>,
+): Pick<
+    ICompleteArguments,
+    'prompt_cache_key' | 'prompt_cache_retention' | 'prompt_cache_options'
+> => ({
+    ...(body.prompt_cache_key
+        ? { prompt_cache_key: String(body.prompt_cache_key) }
+        : {}),
+    ...(body.prompt_cache_retention
+        ? {
+              prompt_cache_retention:
+                  body.prompt_cache_retention as ICompleteArguments['prompt_cache_retention'],
+          }
+        : {}),
+    ...(body.prompt_cache_options
+        ? {
+              prompt_cache_options:
+                  body.prompt_cache_options as ICompleteArguments['prompt_cache_options'],
+          }
+        : {}),
+});
+
 const randomId = (): string => crypto.randomUUID().replace(/-/g, '');
 const generateId = (prefix: string): string => `${prefix}_${randomId()}`;
 
@@ -1590,12 +1610,24 @@ const parseJsonMaybe = (value: unknown): unknown => {
     }
 };
 
+/** An OpenAI `prompt_cache_breakpoint` marker, kept on the translated part. */
+const cacheBreakpointOf = (
+    p: Record<string, unknown>,
+): { prompt_cache_breakpoint?: unknown } =>
+    p.prompt_cache_breakpoint && typeof p.prompt_cache_breakpoint === 'object'
+        ? { prompt_cache_breakpoint: p.prompt_cache_breakpoint }
+        : {};
+
 const normalizeContentPart = (part: unknown): Record<string, unknown> => {
     if (typeof part === 'string') return { type: 'text', text: part };
     if (!part || typeof part !== 'object') return { type: 'text', text: '' };
     const p = part as Record<string, unknown>;
     if (p.type === 'input_text' || p.type === 'output_text') {
-        return { type: 'text', text: String(p.text ?? '') };
+        return {
+            type: 'text',
+            text: String(p.text ?? ''),
+            ...cacheBreakpointOf(p),
+        };
     }
     if (p.type === 'input_image') {
         return {
@@ -1603,6 +1635,7 @@ const normalizeContentPart = (part: unknown): Record<string, unknown> => {
             ...(p.detail ? { detail: p.detail } : {}),
             ...(p.image_url ? { image_url: { url: p.image_url } } : {}),
             ...(p.file_id ? { file_id: p.file_id } : {}),
+            ...cacheBreakpointOf(p),
         };
     }
     if (p.type === 'input_audio')
@@ -1614,6 +1647,7 @@ const normalizeContentPart = (part: unknown): Record<string, unknown> => {
             ...(p.file_id ? { file_id: p.file_id } : {}),
             ...(p.file_url ? { file_url: p.file_url } : {}),
             ...(p.filename ? { filename: p.filename } : {}),
+            ...cacheBreakpointOf(p),
         };
     }
     return p;

src/backend/drivers/ai-chat/providers/azure/AzureResponsesProvider.test.ts

@@ -449,6 +449,22 @@ describe('AzureResponsesProvider.complete request shape', () => {
         expect(args.service_tier).toBe('default');
     });
 
+    it('sends the wire spelling of the in-memory cache retention', async () => {
+        const provider = makeProvider();
+        responsesCreateMock.mockResolvedValueOnce(okResponse);
+
+        await withTestActor(() =>
+            provider.complete({
+                model: 'gpt-5.3-codex',
+                messages: [{ role: 'user', content: 'hi' }],
+                prompt_cache_retention: 'in-memory',
+            } as never),
+        );
+
+        const [args] = responsesCreateMock.mock.calls[0]!;
+        expect(args.prompt_cache_retention).toBe('in_memory');
+    });
+
     it.each([
         ['previous_response_id', 'resp_1'],
         ['conversation', 'conv_1'],

src/backend/drivers/ai-chat/providers/azure/AzureResponsesProvider.ts

@@ -35,6 +35,7 @@ import * as OpenAiUtil from '../../utils/OpenAIUtil.js';
 import {
     clampReasoningEffort,
     openAICompatParams,
+    promptCacheRetentionToWire,
     rejectStatefulResponsesFields,
 } from '../../utils/openaiParams.js';
 import { buildCostsOverride } from '../../utils/pricing.js';
@@ -209,6 +210,9 @@ export class AzureResponsesProvider implements IChatProvider {
         const userIdentifier = upstreamUserIdentifier(actor);
         // Cache key defaults to the actor identifier; see upstreamUserIdentifier.
         const cacheKey = prompt_cache_key ?? userIdentifier;
+        const cacheRetention = promptCacheRetentionToWire(
+            prompt_cache_retention,
+        );
 
         // Resolve any `puter_path` content parts into inline base64 data URLs
         // before the Responses API sees them.
@@ -307,8 +311,8 @@ export class AzureResponsesProvider implements IChatProvider {
             ...(instructions !== undefined ? { instructions } : {}),
             ...(metadata !== undefined ? { metadata } : {}),
             ...(cacheKey !== undefined ? { prompt_cache_key: cacheKey } : {}),
-            ...(prompt_cache_retention !== undefined
-                ? { prompt_cache_retention }
+            ...(cacheRetention !== undefined
+                ? { prompt_cache_retention: cacheRetention }
                 : {}),
             ...(store !== undefined ? { store } : {}),
             ...(max_tokens !== undefined

src/backend/drivers/ai-chat/providers/meta/MetaProvider.ts

@@ -23,6 +23,7 @@ import { HttpError } from '../../../../core/http/HttpError.js';
 import type { MeteringService } from '../../../../services/metering/MeteringService.js';
 import { upstreamUserIdentifier } from '../../../util/upstreamIdentifier.js';
 import type { IChatModel, ICompleteArguments } from '../../types.js';
+import { promptCacheRetentionToWire } from '../../utils/openaiParams.js';
 import { sdkClientOptions } from '../../utils/sdkClient.js';
 import {
     type ChatProviderConfig,
@@ -107,12 +108,9 @@ export class MetaProvider extends OpenAICompatProvider {
                 ? requestedEffort
                 : undefined;
 
-        // Puter spells the in-memory retention with a hyphen; Meta's enum
-        // uses an underscore.
-        const cacheRetention =
-            args.prompt_cache_retention === 'in-memory'
-                ? 'in_memory'
-                : args.prompt_cache_retention;
+        const cacheRetention = promptCacheRetentionToWire(
+            args.prompt_cache_retention,
+        );
 
         // The identifier is Puter's abuse attribution, so `custom` can't
         // override it. Cache key defaults to it; see upstreamUserIdentifier.

src/backend/drivers/ai-chat/providers/openai/OpenAiChatCompletionsProvider.test.ts

@@ -249,6 +249,130 @@ describe('OpenAiChatProvider.complete argument validation', () => {
         expect(result).toEqual({ delegated: true });
     });
 
+    it('delegates a 12h cache lifetime to the Responses provider, which is the only API that writes it', async () => {
+        const { provider } = makeProvider();
+        const sibling = {
+            complete: vi.fn().mockResolvedValue({ delegated: true }),
+        };
+        provider.setResponsesProvider(
+            sibling as unknown as Parameters<
+                typeof provider.setResponsesProvider
+            >[0],
+        );
+
+        const params = {
+            model: 'gpt-6-luna',
+            messages: [{ role: 'user', content: 'hi' }],
+            prompt_cache_options: { ttl: '12h' as const },
+        };
+        const result = await withTestActor(() => provider.complete(params));
+
+        expect(createMock).not.toHaveBeenCalled();
+        expect(sibling.complete).toHaveBeenCalledWith(params);
+        expect(result).toEqual({ delegated: true });
+    });
+
+    it.each([
+        ['30m', { mode: 'explicit', ttl: '30m' }],
+        ['12h', { mode: 'explicit', ttl: '12h' }],
+    ])(
+        'delegates a %s breakpoint lifetime to the Responses provider, since Chat Completions rejects the field',
+        async (_ttl, breakpoint) => {
+            const { provider } = makeProvider();
+            const sibling = {
+                complete: vi.fn().mockResolvedValue({ delegated: true }),
+            };
+            provider.setResponsesProvider(
+                sibling as unknown as Parameters<
+                    typeof provider.setResponsesProvider
+                >[0],
+            );
+
+            const params = {
+                model: 'gpt-6-luna',
+                messages: [
+                    {
+                        role: 'system',
+                        content: [
+                            {
+                                type: 'text',
+                                text: 'long prefix',
+                                prompt_cache_breakpoint: breakpoint,
+                            },
+                        ],
+                    },
+                    { role: 'user', content: 'hi' },
+                ],
+            };
+            const result = await withTestActor(() =>
+                provider.complete(params as never),
+            );
+
+            expect(createMock).not.toHaveBeenCalled();
+            expect(sibling.complete).toHaveBeenCalledWith(params);
+            expect(result).toEqual({ delegated: true });
+        },
+    );
+
+    it('keeps a breakpoint without a lifetime on the Chat Completions path, intact', async () => {
+        const { provider } = makeProvider();
+        createMock.mockResolvedValueOnce({
+            choices: [
+                {
+                    message: { content: 'ok', role: 'assistant' },
+                    finish_reason: 'stop',
+                },
+            ],
+            usage: { prompt_tokens: 1, completion_tokens: 1 },
+        });
+
+        await withTestActor(() =>
+            provider.complete({
+                model: 'gpt-6-luna',
+                messages: [
+                    {
+                        role: 'system',
+                        content: [
+                            {
+                                type: 'text',
+                                text: 'long prefix',
+                                prompt_cache_breakpoint: { mode: 'explicit' },
+                            },
+                        ],
+                    },
+                    { role: 'user', content: 'hi' },
+                ],
+            } as never),
+        );
+
+        const [args] = createMock.mock.calls[0]!;
+        expect(args.messages[0]).toMatchObject({
+            role: 'system',
+            content: [
+                {
+                    type: 'text',
+                    text: 'long prefix',
+                    prompt_cache_breakpoint: { mode: 'explicit' },
+                },
+            ],
+        });
+    });
+
+    it('throws 400 for a 12h cache lifetime without a Responses sibling provider', async () => {
+        const { provider } = makeProvider();
+
+        await expect(
+            withTestActor(() =>
+                provider.complete({
+                    model: 'gpt-6-luna',
+                    messages: [{ role: 'user', content: 'hi' }],
+                    prompt_cache_options: { ttl: '12h' },
+                }),
+            ),
+        ).rejects.toMatchObject({ statusCode: 400 });
+        expect(createMock).not.toHaveBeenCalled();
+    });
+
     it('requestPricing delegates to the Responses sibling (web_search\'s own hold), and no-ops without one', async () => {
         const { provider } = makeProvider();
         const args = {
@@ -349,6 +473,31 @@ describe('OpenAiChatProvider.complete request shape', () => {
         expect(args.safety_identifier).toBe('puter-u42');
     });
 
+    it('forwards 30m prompt_cache_options and the wire spelling of prompt_cache_retention', async () => {
+        const { provider } = makeProvider();
+        createMock.mockResolvedValueOnce(baseCompletion);
+
+        await withTestActor(() =>
+            provider.complete({
+                model: 'gpt-6-luna',
+                messages: [{ role: 'user', content: 'hello' }],
+                prompt_cache_retention: 'in-memory',
+                prompt_cache_options: {
+                    mode: 'explicit',
+                    ttl: '30m',
+                    prewarm: true,
+                } as never,
+            }),
+        );
+
+        const [args] = createMock.mock.calls[0]!;
+        expect(args.prompt_cache_retention).toBe('in_memory');
+        expect(args.prompt_cache_options).toEqual({
+            mode: 'explicit',
+            ttl: '30m',
+        });
+    });
+
     it.each([
         'gpt-6-astra',
         'gpt-6.1-sol',
@@ -665,7 +814,7 @@ describe('OpenAiChatProvider.complete non-stream output', () => {
             },
         });
 
-        await withTestActor(() =>
+        const result = await withTestActor(() =>
             provider.complete({
                 model: 'gpt-6-luna',
                 messages: [{ role: 'user', content: 'hi' }],
@@ -685,6 +834,13 @@ describe('OpenAiChatProvider.complete non-stream output', () => {
             cached_tokens: 1000 * Number(luna.costs.cached_tokens),
             cache_write_tokens: 3000 * Number(luna.costs.cache_write_tokens),
         });
+        // Chat Completions only writes OpenAI's default 30m entries.
+        expect((result as { usageDetails: unknown }).usageDetails).toEqual({
+            inputTokens: 1000,
+            outputTokens: 12,
+            cacheReadTokens: 1000,
+            cacheWrite30mTokens: 3000,
+        });
     });
 
     it('zeroes cached_tokens when prompt_tokens_details is missing', async () => {

src/backend/drivers/ai-chat/providers/openai/OpenAiChatCompletionsProvider.ts

@@ -35,7 +35,10 @@ import { make_openai_tools } from '../../utils/FunctionCalling.js';
 import * as OpenAiUtil from '../../utils/OpenAIUtil.js';
 import {
     clampReasoningEffort,
+    messagesHaveCacheBreakpointTtl,
     openAICompatParams,
+    promptCacheOptionsToWire,
+    promptCacheRetentionToWire,
 } from '../../utils/openaiParams.js';
 import { OPEN_AI_MODELS } from './models.js';
 import type { OpenAiResponsesChatProvider } from './OpenAiChatResponsesProvider.js';
@@ -126,8 +129,11 @@ export class OpenAiChatProvider implements IChatProvider {
             temperature,
             text,
             prompt_cache_key,
+            prompt_cache_retention,
+            prompt_cache_options,
         } = params;
         let { messages, model } = params;
+        const cacheOptions = promptCacheOptionsToWire(prompt_cache_options);
         if (
             tools?.filter((e) => isWebSearchTool(e as Record<string, unknown>))
                 .length
@@ -157,6 +163,21 @@ export class OpenAiChatProvider implements IChatProvider {
             }
             return await this.#responsesProvider.complete(params);
         }
+        // Only the Responses API writes 12h cache entries or takes a lifetime
+        // on a `prompt_cache_breakpoint`; Chat Completions rejects both.
+        if (
+            cacheOptions?.ttl === '12h' ||
+            messagesHaveCacheBreakpointTtl(messages)
+        ) {
+            if (!this.#responsesProvider) {
+                throw new HttpError(
+                    400,
+                    'a prompt cache lifetime requires the OpenAI Responses provider, which is not configured',
+                    { legacyCode: 'bad_request' },
+                );
+            }
+            return await this.#responsesProvider.complete(params);
+        }
         // Validate messages
         if (!Array.isArray(messages)) {
             throw new HttpError(400, '`messages` must be an array', {
@@ -180,6 +201,9 @@ export class OpenAiChatProvider implements IChatProvider {
         const userIdentifier = upstreamUserIdentifier(actor);
         // Cache key defaults to the actor identifier; see upstreamUserIdentifier.
         const cacheKey = prompt_cache_key ?? userIdentifier;
+        const cacheRetention = promptCacheRetentionToWire(
+            prompt_cache_retention,
+        );
 
         // Strip Anthropic-only shape a fallback-replayed message can carry
         // (thinking/server-tool blocks, cache_control, citations) before the
@@ -216,6 +240,12 @@ export class OpenAiChatProvider implements IChatProvider {
             user: userIdentifier,
             safety_identifier: userIdentifier,
             ...(cacheKey !== undefined ? { prompt_cache_key: cacheKey } : {}),
+            ...(cacheRetention !== undefined
+                ? { prompt_cache_retention: cacheRetention }
+                : {}),
+            ...(cacheOptions !== undefined
+                ? { prompt_cache_options: cacheOptions }
+                : {}),
             messages: messages,
             model: modelUsed.id,
             ...(mappedTools?.length ? { tools: mappedTools } : {}),
@@ -254,28 +284,11 @@ export class OpenAiChatProvider implements IChatProvider {
         );
 
         return OpenAiUtil.handle_completion_output({
-            usage_calculator: ({ usage, setUsageCosts }) => {
-                const cachedTokens =
-                    usage.prompt_tokens_details?.cached_tokens ?? 0;
-                // GPT-5.6 and later bill cache writes at 1.25x input. They're
-                // reported inside `prompt_tokens`, like cached reads.
-                // The SDK doesn't type `cache_write_tokens` yet.
-                const cacheWriteTokens =
-                    (
-                        usage.prompt_tokens_details as
-                            { cache_write_tokens?: number } | undefined
-                    )?.cache_write_tokens ?? 0;
-                const trackedUsage = {
-                    prompt_tokens:
-                        (usage.prompt_tokens ?? 0) -
-                        cachedTokens -
-                        cacheWriteTokens,
-                    completion_tokens: usage.completion_tokens ?? 0,
-                    cached_tokens: cachedTokens,
-                    ...(cacheWriteTokens
-                        ? { cache_write_tokens: cacheWriteTokens }
-                        : {}),
-                };
+            usage_calculator: ({ usage, setUsageCosts, setUsageDetails }) => {
+                // GPT-5.6 and later report cache writes inside
+                // `prompt_tokens`, like cached reads; Chat Completions only
+                // writes the default 30m entries, billed at 1.25x input.
+                const trackedUsage = OpenAiUtil.splitCachedPrompt(usage);
 
                 const metered = meterChatUsage(
                     this.#meteringService,
@@ -285,6 +298,11 @@ export class OpenAiChatProvider implements IChatProvider {
                     trackedUsage,
                 );
                 setUsageCosts(metered.costs);
+                setUsageDetails(
+                    OpenAiUtil.usageDetailsFromTrackedUsage(metered.usage, {
+                        writeTtl: '30m',
+                    })!,
+                );
                 return metered.usage;
             },
             stream,

src/backend/drivers/ai-chat/providers/openai/OpenAiChatResponsesProvider.test.ts

@@ -246,6 +246,7 @@ describe('OpenAiResponsesChatProvider model catalog', () => {
                     prompt_tokens: input,
                     cached_tokens: cached,
                     cache_write_tokens: input * 1.25,
+                    cache_write_12h_tokens: input * 2.5,
                     completion_tokens: output,
                 },
                 context: 1_050_000,
@@ -844,7 +845,7 @@ describe('OpenAiResponsesChatProvider.complete non-stream output', () => {
             },
         });
 
-        await withTestActor(() =>
+        const result = await withTestActor(() =>
             provider.complete({
                 model: 'gpt-6-luna',
                 messages: [{ role: 'user', content: 'hi' }],
@@ -867,6 +868,115 @@ describe('OpenAiResponsesChatProvider.complete non-stream output', () => {
             cached_tokens: 1000 * Number(luna.costs.cached_tokens),
             cache_write_tokens: 3000 * Number(luna.costs.cache_write_tokens),
         });
+        // Writes without a per-lifetime breakdown are OpenAI's default 30m
+        // entries, and the neutral breakdown says so.
+        expect((result as { usageDetails: unknown }).usageDetails).toEqual({
+            inputTokens: 1000,
+            outputTokens: 20,
+            cacheReadTokens: 1000,
+            cacheWrite30mTokens: 3000,
+        });
+    });
+
+    it('bills 12h cache writes at 2.5x input and the other writes at 1.25x', async () => {
+        const luna = OPEN_AI_MODELS.find((m) => m.id === 'gpt-6-luna')!;
+        const { provider } = makeProvider();
+        // One request can write both lifetimes: an explicit 12h breakpoint
+        // plus the implicit 30m one OpenAI adds at the end of the prompt.
+        responsesCreateMock.mockResolvedValueOnce({
+            output: [{ role: 'assistant' }],
+            output_text: 'ok',
+            usage: {
+                input_tokens: 6026,
+                output_tokens: 5,
+                input_tokens_details: {
+                    cached_tokens: 0,
+                    cache_write_tokens: 6023,
+                    cache_write_tokens_details: {
+                        ttl_12h_tokens: 6012,
+                        ttl_30m_tokens: 11,
+                    },
+                },
+            },
+        });
+
+        const result = await withTestActor(() =>
+            provider.complete({
+                model: 'gpt-6-luna',
+                messages: [{ role: 'user', content: 'hi' }],
+                prompt_cache_options: { ttl: '12h' },
+            }),
+        );
+
+        const [usage, , , overrides] = recordSpy.mock.calls[0]!;
+        expect(usage).toEqual({
+            prompt_tokens: 3,
+            completion_tokens: 5,
+            cached_tokens: 0,
+            cache_write_tokens: 11,
+            cache_write_12h_tokens: 6012,
+        });
+        expect(luna.costs.cache_write_12h_tokens).toBe(
+            Number(luna.costs.prompt_tokens) * 2.5,
+        );
+        expect(overrides).toEqual({
+            prompt_tokens: 3 * Number(luna.costs.prompt_tokens),
+            completion_tokens: 5 * Number(luna.costs.completion_tokens),
+            cached_tokens: 0,
+            cache_write_tokens: 11 * Number(luna.costs.cache_write_tokens),
+            cache_write_12h_tokens:
+                6012 * Number(luna.costs.cache_write_12h_tokens),
+        });
+        expect((result as { usageDetails: unknown }).usageDetails).toEqual({
+            inputTokens: 3,
+            outputTokens: 5,
+            cacheWrite30mTokens: 11,
+            cacheWrite12hTokens: 6012,
+        });
+    });
+
+    it('forwards prompt_cache_options and the wire spelling of prompt_cache_retention', async () => {
+        const { provider } = makeProvider();
+        responsesCreateMock.mockResolvedValueOnce({
+            output: [{ role: 'assistant' }],
+            output_text: 'ok',
+            usage: { input_tokens: 1, output_tokens: 1 },
+        });
+
+        await withTestActor(() =>
+            provider.complete({
+                model: 'gpt-6-luna',
+                messages: [{ role: 'user', content: 'hi' }],
+                prompt_cache_retention: 'in-memory',
+                prompt_cache_options: {
+                    mode: 'explicit',
+                    ttl: '12h',
+                    comparison_response_id: 'resp_1',
+                } as never,
+            }),
+        );
+
+        const [args] = responsesCreateMock.mock.calls[0]!;
+        expect(args.prompt_cache_retention).toBe('in_memory');
+        expect(args.prompt_cache_options).toEqual({
+            mode: 'explicit',
+            ttl: '12h',
+        });
+    });
+
+    it('rejects a cache lifetime OpenAI does not offer before calling upstream', async () => {
+        const { provider } = makeProvider();
+
+        await expect(
+            withTestActor(() =>
+                provider.complete({
+                    model: 'gpt-6-luna',
+                    messages: [{ role: 'user', content: 'hi' }],
+                    prompt_cache_options: { ttl: '2h' } as never,
+                }),
+            ),
+        ).rejects.toMatchObject({ statusCode: 400 });
+        expect(responsesCreateMock).not.toHaveBeenCalled();
     });
 
     it.each([
@@ -1068,6 +1178,69 @@ describe('OpenAiResponsesChatProvider.complete streaming', () => {
         });
     });
 
+    it('labels streamed cache writes by lifetime on the final usage chunk', async () => {
+        const luna = OPEN_AI_MODELS.find((m) => m.id === 'gpt-6-luna')!;
+        const { provider } = makeProvider();
+        responsesCreateMock.mockReturnValueOnce(
+            asAsyncIterable([
+                { type: 'response.output_text.delta', delta: 'ok' },
+                {
+                    type: 'response.completed',
+                    response: {
+                        usage: {
+                            input_tokens: 6026,
+                            output_tokens: 5,
+                            input_tokens_details: {
+                                cached_tokens: 0,
+                                cache_write_tokens: 6023,
+                                cache_write_tokens_details: {
+                                    ttl_12h_tokens: 6012,
+                                    ttl_30m_tokens: 11,
+                                },
+                            },
+                        },
+                    },
+                },
+            ]),
+        );
+
+        const result = await withTestActor(() =>
+            provider.complete({
+                model: 'gpt-6-luna',
+                messages: [{ role: 'user', content: 'say ok' }],
+                stream: true,
+                prompt_cache_options: { ttl: '12h' },
+            }),
+        );
+        const harness = makeCapturingChatStream();
+        await (
+            result as {
+                init_chat_stream: (p: { chatStream: unknown }) => Promise<void>;
+            }
+        ).init_chat_stream({ chatStream: harness.chatStream });
+
+        const usageEvent = harness.events().find((e) => e.type === 'usage');
+        expect(usageEvent?.usage).toEqual({
+            prompt_tokens: 3,
+            completion_tokens: 5,
+            cached_tokens: 0,
+            cache_write_tokens: 11,
+            cache_write_12h_tokens: 6012,
+        });
+        expect(usageEvent?.usageDetails).toEqual({
+            inputTokens: 3,
+            outputTokens: 5,
+            cacheWrite30mTokens: 11,
+            cacheWrite12hTokens: 6012,
+        });
+        const [, , , overrides] = recordSpy.mock.calls[0]!;
+        expect(overrides).toMatchObject({
+            cache_write_tokens: 11 * Number(luna.costs.cache_write_tokens),
+            cache_write_12h_tokens:
+                6012 * Number(luna.costs.cache_write_12h_tokens),
+        });
+    });
+
     it('emits a tool_use block when response.output_item.done arrives with a function_call', async () => {
         const { provider } = makeProvider();
         responsesCreateMock.mockReturnValueOnce(

src/backend/drivers/ai-chat/providers/openai/OpenAiChatResponsesProvider.ts

@@ -32,6 +32,8 @@ import * as OpenAiUtil from '../../utils/OpenAIUtil.js';
 import {
     clampReasoningEffort,
     openAICompatParams,
+    promptCacheOptionsToWire,
+    promptCacheRetentionToWire,
     rejectStatefulResponsesFields,
 } from '../../utils/openaiParams.js';
 import { responseSamplingParams } from '../../utils/responseSampling.js';
@@ -150,6 +152,7 @@ export class OpenAiResponsesChatProvider implements IChatProvider {
         prompt,
         prompt_cache_key,
         prompt_cache_retention,
+        prompt_cache_options,
         store,
         top_p,
         truncation,
@@ -195,6 +198,10 @@ export class OpenAiResponsesChatProvider implements IChatProvider {
         const userIdentifier = upstreamUserIdentifier(actor);
         // Cache key defaults to the actor identifier; see upstreamUserIdentifier.
         const cacheKey = prompt_cache_key ?? userIdentifier;
+        const cacheRetention = promptCacheRetentionToWire(
+            prompt_cache_retention,
+        );
+        const cacheOptions = promptCacheOptionsToWire(prompt_cache_options);
 
         if (tools) {
             // Unravel tools to OpenAI Responses API format
@@ -288,8 +295,11 @@ export class OpenAiResponsesChatProvider implements IChatProvider {
             ...(instructions !== undefined ? { instructions } : {}),
             ...(metadata !== undefined ? { metadata } : {}),
             ...(cacheKey !== undefined ? { prompt_cache_key: cacheKey } : {}),
-            ...(prompt_cache_retention !== undefined
-                ? { prompt_cache_retention }
+            ...(cacheRetention !== undefined
+                ? { prompt_cache_retention: cacheRetention }
+                : {}),
+            ...(cacheOptions !== undefined
+                ? { prompt_cache_options: cacheOptions }
                 : {}),
             ...(store !== undefined ? { store } : {}),
             ...(max_tokens !== undefined
@@ -310,24 +320,17 @@ export class OpenAiResponsesChatProvider implements IChatProvider {
             { signal: Context.get('upstreamSignal') },
         );
         return OpenAiUtil.handle_completion_output_responses_api({
-            usage_calculator: ({ usage, webSearchCalls, setUsageCosts }) => {
-                const cachedTokens =
-                    (usage as any).input_tokens_details?.cached_tokens ?? 0;
-                // GPT-5.6 and later bill cache writes at 1.25x input. They're
-                // reported inside `input_tokens`, like cached reads.
-                const cacheWriteTokens =
-                    (usage as any).input_tokens_details?.cache_write_tokens ??
-                    0;
+            usage_calculator: ({
+                usage,
+                webSearchCalls,
+                setUsageCosts,
+                setUsageDetails,
+            }) => {
+                // GPT-5.6 and later report cache writes inside `input_tokens`,
+                // like cached reads, split by lifetime (30m and 12h entries
+                // cost 1.25x and 2.5x input to write).
                 const trackedUsage: Record<string, number> = {
-                    prompt_tokens:
-                        ((usage as any).input_tokens ?? 0) -
-                        cachedTokens -
-                        cacheWriteTokens,
-                    completion_tokens: (usage as any).output_tokens ?? 0,
-                    cached_tokens: cachedTokens,
-                    ...(cacheWriteTokens
-                        ? { cache_write_tokens: cacheWriteTokens }
-                        : {}),
+                    ...OpenAiUtil.splitCachedPrompt(usage),
                     ...(webSearchCalls
                         ? { web_search_calls: webSearchCalls }
                         : {}),
@@ -356,6 +359,11 @@ export class OpenAiResponsesChatProvider implements IChatProvider {
                         : {},
                 );
                 setUsageCosts?.(metered.costs);
+                setUsageDetails?.(
+                    OpenAiUtil.usageDetailsFromTrackedUsage(metered.usage, {
+                        writeTtl: '30m',
+                    })!,
+                );
                 return metered.usage;
             },
             stream,

src/backend/drivers/ai-chat/providers/openai/models.ts

@@ -23,6 +23,8 @@ import type { IChatModel } from '../../types.js';
 
 // Prompts over 272K input tokens are billed at 2x input (cached reads and
 // cache writes included) and 1.5x output for the full request.
+// GPT-5.6 and later bill cache writes by the lifetime requested: 1.25x input
+// for the default 30m entries, 2.5x for 12h entries.
 const GPT_LONG_CONTEXT_PRICING = {
     threshold: 272_000,
     input_multiplier: 2,
@@ -49,6 +51,7 @@ export const OPEN_AI_MODELS: IChatModel[] = [
             prompt_tokens: 100,
             cached_tokens: 5,
             cache_write_tokens: 100 * 1.25,
+            cache_write_12h_tokens: 100 * 2.5,
             completion_tokens: 500,
         },
         long_context_pricing: GPT_LONG_CONTEXT_PRICING,
@@ -74,6 +77,7 @@ export const OPEN_AI_MODELS: IChatModel[] = [
             prompt_tokens: 200,
             cached_tokens: 10,
             cache_write_tokens: 200 * 1.25,
+            cache_write_12h_tokens: 200 * 2.5,
             completion_tokens: 1000,
         },
         long_context_pricing: GPT_LONG_CONTEXT_PRICING,
@@ -99,6 +103,7 @@ export const OPEN_AI_MODELS: IChatModel[] = [
             prompt_tokens: 200,
             cached_tokens: 20,
             cache_write_tokens: 200 * 1.25,
+            cache_write_12h_tokens: 200 * 2.5,
             completion_tokens: 1000,
         },
         long_context_pricing: GPT_LONG_CONTEXT_PRICING,
@@ -124,6 +129,7 @@ export const OPEN_AI_MODELS: IChatModel[] = [
             prompt_tokens: 10,
             cached_tokens: 1,
             cache_write_tokens: 10 * 1.25,
+            cache_write_12h_tokens: 10 * 2.5,
             completion_tokens: 50,
         },
         long_context_pricing: GPT_LONG_CONTEXT_PRICING,
@@ -149,6 +155,7 @@ export const OPEN_AI_MODELS: IChatModel[] = [
             prompt_tokens: 1000,
             cached_tokens: 100,
             cache_write_tokens: 1000 * 1.25,
+            cache_write_12h_tokens: 1000 * 2.5,
             completion_tokens: 5000,
         },
         long_context_pricing: GPT_LONG_CONTEXT_PRICING,
@@ -174,6 +181,7 @@ export const OPEN_AI_MODELS: IChatModel[] = [
             prompt_tokens: 400,
             cached_tokens: 40,
             cache_write_tokens: 400 * 1.25,
+            cache_write_12h_tokens: 400 * 2.5,
             completion_tokens: 2000,
         },
         long_context_pricing: GPT_LONG_CONTEXT_PRICING,
@@ -198,6 +206,7 @@ export const OPEN_AI_MODELS: IChatModel[] = [
             prompt_tokens: 200,
             cached_tokens: 20,
             cache_write_tokens: 200 * 1.25,
+            cache_write_12h_tokens: 200 * 2.5,
             completion_tokens: 1200,
         },
         long_context_pricing: GPT_LONG_CONTEXT_PRICING,
@@ -222,6 +231,7 @@ export const OPEN_AI_MODELS: IChatModel[] = [
             prompt_tokens: 20,
             cached_tokens: 2,
             cache_write_tokens: 20 * 1.25,
+            cache_write_12h_tokens: 20 * 2.5,
             completion_tokens: 120,
         },
         long_context_pricing: GPT_LONG_CONTEXT_PRICING,

src/backend/drivers/ai-chat/types.ts

@@ -145,13 +145,19 @@ export type StopReason =
     | 'model_context_window_exceeded'
     | (string & {});
 
-/** Provider-neutral usage breakdown. `inputTokens` excludes cache reads/writes. */
+/**
+ * Provider-neutral usage breakdown. `inputTokens` excludes cache reads/writes.
+ * Cache writes are keyed by the lifetime the entry was written with: Claude and
+ * Moonshot write 5m and 1h entries, OpenAI writes 30m and 12h entries.
+ */
 export interface UsageDetails {
     inputTokens: number;
     outputTokens: number; // includes reasoning
     cacheReadTokens?: number;
     cacheWrite5mTokens?: number;
+    cacheWrite30mTokens?: number;
     cacheWrite1hTokens?: number;
+    cacheWrite12hTokens?: number;
     reasoningTokens?: number;
     webSearchRequests?: number;
     webFetchRequests?: number;
@@ -168,10 +174,22 @@ export interface UsageDetails {
         outputTokens: number;
         cacheReadTokens?: number;
         cacheWrite5mTokens?: number;
+        cacheWrite30mTokens?: number;
         cacheWrite1hTokens?: number;
+        cacheWrite12hTokens?: number;
     }>;
 }
 
+/**
+ * OpenAI `prompt_cache_options`, GPT-5.6 and later. `ttl` is the minimum
+ * lifetime of every cache entry the request writes; `12h` entries cost twice
+ * what `30m` entries do to write and only the Responses API writes them.
+ */
+export interface PromptCacheOptions {
+    mode?: 'implicit' | 'explicit';
+    ttl?: '30m' | '12h';
+}
+
 export interface ICompleteArguments {
     messages: PuterMessage[];
     provider?: string;
@@ -234,7 +252,9 @@ export interface ICompleteArguments {
     metadata?: Record<string, string>;
     prompt?: unknown;
     prompt_cache_key?: string;
-    prompt_cache_retention?: 'in-memory' | '24h' | undefined;
+    /** `in-memory` is accepted as a spelling of OpenAI's `in_memory`. */
+    prompt_cache_retention?: 'in-memory' | 'in_memory' | '24h' | undefined;
+    prompt_cache_options?: PromptCacheOptions;
     store?: boolean;
     top_p?: number;
     truncation?: 'auto' | 'disabled' | undefined;

src/backend/drivers/ai-chat/utils/OpenAIUtil.js

@@ -481,43 +481,86 @@ export const extractMeteredUsage = (usage) => {
 };
 
 /**
- * Chat Completions usage as it's metered: `prompt_tokens` reports cached reads
- * inside its count, so they come out of it and are priced only once, under
- * `cached_tokens`.
+ * @typedef {{
+ *     cached_tokens?: number | null;
+ *     cache_write_tokens?: number | null;
+ *     cache_write_tokens_details?: {
+ *         ttl_30m_tokens?: number | null;
+ *         ttl_12h_tokens?: number | null;
+ *     } | null;
+ * }} OpenAiCacheDetails
+ */
+
+/**
+ * OpenAI-shaped usage as it's metered. The prompt count reports cached reads
+ * and cache writes inside it, so they come out of it and are priced once each
+ * under their own keys: `cached_tokens` for reads, `cache_write_tokens` for
+ * writes at the model's default lifetime and `cache_write_12h_tokens` for
+ * writes at OpenAI's 12h lifetime. Without the per-lifetime breakdown every
+ * write is a default-lifetime write: Chat Completions writes no 12h entries,
+ * and Responses reports the breakdown whenever a request asked for them. Reads
+ * the Chat Completions (`prompt_tokens`) and Responses (`input_tokens`)
+ * spellings alike.
  *
- * @param {import('openai/resources/completions.mjs').CompletionUsage | undefined} usage
+ * @param {{
+ *           prompt_tokens?: number;
+ *           completion_tokens?: number;
+ *           prompt_tokens_details?: OpenAiCacheDetails | null;
+ *           input_tokens?: number;
+ *           output_tokens?: number;
+ *           input_tokens_details?: OpenAiCacheDetails | null;
+ *       }
+ *     | undefined} usage
  */
 export const splitCachedPrompt = (usage) => {
-    const details = usage?.prompt_tokens_details;
+    const details = usage?.prompt_tokens_details ?? usage?.input_tokens_details;
     const cachedTokens = details?.cached_tokens ?? 0;
-    // Moonshot counts the prompt tokens it wrote to its prefix cache here;
-    // they're billed at the model's write rate, not the plain prompt rate.
+    // Moonshot and GPT-5.6+ count the prompt tokens they wrote to the prefix
+    // cache here; they're billed at the model's write rate, not the prompt rate.
     const writeTokens =
         typeof details?.cache_write_tokens === 'number'
             ? details.cache_write_tokens
             : undefined;
+    const reported12h = details?.cache_write_tokens_details?.ttl_12h_tokens;
+    const write12hTokens =
+        typeof reported12h === 'number'
+            ? Math.min(reported12h, writeTokens ?? 0)
+            : undefined;
     return {
         prompt_tokens:
-            (usage?.prompt_tokens ?? 0) - cachedTokens - (writeTokens ?? 0),
-        completion_tokens: usage?.completion_tokens ?? 0,
+            (usage?.prompt_tokens ?? usage?.input_tokens ?? 0) -
+            cachedTokens -
+            (writeTokens ?? 0),
+        completion_tokens:
+            usage?.completion_tokens ?? usage?.output_tokens ?? 0,
         cached_tokens: cachedTokens,
         ...(writeTokens !== undefined
-            ? { cache_write_tokens: writeTokens }
+            ? { cache_write_tokens: writeTokens - (write12hTokens ?? 0) }
+            : {}),
+        ...(write12hTokens !== undefined
+            ? { cache_write_12h_tokens: write12hTokens }
             : {}),
     };
 };
 
 /**
- * The `{prompt_tokens, completion_tokens, cached_tokens, cache_write_tokens}`
- * shape every OpenAI-family `usage_calculator` already returns for billing,
- * mapped to the provider-neutral `UsageDetails` the end-of-stream/non-stream
- * result carries. `inputTokens`/`outputTokens` are the same numbers already
- * billed — this never introduces a new figure, only exposes the breakdown.
+ * The `{prompt_tokens, completion_tokens, cached_tokens, cache_write_tokens,
+ * cache_write_12h_tokens}` shape every OpenAI-family `usage_calculator` already
+ * returns for billing, mapped to the provider-neutral `UsageDetails` the
+ * end-of-stream/non-stream result carries. `inputTokens`/`outputTokens` are the
+ * same numbers already billed — this never introduces a new figure, only
+ * exposes the breakdown.
  *
  * @param {Record<string, number> | undefined | null} trackedUsage
+ * @param {{ writeTtl?: '5m' | '30m' }} [opts] The lifetime `cache_write_tokens`
+ *   were written with: 5m unless the provider says otherwise (OpenAI's default
+ *   entries live 30m).
  * @returns {import('../types.js').UsageDetails | undefined}
  */
-export const usageDetailsFromTrackedUsage = (trackedUsage) => {
+export const usageDetailsFromTrackedUsage = (
+    trackedUsage,
+    { writeTtl = '5m' } = {},
+) => {
     if (!trackedUsage || typeof trackedUsage !== 'object') return undefined;
     // OpenRouter, Infron and Ollama track `{prompt, completion,
     // input_cache_read}` instead; any other shape is left to the driver.
@@ -526,12 +569,19 @@ export const usageDetailsFromTrackedUsage = (trackedUsage) => {
     if (input === undefined && output === undefined) return undefined;
     const cacheRead =
         trackedUsage.cached_tokens ?? trackedUsage.input_cache_read;
+    const cacheWrite = trackedUsage.cache_write_tokens;
     return {
         inputTokens: input ?? 0,
         outputTokens: output ?? 0,
         ...(cacheRead ? { cacheReadTokens: cacheRead } : {}),
-        ...(trackedUsage.cache_write_tokens
-            ? { cacheWrite5mTokens: trackedUsage.cache_write_tokens }
+        ...(cacheWrite && writeTtl === '30m'
+            ? { cacheWrite30mTokens: cacheWrite }
+            : {}),
+        ...(cacheWrite && writeTtl !== '30m'
+            ? { cacheWrite5mTokens: cacheWrite }
+            : {}),
+        ...(trackedUsage.cache_write_12h_tokens
+            ? { cacheWrite12hTokens: trackedUsage.cache_write_12h_tokens }
             : {}),
     };
 };
@@ -864,12 +914,16 @@ export const create_chat_stream_handler_responses_api =
         // Missing usage is left undefined rather than fed to the calculator —
         // see the sibling handler above, including why usage is reported
         // before the block flushes.
+        let usageDetails;
         const usage = last_usage
             ? usage_calculator({
                   usage: last_usage,
                   webSearchCalls,
                   tool_usage: toolUsage,
                   setUsageCosts: (c) => chatStream.setUsageCosts(c),
+                  setUsageDetails: (d) => {
+                      usageDetails = d;
+                  },
               })
             : undefined;
         chatStream.reportUsage(usage);
@@ -877,7 +931,7 @@ export const create_chat_stream_handler_responses_api =
             reason:
                 incompleteReason ?? (sawFunctionCall ? 'tool_use' : 'end_turn'),
         });
-        const usageDetails = usageDetailsFromTrackedUsage(usage);
+        usageDetails ??= usageDetailsFromTrackedUsage(usage);
         if (usageDetails) chatStream.setUsageDetails(usageDetails);
 
         textblock.end();
@@ -1015,6 +1069,7 @@ export const handle_completion_output = async (
  *     webSearchCalls?: number;
  *     tool_usage?: Record<string, unknown>;
  *     setUsageCosts?: (costs: Record<string, number>) => void;
+ *     setUsageDetails?: (details: import('../types').UsageDetails) => void;
  * }) => unknown} params.usage_calculator
  * @param {() => Promise<void>} [params.finally_fn]
  * @returns {ReturnType<import('../types').IChatProvider['complete']>}
@@ -1156,12 +1211,15 @@ export const handle_completion_output_responses_api = async ({
               setUsageCosts: (c) => {
                   ret.usageCosts = c;
               },
+              setUsageDetails: (d) => {
+                  ret.usageDetails = d;
+              },
           })
         : {
               input_tokens: completion.usage.input_tokens,
               output_tokens: completion.usage.output_tokens,
           };
-    if (usage_calculator) {
+    if (usage_calculator && ret.usageDetails === undefined) {
         const usageDetails = usageDetailsFromTrackedUsage(ret.usage);
         if (usageDetails) ret.usageDetails = usageDetails;
     }

src/backend/drivers/ai-chat/utils/OpenAIUtil.test.ts

@@ -247,6 +247,40 @@ describe('usageDetailsFromTrackedUsage', () => {
         });
     });
 
+    it('labels cache writes by the lifetime the provider says it wrote them with', () => {
+        expect(
+            usageDetailsFromTrackedUsage(
+                {
+                    prompt_tokens: 10,
+                    completion_tokens: 5,
+                    cached_tokens: 3,
+                    cache_write_tokens: 11,
+                    cache_write_12h_tokens: 6012,
+                },
+                { writeTtl: '30m' },
+            ),
+        ).toEqual({
+            inputTokens: 10,
+            outputTokens: 5,
+            cacheReadTokens: 3,
+            cacheWrite30mTokens: 11,
+            cacheWrite12hTokens: 6012,
+        });
+        // Zero counts, as OpenAI reports on a cache hit, add no field.
+        expect(
+            usageDetailsFromTrackedUsage(
+                {
+                    prompt_tokens: 10,
+                    completion_tokens: 5,
+                    cached_tokens: 3,
+                    cache_write_tokens: 0,
+                    cache_write_12h_tokens: 0,
+                },
+                { writeTtl: '30m' },
+            ),
+        ).toEqual({ inputTokens: 10, outputTokens: 5, cacheReadTokens: 3 });
+    });
+
     it('returns undefined for a missing/non-object usage', () => {
         expect(usageDetailsFromTrackedUsage(undefined)).toBeUndefined();
         expect(usageDetailsFromTrackedUsage(null)).toBeUndefined();
@@ -962,6 +996,66 @@ describe('splitCachedPrompt', () => {
             cached_tokens: 3,
         });
     });
+
+    it('reads the Responses usage spelling', () => {
+        expect(
+            splitCachedPrompt({
+                input_tokens: 6026,
+                output_tokens: 5,
+                input_tokens_details: { cached_tokens: 0, cache_write_tokens: 6023 },
+            }),
+        ).toEqual({
+            prompt_tokens: 3,
+            completion_tokens: 5,
+            cached_tokens: 0,
+            cache_write_tokens: 6023,
+        });
+    });
+
+    it('splits 12h writes out of the write count when the breakdown is reported', () => {
+        // One request can write both lifetimes: an explicit 12h breakpoint
+        // plus the implicit 30m one OpenAI adds at the end of the prompt.
+        expect(
+            splitCachedPrompt({
+                input_tokens: 6026,
+                output_tokens: 5,
+                input_tokens_details: {
+                    cached_tokens: 0,
+                    cache_write_tokens: 6023,
+                    cache_write_tokens_details: {
+                        ttl_12h_tokens: 6012,
+                        ttl_30m_tokens: 11,
+                    },
+                },
+            }),
+        ).toEqual({
+            prompt_tokens: 3,
+            completion_tokens: 5,
+            cached_tokens: 0,
+            cache_write_tokens: 11,
+            cache_write_12h_tokens: 6012,
+        });
+    });
+
+    it('never reports more 12h writes than writes in total', () => {
+        expect(
+            splitCachedPrompt({
+                input_tokens: 100,
+                output_tokens: 1,
+                input_tokens_details: {
+                    cached_tokens: 0,
+                    cache_write_tokens: 40,
+                    cache_write_tokens_details: { ttl_12h_tokens: 50 },
+                },
+            }),
+        ).toEqual({
+            prompt_tokens: 60,
+            completion_tokens: 1,
+            cached_tokens: 0,
+            cache_write_tokens: 0,
+            cache_write_12h_tokens: 40,
+        });
+    });
 });
 
 // ── recorded usage costs ────────────────────────────────────────────

src/backend/drivers/ai-chat/utils/openaiParams.test.ts

@@ -22,11 +22,14 @@ import { describe, expect, it } from 'vitest';
 import type { ICompleteArguments } from '../types.js';
 import {
     clampReasoningEffort,
+    messagesHaveCacheBreakpointTtl,
     openAICompatParams,
     outputFormatFromResponseFormat,
     outputFormatFromResponsesText,
     outputFormatToResponseFormat,
     outputFormatToResponsesText,
+    promptCacheOptionsToWire,
+    promptCacheRetentionToWire,
     rejectStatefulResponsesFields,
     toolChoiceFromWire,
     toolChoiceToWire,
@@ -334,3 +337,109 @@ describe('rejectStatefulResponsesFields', () => {
         ).toThrow(/previous_response_id/);
     });
 });
+
+describe('promptCacheRetentionToWire', () => {
+    it('spells the in-memory retention the way the upstreams expect', () => {
+        expect(promptCacheRetentionToWire('in-memory')).toBe('in_memory');
+        expect(promptCacheRetentionToWire('in_memory')).toBe('in_memory');
+        expect(promptCacheRetentionToWire('24h')).toBe('24h');
+        expect(promptCacheRetentionToWire(undefined)).toBeUndefined();
+    });
+});
+
+describe('promptCacheOptionsToWire', () => {
+    it('forwards mode and ttl and nothing else', () => {
+        expect(
+            promptCacheOptionsToWire({
+                mode: 'explicit',
+                ttl: '12h',
+                prewarm: true,
+                comparison_response_id: 'resp_1',
+            }),
+        ).toEqual({ mode: 'explicit', ttl: '12h' });
+        expect(promptCacheOptionsToWire({ ttl: '30m' })).toEqual({
+            ttl: '30m',
+        });
+    });
+
+    it('sends nothing for an absent or empty object', () => {
+        expect(promptCacheOptionsToWire(undefined)).toBeUndefined();
+        expect(promptCacheOptionsToWire(null)).toBeUndefined();
+        expect(promptCacheOptionsToWire({})).toBeUndefined();
+        expect(promptCacheOptionsToWire({ prewarm: true })).toBeUndefined();
+    });
+
+    it('rejects a lifetime or mode OpenAI does not offer', () => {
+        expect(() => promptCacheOptionsToWire({ ttl: '2h' })).toThrow(
+            expect.objectContaining({ statusCode: 400 }),
+        );
+        expect(() => promptCacheOptionsToWire({ ttl: '24h' })).toThrow(
+            /30m.*12h/,
+        );
+        expect(() => promptCacheOptionsToWire({ mode: 'auto' })).toThrow(
+            /implicit.*explicit/,
+        );
+        expect(() => promptCacheOptionsToWire('12h')).toThrow(
+            /must be an object/,
+        );
+    });
+});
+
+describe('messagesHaveCacheBreakpointTtl', () => {
+    it('finds a breakpoint lifetime on any content part', () => {
+        expect(
+            messagesHaveCacheBreakpointTtl([
+                { role: 'user', content: 'plain' },
+                {
+                    role: 'system',
+                    content: [
+                        { type: 'text', text: 'a' },
+                        {
+                            type: 'text',
+                            text: 'b',
+                            prompt_cache_breakpoint: {
+                                mode: 'explicit',
+                                ttl: '30m',
+                            },
+                        },
+                    ],
+                },
+            ]),
+        ).toBe(true);
+        expect(
+            messagesHaveCacheBreakpointTtl([
+                {
+                    role: 'user',
+                    content: {
+                        type: 'text',
+                        text: 'a',
+                        prompt_cache_breakpoint: { ttl: '12h' },
+                    },
+                },
+            ]),
+        ).toBe(true);
+    });
+
+    it('ignores breakpoints without a lifetime and odd message shapes', () => {
+        expect(
+            messagesHaveCacheBreakpointTtl([
+                {
+                    role: 'system',
+                    content: [
+                        {
+                            type: 'text',
+                            text: 'a',
+                            prompt_cache_breakpoint: { mode: 'explicit' },
+                        },
+                        'bare string part',
+                        null,
+                    ],
+                },
+                { role: 'user', content: null },
+                null,
+            ]),
+        ).toBe(false);
+        expect(messagesHaveCacheBreakpointTtl(undefined)).toBe(false);
+        expect(messagesHaveCacheBreakpointTtl('nope')).toBe(false);
+    });
+});

src/backend/drivers/ai-chat/utils/openaiParams.ts

@@ -29,6 +29,7 @@ import { HttpError } from '../../../core/http/HttpError.js';
 import type {
     ICompleteArguments,
     OutputFormat,
+    PromptCacheOptions,
     ReasoningEffort,
     ToolChoice,
 } from '../types.js';
@@ -305,6 +306,80 @@ export const openAICompatParams = (
     return out;
 };
 
+// -- prompt caching ----------------------------------------------------------
+
+/**
+ * The wire spelling of `prompt_cache_retention`. Puter also accepts the
+ * hyphenated `in-memory`, which every OpenAI-shaped upstream rejects.
+ */
+export const promptCacheRetentionToWire = (
+    retention: ICompleteArguments['prompt_cache_retention'],
+): 'in_memory' | '24h' | undefined =>
+    retention === 'in-memory' ? 'in_memory' : retention;
+
+const PROMPT_CACHE_MODES = new Set(['implicit', 'explicit']);
+const PROMPT_CACHE_TTLS = new Set(['30m', '12h']);
+
+/**
+ * `prompt_cache_options` as forwarded upstream: `mode` and `ttl` only, each
+ * checked against the values OpenAI accepts, so a bad value fails here with a
+ * clear message instead of as an upstream 400 the fallback loop may hide.
+ * `comparison_response_id` names a stored response, which Puter never keeps,
+ * and `prewarm` is dropped with it.
+ */
+export const promptCacheOptionsToWire = (
+    options: unknown,
+): PromptCacheOptions | undefined => {
+    if (options === undefined || options === null) return undefined;
+    if (typeof options !== 'object' || Array.isArray(options)) {
+        throw new HttpError(400, '`prompt_cache_options` must be an object', {
+            legacyCode: 'bad_request',
+        });
+    }
+    const { mode, ttl } = options as Record<string, unknown>;
+    if (mode !== undefined && !PROMPT_CACHE_MODES.has(mode as string)) {
+        throw new HttpError(
+            400,
+            '`prompt_cache_options.mode` must be `implicit` or `explicit`',
+            { legacyCode: 'bad_request' },
+        );
+    }
+    if (ttl !== undefined && !PROMPT_CACHE_TTLS.has(ttl as string)) {
+        throw new HttpError(
+            400,
+            '`prompt_cache_options.ttl` must be `30m` or `12h`',
+            { legacyCode: 'bad_request' },
+        );
+    }
+    const wire: PromptCacheOptions = {
+        ...(mode !== undefined
+            ? { mode: mode as PromptCacheOptions['mode'] }
+            : {}),
+        ...(ttl !== undefined ? { ttl: ttl as PromptCacheOptions['ttl'] } : {}),
+    };
+    return Object.keys(wire).length ? wire : undefined;
+};
+
+/**
+ * Whether any content part carries a `prompt_cache_breakpoint` with its own
+ * `ttl`. Chat Completions rejects the field whatever its value; only the
+ * Responses API honours a per-breakpoint lifetime.
+ */
+export const messagesHaveCacheBreakpointTtl = (messages: unknown): boolean =>
+    Array.isArray(messages) &&
+    messages.some((message) => {
+        const content = (message as { content?: unknown } | null)?.content;
+        const parts = Array.isArray(content) ? content : [content];
+        return parts.some(
+            (part) =>
+                (
+                    part as {
+                        prompt_cache_breakpoint?: { ttl?: unknown } | null;
+                    } | null
+                )?.prompt_cache_breakpoint?.ttl !== undefined,
+        );
+    });
+
 // -- Responses server-side state ---------------------------------------------
 
 const STATEFUL_RESPONSES_FIELDS = [

src/backend/drivers/ai-image/ImageGenerationDriver.test.ts

@@ -758,7 +758,10 @@ describe('ImageGenerationDriver.generate provider routing', () => {
             }),
         );
 
-        const reserveSpy = vi.spyOn(server.services.metering, 'reserveCredits');
+        const reserveSpy = vi.spyOn(
+            server.services.metering,
+            'reserveCreditsIfAffordable',
+        );
         const usageSpy = vi.spyOn(
             server.services.metering,
             'batchIncrementUsages',
@@ -852,7 +855,7 @@ describe('ImageGenerationDriver.generate provider routing', () => {
             });
             const reserveSpy = vi.spyOn(
                 server.services.metering,
-                'reserveCredits',
+                'reserveCreditsIfAffordable',
             );
 
             // Cloudflare answers the scheduled refresh with new rates at once;
@@ -1162,8 +1165,8 @@ describe('ImageGenerationDriver.generate Puter file inputs', () => {
         );
 
     beforeEach(() => {
-        vi.spyOn(server.services.metering, 'hasEnoughCredits').mockResolvedValue(
-            true,
+        vi.spyOn(server.services.metering, 'reserveCreditsIfAffordable').mockImplementation((who, amount, opts) =>
+            server.services.metering.reserveCredits(who, amount, opts),
         );
     });
 
@@ -1665,7 +1668,10 @@ it.each([undefined, null, '', '  ', 42, {}])(
 
 describe('ImageGenerationDriver cost factor', () => {
     it('holds and meters at the AI cost factor', async () => {
-        const reserveSpy = vi.spyOn(server.services.metering, 'reserveCredits');
+        const reserveSpy = vi.spyOn(
+            server.services.metering,
+            'reserveCreditsIfAffordable',
+        );
         const usageSpy = vi.spyOn(
             server.services.metering,
             'batchIncrementUsages',

src/backend/drivers/ai-image/providers/byteplus/BytePlusImageProvider.test.ts

@@ -72,7 +72,7 @@ vi.mock('openai', () => {
 // -- Test harness ----------------------------------------------------
 
 let server: PuterServer;
-let hasCreditsSpy: MockInstance<MeteringService['hasEnoughCredits']>;
+let admitSpy: MockInstance<MeteringService['reserveCreditsIfAffordable']>;
 let batchIncrementUsagesSpy: MockInstance<
     MeteringService['batchIncrementUsages']
 >;
@@ -107,7 +107,7 @@ const makeProvider = (
 beforeEach(() => {
     generateMock.mockReset();
     openAICtor.mockReset();
-    hasCreditsSpy = vi.spyOn(server.services.metering, 'hasEnoughCredits');
+    admitSpy = vi.spyOn(server.services.metering, 'reserveCreditsIfAffordable');
     batchIncrementUsagesSpy = vi.spyOn(
         server.services.metering,
         'batchIncrementUsages',
@@ -177,7 +177,7 @@ describe('BytePlusImageProvider.generate gates', () => {
         expect(result).toBe(
             'https://puter-sample-data.puter.site/image_example.png',
         );
-        expect(hasCreditsSpy).not.toHaveBeenCalled();
+        expect(admitSpy).not.toHaveBeenCalled();
         expect(generateMock).not.toHaveBeenCalled();
     });
 
@@ -196,7 +196,7 @@ describe('BytePlusImageProvider.generate gates', () => {
     });
 
     it('throws 402 BEFORE hitting ModelArk when the actor lacks credits', async () => {
-        hasCreditsSpy.mockResolvedValueOnce(false);
+        admitSpy.mockResolvedValueOnce(null);
         await expect(
             withTestActor(() => makeProvider().generate({ prompt: 'hi' })),
         ).rejects.toMatchObject({ statusCode: 402 });
@@ -713,7 +713,7 @@ it.each([
             }),
         ),
     ).rejects.toMatchObject({ statusCode: 400, legacyCode: 'bad_request' });
-    expect(hasCreditsSpy).not.toHaveBeenCalled();
+    expect(admitSpy).not.toHaveBeenCalled();
     expect(generateMock).not.toHaveBeenCalled();
 });
 

src/backend/drivers/ai-image/providers/cloudflare/CloudflareImageProvider.test.ts

@@ -73,7 +73,7 @@ let server: PuterServer;
 let globalFetchSpy: MockInstance<typeof fetch>;
 let fetchSpy: Mock<typeof fetch>;
 let modelSearchFetch: Mock<typeof fetch>;
-let hasCreditsSpy: MockInstance<MeteringService['hasEnoughCredits']>;
+let admitSpy: MockInstance<MeteringService['reserveCreditsIfAffordable']>;
 let batchIncrementUsagesSpy: MockInstance<
     MeteringService['batchIncrementUsages']
 >;
@@ -123,7 +123,7 @@ beforeEach(() => {
                 ? modelSearchFetch(input, init)
                 : fetchSpy(input, init),
         );
-    hasCreditsSpy = vi.spyOn(server.services.metering, 'hasEnoughCredits');
+    admitSpy = vi.spyOn(server.services.metering, 'reserveCreditsIfAffordable');
     batchIncrementUsagesSpy = vi.spyOn(
         server.services.metering,
         'batchIncrementUsages',
@@ -188,7 +188,7 @@ describe('CloudflareImageProvider.generate test_mode', () => {
         expect(result).toBe(
             'https://puter-sample-data.puter.site/image_example.png',
         );
-        expect(hasCreditsSpy).not.toHaveBeenCalled();
+        expect(admitSpy).not.toHaveBeenCalled();
         expect(fetchSpy).not.toHaveBeenCalled();
     });
 });
@@ -210,7 +210,7 @@ describe('CloudflareImageProvider.generate argument validation', () => {
 describe('CloudflareImageProvider.generate credit gate', () => {
     it('throws 402 BEFORE hitting Cloudflare when actor lacks credits', async () => {
         const provider = makeProvider();
-        hasCreditsSpy.mockResolvedValueOnce(false);
+        admitSpy.mockResolvedValueOnce(null);
 
         await expect(
             withTestActor(() => provider.generate({ prompt: 'hi' })),
@@ -240,7 +240,7 @@ describe('CloudflareImageProvider.generate credit gate', () => {
             actor,
         );
 
-        const [, estimate] = hasCreditsSpy.mock.calls[0]!;
+        const [, estimate] = admitSpy.mock.calls[0]!;
         expect(estimate).toBeGreaterThan(0);
         expect(heldDuringCall).toBe(Math.ceil(estimate));
         // The hold stays until the usage write lands.
@@ -708,7 +708,7 @@ describe('Cloudflare legacy image option', () => {
                 legacyCode: 'bad_request',
             });
             expect(fetchSpy).not.toHaveBeenCalled();
-            expect(hasCreditsSpy).not.toHaveBeenCalled();
+            expect(admitSpy).not.toHaveBeenCalled();
         },
     );
 
@@ -726,7 +726,7 @@ describe('Cloudflare legacy image option', () => {
             message: 'Invalid input image (empty or not base64)',
         });
         expect(fetchSpy).not.toHaveBeenCalled();
-        expect(hasCreditsSpy).not.toHaveBeenCalled();
+        expect(admitSpy).not.toHaveBeenCalled();
     });
 });
 
@@ -823,12 +823,12 @@ describe('Cloudflare priced legacy models', () => {
             imageSize: { kind: 'pixels', w: 512, h: 512 },
         }));
         expect(JSON.parse(fetchSpy.mock.calls[0]![1]!.body as string)).toMatchObject({ image: [1, 2, 3], mask: [4, 5, 6], num_steps: 20, width: 512, height: 512 });
-        expect(hasCreditsSpy).toHaveBeenCalledWith(expect.anything(), 0);
+        expect(admitSpy).toHaveBeenCalledWith(expect.anything(), 0, undefined);
     });
 
     it('rejects missing inpainting inputs before credit checks', async () => {
         await expect(withTestActor(() => makeProvider().generate({ model: '@cf/runwayml/stable-diffusion-v1-5-inpainting', prompt: 'A cup' }))).rejects.toMatchObject({ statusCode: 400 });
-        expect(hasCreditsSpy).not.toHaveBeenCalled();
+        expect(admitSpy).not.toHaveBeenCalled();
         expect(fetchSpy).not.toHaveBeenCalled();
     });
 
@@ -844,7 +844,7 @@ describe('Cloudflare priced legacy models', () => {
     it('charges Lucid at the price returned by the model API', async () => {
         fetchSpy.mockResolvedValueOnce(new Response(new Uint8Array([1, 2, 3]), { headers: { 'content-type': 'image/png' } }));
         await withTestActor(() => makeProvider().generate({ model: '@cf/leonardo/lucid-origin', prompt: 'A cup', imageSize: { kind: 'pixels', w: 512, h: 512 }, steps: 1 }));
-        expect(hasCreditsSpy).toHaveBeenCalledWith(expect.anything(), 713200);
+        expect(admitSpy).toHaveBeenCalledWith(expect.anything(), 713200, undefined);
     });
 });
 
@@ -897,9 +897,10 @@ describe('Cloudflare model-search pricing', () => {
         await runPhoenix(provider);
 
         expect(listed?.costs).toEqual({ tile_512: 1_000_000, step: 20_200 });
-        expect(hasCreditsSpy).toHaveBeenCalledWith(
+        expect(admitSpy).toHaveBeenCalledWith(
             expect.anything(),
             4 * 1_000_000 + 10 * 20_200,
+            undefined,
         );
         expect(batchIncrementUsagesSpy.mock.calls[0]![1]).toEqual([
             expect.objectContaining({
@@ -930,9 +931,10 @@ describe('Cloudflare model-search pricing', () => {
         await runPhoenix(makeProvider());
 
         expect(modelSearchFetch).not.toHaveBeenCalled();
-        expect(hasCreditsSpy).toHaveBeenCalledWith(
+        expect(admitSpy).toHaveBeenCalledWith(
             expect.anything(),
             4 * 583_000 + 10 * 11_000,
+            undefined,
         );
     });
 
@@ -955,7 +957,7 @@ describe('Cloudflare model-search pricing', () => {
         await refresh;
         await runPhoenix(provider);
 
-        expect(hasCreditsSpy.mock.calls.map(([, cost]) => cost)).toEqual([
+        expect(admitSpy.mock.calls.map(([, cost]) => cost)).toEqual([
             2_442_000, 4_202_000,
         ]);
     });
@@ -977,9 +979,10 @@ describe('Cloudflare model-search pricing', () => {
         await runPhoenix(provider);
 
         expect(modelSearchFetch).toHaveBeenCalledTimes(2);
-        expect(hasCreditsSpy).toHaveBeenCalledWith(
+        expect(admitSpy).toHaveBeenCalledWith(
             expect.anything(),
             4_202_000,
+            undefined,
         );
     });
 
@@ -1015,7 +1018,7 @@ describe('Cloudflare model-search pricing', () => {
                     steps: 10,
                 } as never),
             );
-            return hasCreditsSpy.mock.lastCall![1];
+            return admitSpy.mock.lastCall![1];
         };
         const settle = () => new Promise((resolve) => setImmediate(resolve));
         const OLD = { tile_512: 583_000, step: 11_000 };
@@ -1069,9 +1072,10 @@ describe('Cloudflare model-search pricing', () => {
             }),
         );
         expect(modelSearchFetch).toHaveBeenCalledOnce();
-        expect(hasCreditsSpy).toHaveBeenCalledWith(
+        expect(admitSpy).toHaveBeenCalledWith(
             expect.anything(),
             4 * 5280 + 4 * 10560,
+            undefined,
         );
     });
 

src/backend/drivers/ai-image/providers/gemini/GeminiImageProvider.test.ts

@@ -82,7 +82,7 @@ vi.mock('../../inputImage.js', async (orig) => ({
 // ── Test harness ────────────────────────────────────────────────────
 
 let server: PuterServer;
-let hasCreditsSpy: MockInstance<MeteringService['hasEnoughCredits']>;
+let admitSpy: MockInstance<MeteringService['reserveCreditsIfAffordable']>;
 let incrementUsageSpy: MockInstance<MeteringService['incrementUsage']>;
 let batchIncrementUsagesSpy: MockInstance<
     MeteringService['batchIncrementUsages']
@@ -111,7 +111,7 @@ beforeEach(() => {
     generateContentMock.mockReset();
     toBase64DataUriMock.mockReset();
     googleAICtor.mockReset();
-    hasCreditsSpy = vi.spyOn(server.services.metering, 'hasEnoughCredits');
+    admitSpy = vi.spyOn(server.services.metering, 'reserveCreditsIfAffordable');
     incrementUsageSpy = vi.spyOn(server.services.metering, 'incrementUsage');
     batchIncrementUsagesSpy = vi.spyOn(
         server.services.metering,
@@ -167,7 +167,7 @@ describe('GeminiImageProvider.generate test_mode', () => {
         expect(result).toBe(
             'https://puter-sample-data.puter.site/image_example.png',
         );
-        expect(hasCreditsSpy).not.toHaveBeenCalled();
+        expect(admitSpy).not.toHaveBeenCalled();
         expect(generateContentMock).not.toHaveBeenCalled();
     });
 });
@@ -219,7 +219,7 @@ describe('GeminiImageProvider.generate argument validation', () => {
                 legacyCode: 'bad_request',
                 message: expect.stringContaining('Unsupported quality tier'),
             });
-            expect(hasCreditsSpy).not.toHaveBeenCalled();
+            expect(admitSpy).not.toHaveBeenCalled();
             expect(generateContentMock).not.toHaveBeenCalled();
         },
     );
@@ -427,7 +427,7 @@ describe('GeminiImageProvider.generate Flash path (generateContent)', () => {
 
     it('throws 402 BEFORE hitting Gemini when actor lacks credits', async () => {
         const provider = makeProvider();
-        hasCreditsSpy.mockResolvedValueOnce(false);
+        admitSpy.mockResolvedValueOnce(null);
 
         await expect(
             withTestActor(() =>
@@ -466,7 +466,7 @@ describe('GeminiImageProvider.generate Flash path (generateContent)', () => {
             actor,
         );
 
-        const [, estimate] = hasCreditsSpy.mock.calls[0]!;
+        const [, estimate] = admitSpy.mock.calls[0]!;
         expect(estimate).toBeGreaterThan(0);
         expect(heldDuringCall).toBe(Math.ceil(estimate));
         // The hold stays until the usage write lands.
@@ -643,7 +643,7 @@ describe('Gemini Nano Banana image generation', () => {
         const request = generateContentMock.mock.calls[0][0];
         expect(request.config.imageConfig.imageSize).toBe('1K');
         // Input + 1120 image tokens at $30/1M + 1000 text tokens at $7.50/1M.
-        expect(hasCreditsSpy).toHaveBeenCalledWith(expect.anything(), 4_194_450);
+        expect(admitSpy).toHaveBeenCalledWith(expect.anything(), 4_194_450, undefined);
         expect(batchIncrementUsagesSpy).toHaveBeenCalledWith(
             expect.anything(),
             expect.arrayContaining([

src/backend/drivers/ai-image/providers/kling/KlingImageProvider.test.ts

@@ -50,7 +50,7 @@ import { KlingImageProvider } from './KlingImageProvider.js';
 
 let server: PuterServer;
 let fetchSpy: MockInstance<typeof fetch>;
-let hasCreditsSpy: MockInstance<MeteringService['hasEnoughCredits']>;
+let admitSpy: MockInstance<MeteringService['reserveCreditsIfAffordable']>;
 let incrementUsageSpy: MockInstance<MeteringService['incrementUsage']>;
 
 beforeAll(async () => {
@@ -73,7 +73,7 @@ const makeProvider = () =>
 
 beforeEach(() => {
     fetchSpy = vi.spyOn(globalThis, 'fetch') as MockInstance<typeof fetch>;
-    hasCreditsSpy = vi.spyOn(server.services.metering, 'hasEnoughCredits');
+    admitSpy = vi.spyOn(server.services.metering, 'reserveCreditsIfAffordable');
     incrementUsageSpy = vi.spyOn(server.services.metering, 'incrementUsage');
     incrementUsageSpy.mockResolvedValue({} as never);
 });
@@ -318,7 +318,7 @@ describe('KlingImageProvider billing', () => {
     });
 
     it('rejects before calling Kling when credits run short', async () => {
-        hasCreditsSpy.mockResolvedValueOnce(false);
+        admitSpy.mockResolvedValueOnce(null);
         await expect(generate({})).rejects.toMatchObject({ statusCode: 402 });
         expect(fetchSpy).not.toHaveBeenCalled();
     });

src/backend/drivers/ai-image/providers/openai/OpenAiImageProvider.test.ts

@@ -97,7 +97,7 @@ vi.mock('../../inputImage.js', async (orig) => ({
 // ── Test harness ────────────────────────────────────────────────────
 
 let server: PuterServer;
-let hasCreditsSpy: MockInstance<MeteringService['hasEnoughCredits']>;
+let admitSpy: MockInstance<MeteringService['reserveCreditsIfAffordable']>;
 let batchIncrementUsagesSpy: MockInstance<
     MeteringService['batchIncrementUsages']
 >;
@@ -126,7 +126,7 @@ beforeEach(() => {
     editMock.mockReset();
     fetchImageAsBase64Mock.mockReset();
     openAICtor.mockReset();
-    hasCreditsSpy = vi.spyOn(server.services.metering, 'hasEnoughCredits');
+    admitSpy = vi.spyOn(server.services.metering, 'reserveCreditsIfAffordable');
     batchIncrementUsagesSpy = vi.spyOn(
         server.services.metering,
         'batchIncrementUsages',
@@ -195,7 +195,7 @@ describe('OpenAiImageProvider.generate test_mode', () => {
         expect(result).toBe(
             'https://puter-sample-data.puter.site/image_example.png',
         );
-        expect(hasCreditsSpy).not.toHaveBeenCalled();
+        expect(admitSpy).not.toHaveBeenCalled();
         expect(generateMock).not.toHaveBeenCalled();
     });
 });
@@ -253,7 +253,8 @@ describe('OpenAiImageProvider.generate credit gate', () => {
         });
         let blocked = false;
         vi.spyOn(redis, 'meterIncr').mockImplementation(async (...args) => {
-            if (!blocked && args[5].includes(`:actor:${actor.user!.uuid}:`)) {
+            const actorKey = `:actor:${actor.user!.uuid}:`;
+            if (!blocked && args.some((arg) => arg.includes(actorKey))) {
                 blocked = true;
                 await held;
             }
@@ -287,7 +288,7 @@ describe('OpenAiImageProvider.generate credit gate', () => {
 
     it('throws 402 BEFORE hitting OpenAI when actor lacks credits', async () => {
         const provider = makeProvider();
-        hasCreditsSpy.mockResolvedValueOnce(false);
+        admitSpy.mockResolvedValueOnce(null);
         await expect(
             withTestActor(() =>
                 provider.generate({
@@ -323,7 +324,7 @@ describe('OpenAiImageProvider.generate credit gate', () => {
             actor,
         );
 
-        const [, estimate] = hasCreditsSpy.mock.calls[0]!;
+        const [, estimate] = admitSpy.mock.calls[0]!;
         expect(estimate).toBeGreaterThan(0);
         expect(heldDuringCall).toBe(Math.ceil(estimate));
         // The hold stays until the usage write lands.
@@ -727,8 +728,8 @@ describe('OpenAiImageProvider gpt-image-2.5 models', () => {
         );
 
         // Latent factor 48 vs 24 at the medium tier.
-        const gptImage2Estimate = hasCreditsSpy.mock.calls[0]![1];
-        const gptImage25Estimate = hasCreditsSpy.mock.calls[1]![1];
+        const gptImage2Estimate = admitSpy.mock.calls[0]![1];
+        const gptImage25Estimate = admitSpy.mock.calls[1]![1];
         expect(gptImage25Estimate).toBeLessThan(gptImage2Estimate);
     });
 
@@ -753,8 +754,8 @@ describe('OpenAiImageProvider gpt-image-2.5 models', () => {
             }),
         );
 
-        const highEstimate = hasCreditsSpy.mock.calls[0]![1];
-        const maxEstimate = hasCreditsSpy.mock.calls[1]![1];
+        const highEstimate = admitSpy.mock.calls[0]![1];
+        const maxEstimate = admitSpy.mock.calls[1]![1];
         expect(maxEstimate).toBeGreaterThan(highEstimate);
     });
 });

src/backend/drivers/ai-image/providers/replicate/ReplicateImageGenerationProvider.test.ts

@@ -84,7 +84,7 @@ vi.mock('../../../../util/secureHttp.js', () => ({
 // ── Test harness ────────────────────────────────────────────────────
 
 let server: PuterServer;
-let hasCreditsSpy: MockInstance<MeteringService['hasEnoughCredits']>;
+let admitSpy: MockInstance<MeteringService['reserveCreditsIfAffordable']>;
 let incrementUsageSpy: MockInstance<MeteringService['incrementUsage']>;
 let batchIncrementUsagesSpy: MockInstance<
     MeteringService['batchIncrementUsages']
@@ -115,7 +115,7 @@ beforeEach(() => {
     cancelMock.mockReset();
     replicateCtor.mockReset();
     secureFetchMock.mockReset();
-    hasCreditsSpy = vi.spyOn(server.services.metering, 'hasEnoughCredits');
+    admitSpy = vi.spyOn(server.services.metering, 'reserveCreditsIfAffordable');
     incrementUsageSpy = vi.spyOn(server.services.metering, 'incrementUsage');
     batchIncrementUsagesSpy = vi.spyOn(
         server.services.metering,
@@ -177,7 +177,7 @@ describe('ReplicateImageGenerationProvider.generate test_mode', () => {
         expect(result).toBe(
             'https://puter-sample-data.puter.site/image_example.png',
         );
-        expect(hasCreditsSpy).not.toHaveBeenCalled();
+        expect(admitSpy).not.toHaveBeenCalled();
         expect(createPredictionMock).not.toHaveBeenCalled();
     });
 });
@@ -199,7 +199,7 @@ describe('ReplicateImageGenerationProvider.generate argument validation', () =>
 describe('ReplicateImageGenerationProvider.generate credit gate', () => {
     it('throws 402 BEFORE hitting Replicate when actor lacks credits', async () => {
         const provider = makeProvider();
-        hasCreditsSpy.mockResolvedValueOnce(false);
+        admitSpy.mockResolvedValueOnce(null);
         await expect(
             withTestActor(() => provider.generate({ prompt: 'hi' })),
         ).rejects.toMatchObject({ statusCode: 402 });
@@ -255,7 +255,10 @@ describe('ReplicateImageGenerationProvider.generate credit gate', () => {
     it('holds credits for longer than a prediction can run', async () => {
         const provider = makeProvider();
         const actor = holdUser('ttl');
-        const reserveSpy = vi.spyOn(server.services.metering, 'reserveCredits');
+        const reserveSpy = vi.spyOn(
+            server.services.metering,
+            'reserveCreditsIfAffordable',
+        );
         createPredictionMock.mockResolvedValueOnce({
             id: 'ttl',
             status: 'succeeded',
@@ -274,7 +277,9 @@ describe('ReplicateImageGenerationProvider.generate credit gate', () => {
         const provider = makeProvider();
         const actor = holdUser('surcharge');
         secureFetchMock.mockResolvedValueOnce(new Response('not-an-image'));
-        hasCreditsSpy.mockResolvedValueOnce(true).mockResolvedValueOnce(false);
+        admitSpy.mockImplementationOnce((who, amount, opts) =>
+            server.services.metering.reserveCredits(who, amount, opts),
+        ).mockResolvedValueOnce(false);
 
         await expect(
             withTestActor(
@@ -950,7 +955,7 @@ it('does not start a prediction for an already-aborted request', async () => {
         ),
     ).rejects.toMatchObject({ statusCode: 400, legacyCode: 'client_aborted' });
     expect(createPredictionMock).not.toHaveBeenCalled();
-    expect(hasCreditsSpy).not.toHaveBeenCalled();
+    expect(admitSpy).not.toHaveBeenCalled();
 });
 
 it('stops polling and cancels at the prediction deadline', async () => {
@@ -1192,12 +1197,12 @@ it('rejects more than ten input images before fetching or pricing any', async ()
         ),
     ).rejects.toMatchObject({ statusCode: 400, legacyCode: 'bad_request' });
     expect(secureFetchMock).not.toHaveBeenCalled();
-    expect(hasCreditsSpy).not.toHaveBeenCalled();
+    expect(admitSpy).not.toHaveBeenCalled();
     expect(createPredictionMock).not.toHaveBeenCalled();
 });
 
 it('checks credits on the output-only estimate before fetching input images', async () => {
-    hasCreditsSpy.mockResolvedValueOnce(false);
+    admitSpy.mockResolvedValueOnce(null);
     await expect(
         withTestActor(() =>
             makeProvider().generate({

src/backend/drivers/ai-image/providers/together/TogetherImageProvider.test.ts

@@ -71,7 +71,7 @@ vi.mock('together-ai', () => {
 // ── Test harness ────────────────────────────────────────────────────
 
 let server: PuterServer;
-let hasCreditsSpy: MockInstance<MeteringService['hasEnoughCredits']>;
+let admitSpy: MockInstance<MeteringService['reserveCreditsIfAffordable']>;
 let incrementUsageSpy: MockInstance<MeteringService['incrementUsage']>;
 
 beforeAll(async () => {
@@ -96,7 +96,7 @@ const makeProvider = () =>
 beforeEach(() => {
     generateMock.mockReset();
     togetherCtor.mockReset();
-    hasCreditsSpy = vi.spyOn(server.services.metering, 'hasEnoughCredits');
+    admitSpy = vi.spyOn(server.services.metering, 'reserveCreditsIfAffordable');
     incrementUsageSpy = vi.spyOn(server.services.metering, 'incrementUsage');
 });
 
@@ -158,7 +158,7 @@ describe('TogetherImageProvider.generate test_mode', () => {
         expect(result).toBe(
             'https://puter-sample-data.puter.site/image_example.png',
         );
-        expect(hasCreditsSpy).not.toHaveBeenCalled();
+        expect(admitSpy).not.toHaveBeenCalled();
         expect(generateMock).not.toHaveBeenCalled();
     });
 });
@@ -189,7 +189,7 @@ describe('TogetherImageProvider.generate argument validation', () => {
 describe('TogetherImageProvider.generate credit gate', () => {
     it('throws 402 BEFORE hitting Together when actor lacks credits', async () => {
         const provider = makeProvider();
-        hasCreditsSpy.mockResolvedValueOnce(false);
+        admitSpy.mockResolvedValueOnce(null);
 
         await expect(
             withTestActor(() =>
@@ -760,7 +760,7 @@ describe('Together supported sizes and references', () => {
             width: 1024,
             height: 1024,
         });
-        expect(Number.isFinite(hasCreditsSpy.mock.calls[0][1])).toBe(true);
+        expect(Number.isFinite(admitSpy.mock.calls[0][1])).toBe(true);
     });
 
     it('resolves provider aliases without changing the selected model', async () => {
@@ -790,7 +790,7 @@ describe('Together supported sizes and references', () => {
                 }),
             ),
         ).rejects.toMatchObject({ statusCode: 400 });
-        expect(hasCreditsSpy).not.toHaveBeenCalled();
+        expect(admitSpy).not.toHaveBeenCalled();
         expect(generateMock).not.toHaveBeenCalled();
     });
 
@@ -859,7 +859,7 @@ it.each(['3K', 'unknown', ' 5k '])(
                 }),
             ),
         ).rejects.toMatchObject({ statusCode: 400, legacyCode: 'bad_request' });
-        expect(hasCreditsSpy).not.toHaveBeenCalled();
+        expect(admitSpy).not.toHaveBeenCalled();
         expect(generateMock).not.toHaveBeenCalled();
     },
 );
@@ -895,7 +895,7 @@ describe('Together current API prices', () => {
                 input_image: 'https://example.com/reference.png',
             }),
         );
-        expect(hasCreditsSpy).toHaveBeenCalledWith(expect.anything(), 4685000);
+        expect(admitSpy).toHaveBeenCalledWith(expect.anything(), 4685000, undefined);
         expect(incrementUsageSpy).toHaveBeenCalledWith(
             expect.anything(),
             'togetherai:google/flash-image-3.1:0.5K',

src/backend/drivers/ai-image/providers/xai/XAIImageProvider.test.ts

@@ -85,7 +85,7 @@ vi.mock('openai', () => {
 // ── Test harness ────────────────────────────────────────────────────
 
 let server: PuterServer;
-let hasCreditsSpy: MockInstance<MeteringService['hasEnoughCredits']>;
+let admitSpy: MockInstance<MeteringService['reserveCreditsIfAffordable']>;
 let batchIncrementUsagesSpy: MockInstance<
     MeteringService['batchIncrementUsages']
 >;
@@ -115,7 +115,7 @@ beforeEach(() => {
     openAICtor.mockReset();
     axiosGetMock.mockReset();
     axiosGetMock.mockRejectedValue(new Error('Catalog unavailable'));
-    hasCreditsSpy = vi.spyOn(server.services.metering, 'hasEnoughCredits');
+    admitSpy = vi.spyOn(server.services.metering, 'reserveCreditsIfAffordable');
     batchIncrementUsagesSpy = vi.spyOn(
         server.services.metering,
         'batchIncrementUsages',
@@ -182,7 +182,7 @@ describe('XAIImageProvider.generate test_mode', () => {
         expect(result).toBe(
             'https://puter-sample-data.puter.site/image_example.png',
         );
-        expect(hasCreditsSpy).not.toHaveBeenCalled();
+        expect(admitSpy).not.toHaveBeenCalled();
         expect(generateMock).not.toHaveBeenCalled();
         expect(batchIncrementUsagesSpy).not.toHaveBeenCalled();
     });
@@ -231,7 +231,7 @@ describe('XAIImageProvider.generate argument validation', () => {
 describe('XAIImageProvider.generate credit gate', () => {
     it('throws 402 BEFORE hitting xAI when actor lacks credits', async () => {
         const provider = makeProvider();
-        hasCreditsSpy.mockResolvedValueOnce(false);
+        admitSpy.mockResolvedValueOnce(null);
 
         await expect(
             withTestActor(() =>
@@ -718,7 +718,7 @@ describe('XAIImageProvider quality and reference limits', () => {
                 }),
             ),
         ).rejects.toMatchObject({ statusCode: 400 });
-        expect(hasCreditsSpy).not.toHaveBeenCalled();
+        expect(admitSpy).not.toHaveBeenCalled();
         expect(postMock).not.toHaveBeenCalled();
     });
 });
@@ -746,7 +746,7 @@ describe('xAI option validation', () => {
                 makeProvider().generate({ prompt: 'hi', ...options } as never),
             ),
         ).rejects.toMatchObject({ statusCode: 400 });
-        expect(hasCreditsSpy).not.toHaveBeenCalled();
+        expect(admitSpy).not.toHaveBeenCalled();
         expect(generateMock).not.toHaveBeenCalled();
     });
 });

src/backend/drivers/ai-ocr/OCRDriver.test.ts

@@ -167,7 +167,7 @@ const sentRegions = () =>
 
 let server: PuterServer;
 let driver: OCRDriver;
-let hasCreditsSpy: MockInstance<MeteringService['hasEnoughCredits']>;
+let admitSpy: MockInstance<MeteringService['reserveCreditsIfAffordable']>;
 let incrementUsageSpy: MockInstance<MeteringService['incrementUsage']>;
 
 beforeAll(async () => {
@@ -199,7 +199,7 @@ beforeEach(() => {
     mistralCtor.mockReset();
     // Spy on metering — keep the real impl so its recording side runs,
     // but capture calls so per-test assertions can inspect them.
-    hasCreditsSpy = vi.spyOn(server.services.metering, 'hasEnoughCredits');
+    admitSpy = vi.spyOn(server.services.metering, 'reserveCreditsIfAffordable');
     incrementUsageSpy = vi.spyOn(server.services.metering, 'incrementUsage');
 });
 
@@ -335,7 +335,7 @@ describe('OCRDriver.recognize (aws-textract)', () => {
     };
 
     it('throws 402 when the actor does not have enough credits', async () => {
-        hasCreditsSpy.mockResolvedValueOnce(false);
+        admitSpy.mockResolvedValueOnce(null);
         const { actor } = await makeUser();
 
         await expect(
@@ -546,7 +546,7 @@ describe('OCRDriver.recognize (aws-textract)', () => {
     describe('regional pricing', () => {
         const onePage = { Blocks: [{ BlockType: 'PAGE' }] };
         const checkedCosts = () =>
-            hasCreditsSpy.mock.calls.map(([, cost]) => cost);
+            admitSpy.mock.calls.map(([, cost]) => cost);
         const textractCharges = () =>
             incrementUsageSpy.mock.calls
                 .filter(([, type]) => type === TEXTRACT_USAGE)
@@ -719,7 +719,7 @@ describe('OCRDriver.recognize (mistral)', () => {
     };
 
     it('throws 402 when the actor does not have enough credits', async () => {
-        hasCreditsSpy.mockResolvedValueOnce(false);
+        admitSpy.mockResolvedValueOnce(null);
         const { actor } = await makeUser();
 
         await expect(
@@ -1033,7 +1033,7 @@ describe('OCRDriver.recognize (mistral)', () => {
         const pageType = 'mistral-ocr:mistral-ocr-4-1:page';
         const annotationType = 'mistral-ocr:mistral-ocr-4-1:annotations:page';
         // The pre-flight covers the page plus its annotation.
-        expect(hasCreditsSpy.mock.calls[0]![1]).toBe(
+        expect(admitSpy.mock.calls[0]![1]).toBe(
             OCR_COSTS[pageType] + OCR_COSTS[annotationType],
         );
         const ocrCalls = incrementUsageSpy.mock.calls.filter(
@@ -1080,7 +1080,7 @@ describe('OCRDriver credit pre-flight', () => {
     const pageType = 'mistral-ocr:mistral-ocr-4-1:page';
     const perPage = OCR_COSTS[pageType];
     const pdfSource = (buffer: Buffer) => dataUrl(buffer, 'application/pdf');
-    const checkedCosts = () => hasCreditsSpy.mock.calls.map(([, cost]) => cost);
+    const checkedCosts = () => admitSpy.mock.calls.map(([, cost]) => cost);
     const outstandingHolds = (actor: Actor) =>
         server.stores.creditHold.outstanding(actor.user.uuid!);
 
@@ -1171,8 +1171,8 @@ describe('OCRDriver credit pre-flight', () => {
             ),
         ).rejects.toMatchObject({ statusCode: 402 });
 
-        // The estimate/hold path (which calls hasEnoughCredits) never ran.
-        expect(hasCreditsSpy).not.toHaveBeenCalled();
+        // The estimate/hold path never ran.
+        expect(admitSpy).not.toHaveBeenCalled();
         expect(mistralOcrProcessMock).not.toHaveBeenCalled();
         noUsage.mockRestore();
     });

src/backend/drivers/ai-speech2speech/VoiceChangerDriver.test.ts

@@ -72,7 +72,7 @@ vi.mock('undici', async (importOriginal) => ({
 let server: PuterServer;
 let driver: VoiceChangerDriver;
 let fetchSpy: MockInstance<typeof fetch>;
-let hasCreditsSpy: MockInstance<MeteringService['hasEnoughCredits']>;
+let admitSpy: MockInstance<MeteringService['reserveCreditsIfAffordable']>;
 let incrementUsageSpy: MockInstance<MeteringService['incrementUsage']>;
 
 beforeAll(async () => {
@@ -91,7 +91,7 @@ afterAll(async () => {
 beforeEach(() => {
     webFetchMock.mockReset();
     fetchSpy = vi.spyOn(globalThis, 'fetch') as MockInstance<typeof fetch>;
-    hasCreditsSpy = vi.spyOn(server.services.metering, 'hasEnoughCredits');
+    admitSpy = vi.spyOn(server.services.metering, 'reserveCreditsIfAffordable');
     incrementUsageSpy = vi.spyOn(server.services.metering, 'incrementUsage');
 });
 
@@ -197,7 +197,7 @@ describe('VoiceChangerDriver.convert argument validation', () => {
 describe('VoiceChangerDriver.convert credit gate', () => {
     it('throws 402 BEFORE hitting ElevenLabs when the actor lacks credits', async () => {
         const { actor } = await makeUser();
-        hasCreditsSpy.mockResolvedValueOnce(false);
+        admitSpy.mockResolvedValueOnce(null);
 
         await expect(
             withActor(actor, () =>
@@ -387,7 +387,7 @@ describe('VoiceChangerDriver.convert success path', () => {
 
         const [base, factored] = metered();
         expect(factored).toBe(base! * 2);
-        const held = hasCreditsSpy.mock.calls.map(([, amount]) => amount);
+        const held = admitSpy.mock.calls.map(([, amount]) => amount);
         expect(held).toEqual([base, base! * 2]);
     });
 

src/backend/drivers/ai-speech2txt/SpeechToTextDriver.test.ts

@@ -122,7 +122,7 @@ vi.mock('openai', () => {
 
 let server: PuterServer;
 let driver: SpeechToTextDriver;
-let hasCreditsSpy: MockInstance<MeteringService['hasEnoughCredits']>;
+let admitSpy: MockInstance<MeteringService['reserveCreditsIfAffordable']>;
 let incrementUsageSpy: MockInstance<MeteringService['incrementUsage']>;
 
 beforeAll(async () => {
@@ -145,7 +145,7 @@ beforeEach(() => {
     toFileMock.mockClear();
     // Spy on metering — keep the real impl so its recording side runs,
     // but capture calls so per-test assertions can inspect them.
-    hasCreditsSpy = vi.spyOn(server.services.metering, 'hasEnoughCredits');
+    admitSpy = vi.spyOn(server.services.metering, 'reserveCreditsIfAffordable');
     incrementUsageSpy = vi.spyOn(server.services.metering, 'incrementUsage');
 });
 
@@ -360,7 +360,7 @@ describe('SpeechToTextDriver argument validation', () => {
 
 describe('SpeechToTextDriver credit gate', () => {
     it('throws 402 BEFORE hitting OpenAI when actor lacks credits', async () => {
-        hasCreditsSpy.mockResolvedValueOnce(false);
+        admitSpy.mockResolvedValueOnce(null);
         const { actor } = await makeUser();
 
         await expect(
@@ -686,7 +686,7 @@ describe('SpeechToTextDriver metering', () => {
         expect(cost).toBe(SPEECH_TO_TEXT_COSTS[usageType]);
     });
 
-    it('asks hasEnoughCredits for the same total it later meters', async () => {
+    it('reserves the same total it later meters', async () => {
         const { actor } = await makeUser();
         transcriptionsCreateMock.mockResolvedValueOnce({ text: 'x' });
 
@@ -700,7 +700,7 @@ describe('SpeechToTextDriver metering', () => {
 
         const usageType = 'openai:gpt-transcribe:second';
         const expected = SPEECH_TO_TEXT_COSTS[usageType] * 2;
-        const creditCall = hasCreditsSpy.mock.calls[0]!;
+        const creditCall = admitSpy.mock.calls[0]!;
         expect(creditCall[1]).toBe(expected);
     });
 
@@ -794,7 +794,7 @@ describe('SpeechToTextDriver metering', () => {
 
         const [base, factored] = metered();
         expect(factored).toBe(base! * 2);
-        const held = hasCreditsSpy.mock.calls.map(([, amount]) => amount);
+        const held = admitSpy.mock.calls.map(([, amount]) => amount);
         expect(held).toEqual([base, base! * 2]);
     });
 });

src/backend/drivers/ai-speech2txt/providers/gemini/GeminiSpeechToTextProvider.test.ts

@@ -72,7 +72,7 @@ const HOLD = COUNTED_TOKENS * AUDIO_RATE + 8192 * OUTPUT_RATE;
 let server: PuterServer;
 let sttDriver: SpeechToTextDriver;
 let fetchSpy: MockInstance<typeof fetch>;
-let hasCreditsSpy: MockInstance<MeteringService['hasEnoughCredits']>;
+let admitSpy: MockInstance<MeteringService['reserveCreditsIfAffordable']>;
 let batchSpy: MockInstance<MeteringService['batchIncrementUsages']>;
 
 const driver = {
@@ -102,7 +102,7 @@ beforeEach(() => {
         .mockRejectedValue(new Error('unexpected fetch')) as MockInstance<
         typeof fetch
     >;
-    hasCreditsSpy = vi.spyOn(server.services.metering, 'hasEnoughCredits');
+    admitSpy = vi.spyOn(server.services.metering, 'reserveCreditsIfAffordable');
     batchSpy = vi.spyOn(server.services.metering, 'batchIncrementUsages');
 });
 
@@ -220,13 +220,16 @@ const metered = (): UsageInput[] =>
 /** Records each credit hold taken, its options, and its release. */
 const trackHolds = (order: string[] = []) => {
     const metering = server.services.metering;
-    const realReserve = metering.reserveCredits.bind(metering);
+    const realReserve = Object.getPrototypeOf(
+        metering,
+    ).reserveCreditsIfAffordable.bind(metering) as typeof metering.reserveCreditsIfAffordable;
     const held: { amount: number; ttlMs?: number }[] = [];
     const released = vi.fn();
-    vi.spyOn(metering, 'reserveCredits').mockImplementation(
+    vi.spyOn(metering, 'reserveCreditsIfAffordable').mockImplementation(
         async (actor, amount, opts) => {
             held.push({ amount, ttlMs: opts?.ttlMs });
             const hold = await realReserve(actor, amount, opts);
+            if (!hold) return null;
             return {
                 ...hold,
                 release: async () => {
@@ -425,7 +428,7 @@ describe('GeminiSpeechToTextProvider test_mode', () => {
             model: MODEL,
         });
         expect(fetchSpy).not.toHaveBeenCalled();
-        expect(hasCreditsSpy).not.toHaveBeenCalled();
+        expect(admitSpy).not.toHaveBeenCalled();
         expect(batchSpy).not.toHaveBeenCalled();
     });
 
@@ -1263,12 +1266,12 @@ describe('GeminiSpeechToTextProvider countTokens preflight', () => {
 describe('GeminiSpeechToTextProvider credit hold', () => {
     it('throws 402 after counting tokens, before transcribing', async () => {
         const { actor } = await makeUser();
-        hasCreditsSpy.mockResolvedValueOnce(false);
+        admitSpy.mockResolvedValueOnce(null);
         fetchSpy.mockResolvedValueOnce(Response.json({ totalTokens: 91 }));
         await expect(
             withActor(actor, () => driver.transcribe({ file: dataUrl() })),
         ).rejects.toMatchObject({ statusCode: 402 });
-        expect(hasCreditsSpy.mock.calls[0]![1]).toBe(HOLD);
+        expect(admitSpy.mock.calls[0]![1]).toBe(HOLD);
         expect(fetchSpy).toHaveBeenCalledTimes(1);
         expect(batchSpy).not.toHaveBeenCalled();
     });

src/backend/drivers/ai-speech2txt/providers/xai/XAISpeechToTextProvider.test.ts

@@ -70,7 +70,7 @@ const driver = {
     getReportedCosts: () => sttDriver.getReportedCosts(),
 };
 let fetchSpy: MockInstance<typeof fetch>;
-let hasCreditsSpy: MockInstance<MeteringService['hasEnoughCredits']>;
+let admitSpy: MockInstance<MeteringService['reserveCreditsIfAffordable']>;
 let incrementUsageSpy: MockInstance<MeteringService['incrementUsage']>;
 
 beforeAll(async () => {
@@ -88,7 +88,7 @@ afterAll(async () => {
 
 beforeEach(() => {
     fetchSpy = vi.spyOn(globalThis, 'fetch') as MockInstance<typeof fetch>;
-    hasCreditsSpy = vi.spyOn(server.services.metering, 'hasEnoughCredits');
+    admitSpy = vi.spyOn(server.services.metering, 'reserveCreditsIfAffordable');
     incrementUsageSpy = vi.spyOn(server.services.metering, 'incrementUsage');
 });
 
@@ -193,7 +193,7 @@ describe('XAISpeechToTextProvider test_mode', () => {
         expect(Array.isArray(result.words)).toBe(true);
         // No file required, no actor required, no fetch / metering hit.
         expect(fetchSpy).not.toHaveBeenCalled();
-        expect(hasCreditsSpy).not.toHaveBeenCalled();
+        expect(admitSpy).not.toHaveBeenCalled();
         expect(incrementUsageSpy).not.toHaveBeenCalled();
     });
 
@@ -258,7 +258,7 @@ describe('XAISpeechToTextProvider missing API key', () => {
 
 describe('XAISpeechToTextProvider credit gate', () => {
     it('throws 402 BEFORE hitting xAI when actor lacks credits', async () => {
-        hasCreditsSpy.mockResolvedValueOnce(false);
+        admitSpy.mockResolvedValueOnce(null);
         const { actor } = await makeUser();
 
         await expect(
@@ -273,7 +273,7 @@ describe('XAISpeechToTextProvider credit gate', () => {
         expect(incrementUsageSpy).not.toHaveBeenCalled();
     });
 
-    it('asks hasEnoughCredits for estimated seconds × per-second ucents', async () => {
+    it('reserves estimated seconds × per-second ucents', async () => {
         const { actor } = await makeUser();
         fetchSpy.mockResolvedValueOnce(
             sttResponse({ text: 'ok', duration: 1 }),
@@ -285,7 +285,7 @@ describe('XAISpeechToTextProvider credit gate', () => {
             driver.transcribe({ file: dataUrl(audio, 'audio/mp3') }),
         );
 
-        expect(hasCreditsSpy.mock.calls[0]![1]).toBe(UCENTS_PER_SECOND * 2);
+        expect(admitSpy.mock.calls[0]![1]).toBe(UCENTS_PER_SECOND * 2);
     });
 
     it('estimates 60 seconds for URL inputs (we cannot inspect size locally)', async () => {
@@ -298,7 +298,7 @@ describe('XAISpeechToTextProvider credit gate', () => {
             driver.transcribe({ file: 'https://example.com/clip.mp3' }),
         );
 
-        expect(hasCreditsSpy.mock.calls[0]![1]).toBe(UCENTS_PER_SECOND * 60);
+        expect(admitSpy.mock.calls[0]![1]).toBe(UCENTS_PER_SECOND * 60);
     });
 });
 

src/backend/drivers/ai-tts/TTSDriver.test.ts

@@ -699,9 +699,9 @@ describe('TTSDriver cost factor', () => {
             server.services.metering,
             'incrementUsage',
         );
-        const hasCreditsSpy = vi.spyOn(
+        const admitSpy = vi.spyOn(
             server.services.metering,
-            'hasEnoughCredits',
+            'reserveCreditsIfAffordable',
         );
         const metered = () =>
             incrementUsageSpy.mock.calls.map(([, , , cost]) => cost!);
@@ -725,7 +725,7 @@ describe('TTSDriver cost factor', () => {
         const [base, factored] = metered();
         expect(base).toBeGreaterThan(0);
         expect(factored).toBe(Math.round(base! * 2));
-        const held = hasCreditsSpy.mock.calls.map(([, amount]) => amount);
+        const held = admitSpy.mock.calls.map(([, amount]) => amount);
         expect(held).toEqual([base, Math.round(base! * 2)]);
     });
 });

src/backend/drivers/ai-tts/providers/awsPolly/AWSPollyTTSProvider.test.ts

@@ -84,7 +84,7 @@ vi.mock('@aws-sdk/client-polly', async () => {
 
 let server: PuterServer;
 let priceFetch: MockInstance<typeof fetch>;
-let hasCreditsSpy: MockInstance<MeteringService['hasEnoughCredits']>;
+let admitSpy: MockInstance<MeteringService['reserveCreditsIfAffordable']>;
 let incrementUsageSpy: MockInstance<MeteringService['incrementUsage']>;
 
 beforeAll(async () => {
@@ -180,7 +180,7 @@ beforeEach(() => {
     pollyCtor.mockReset();
     priceFetch = vi.fn(servePriceLists());
     vi.stubGlobal('fetch', priceFetch);
-    hasCreditsSpy = vi.spyOn(server.services.metering, 'hasEnoughCredits');
+    admitSpy = vi.spyOn(server.services.metering, 'reserveCreditsIfAffordable');
     incrementUsageSpy = vi.spyOn(server.services.metering, 'incrementUsage');
 });
 
@@ -314,7 +314,7 @@ describe('AWSPollyTTSProvider.synthesize test_mode', () => {
             url: 'https://puter-sample-data.puter.site/tts_example.mp3',
             content_type: 'audio',
         });
-        expect(hasCreditsSpy).not.toHaveBeenCalled();
+        expect(admitSpy).not.toHaveBeenCalled();
         expect(pollySendMock).not.toHaveBeenCalled();
     });
 });
@@ -349,7 +349,7 @@ describe('AWSPollyTTSProvider.synthesize argument validation', () => {
 describe('AWSPollyTTSProvider.synthesize credit gate', () => {
     it('throws 402 BEFORE hitting Polly when actor lacks credits', async () => {
         const provider = makeProvider();
-        hasCreditsSpy.mockResolvedValueOnce(false);
+        admitSpy.mockResolvedValueOnce(null);
         sendDispatch();
 
         await expect(
@@ -481,7 +481,7 @@ describe('AWSPollyTTSProvider.synthesize metering', () => {
         expect(cost).toBe(expectedCost);
     });
 
-    it('asks for hasEnoughCredits with the same total it later meters', async () => {
+    it('reserves the same total it later meters', async () => {
         const provider = makeProvider();
         sendDispatch();
 
@@ -495,7 +495,7 @@ describe('AWSPollyTTSProvider.synthesize metering', () => {
         );
 
         const expectedCost = AWS_POLLY_COSTS['generative'] * text.length;
-        expect(hasCreditsSpy.mock.calls[0]![1]).toBe(expectedCost);
+        expect(admitSpy.mock.calls[0]![1]).toBe(expectedCost);
     });
 });
 
@@ -599,7 +599,7 @@ describe('AWSPollyTTSProvider published pricing', () => {
             engine: 'generative',
         });
 
-        expect(hasCreditsSpy.mock.calls.map((c) => c[1])).toEqual([
+        expect(admitSpy.mock.calls.map((c) => c[1])).toEqual([
             1700 * 5,
             3000 * 5,
         ]);
@@ -648,7 +648,7 @@ describe('AWSPollyTTSProvider published pricing', () => {
         await readStreamResult(result);
 
         expect(refreshedNeural).toBe(19);
-        expect(hasCreditsSpy.mock.calls[0]![1]).toBe(1700 * 5);
+        expect(admitSpy.mock.calls[0]![1]).toBe(1700 * 5);
         expect(incrementUsageSpy.mock.calls[0]![3]).toBe(1700 * 5);
     });
 

src/backend/drivers/ai-tts/providers/common.test.ts

@@ -86,8 +86,10 @@ describe('meterPerCharacter', () => {
 
     it('holds and then meters exactly text length × price', async () => {
         const check = vi
-            .spyOn(server.services.metering, 'hasEnoughCredits')
-            .mockResolvedValue(true);
+            .spyOn(server.services.metering, 'reserveCreditsIfAffordable')
+            .mockImplementation((who, amount, opts) =>
+                server.services.metering.reserveCredits(who, amount, opts),
+            );
         const record = vi.spyOn(server.services.metering, 'incrementUsage');
 
         await drain(
@@ -101,7 +103,7 @@ describe('meterPerCharacter', () => {
             ),
         );
 
-        expect(check).toHaveBeenCalledWith(actor, 7500);
+        expect(check).toHaveBeenCalledWith(actor, 7500, undefined);
         expect(record).toHaveBeenCalledWith(
             actor,
             'openai:tts-1:character',
@@ -118,8 +120,10 @@ describe('meterPerCharacter', () => {
     it('meters nothing when the upstream breaks before any audio', async () => {
         vi.spyOn(
             server.services.metering,
-            'hasEnoughCredits',
-        ).mockResolvedValue(true);
+            'reserveCreditsIfAffordable',
+        ).mockImplementation((who, amount, opts) =>
+            server.services.metering.reserveCredits(who, amount, opts),
+        );
         const record = vi.spyOn(server.services.metering, 'incrementUsage');
 
         await drain(
@@ -139,8 +143,10 @@ describe('meterPerCharacter', () => {
     it('meters the full text once audio has started, even if the upstream then breaks', async () => {
         vi.spyOn(
             server.services.metering,
-            'hasEnoughCredits',
-        ).mockResolvedValue(true);
+            'reserveCreditsIfAffordable',
+        ).mockImplementation((who, amount, opts) =>
+            server.services.metering.reserveCredits(who, amount, opts),
+        );
         const record = vi.spyOn(server.services.metering, 'incrementUsage');
 
         await drain(
@@ -165,8 +171,10 @@ describe('meterPerCharacter', () => {
     it('meters the full text when the caller hangs up before any audio', async () => {
         vi.spyOn(
             server.services.metering,
-            'hasEnoughCredits',
-        ).mockResolvedValue(true);
+            'reserveCreditsIfAffordable',
+        ).mockImplementation((who, amount, opts) =>
+            server.services.metering.reserveCredits(who, amount, opts),
+        );
         const record = vi.spyOn(server.services.metering, 'incrementUsage');
 
         const result = await meterPerCharacter(
@@ -192,8 +200,10 @@ describe('meterPerCharacter', () => {
     it('meters nothing when synthesis fails', async () => {
         vi.spyOn(
             server.services.metering,
-            'hasEnoughCredits',
-        ).mockResolvedValue(true);
+            'reserveCreditsIfAffordable',
+        ).mockImplementation((who, amount, opts) =>
+            server.services.metering.reserveCredits(who, amount, opts),
+        );
         const record = vi.spyOn(server.services.metering, 'incrementUsage');
         const boom = new Error('vendor down');
 
@@ -213,8 +223,8 @@ describe('meterPerCharacter', () => {
     it('refuses with a 402 before synthesizing when unaffordable', async () => {
         vi.spyOn(
             server.services.metering,
-            'hasEnoughCredits',
-        ).mockResolvedValue(false);
+            'reserveCreditsIfAffordable',
+        ).mockResolvedValue(null);
         const synthesize = vi.fn(audio);
 
         await expect(

src/backend/drivers/ai-tts/providers/elevenlabs/ElevenLabsTTSProvider.test.ts

@@ -57,7 +57,7 @@ import { ELEVENLABS_TTS_COSTS } from './costs.js';
 
 let server: PuterServer;
 let fetchSpy: MockInstance<typeof fetch>;
-let hasCreditsSpy: MockInstance<MeteringService['hasEnoughCredits']>;
+let admitSpy: MockInstance<MeteringService['reserveCreditsIfAffordable']>;
 let incrementUsageSpy: MockInstance<MeteringService['incrementUsage']>;
 
 beforeAll(async () => {
@@ -88,7 +88,7 @@ const audioResponse = (body = 'audio-bytes', contentType = 'audio/mpeg') =>
 
 beforeEach(() => {
     fetchSpy = vi.spyOn(globalThis, 'fetch') as MockInstance<typeof fetch>;
-    hasCreditsSpy = vi.spyOn(server.services.metering, 'hasEnoughCredits');
+    admitSpy = vi.spyOn(server.services.metering, 'reserveCreditsIfAffordable');
     incrementUsageSpy = vi.spyOn(server.services.metering, 'incrementUsage');
 });
 
@@ -283,7 +283,7 @@ describe('ElevenLabsTTSProvider.synthesize test_mode', () => {
             url: 'https://puter-sample-data.puter.site/tts_example.mp3',
             content_type: 'audio',
         });
-        expect(hasCreditsSpy).not.toHaveBeenCalled();
+        expect(admitSpy).not.toHaveBeenCalled();
         expect(fetchSpy).not.toHaveBeenCalled();
     });
 });
@@ -323,7 +323,7 @@ describe('ElevenLabsTTSProvider.synthesize argument validation', () => {
         });
 
         expect(fetchSpy).not.toHaveBeenCalled();
-        expect(hasCreditsSpy).not.toHaveBeenCalled();
+        expect(admitSpy).not.toHaveBeenCalled();
         expect(incrementUsageSpy).not.toHaveBeenCalled();
     });
 
@@ -358,7 +358,7 @@ describe('ElevenLabsTTSProvider.synthesize argument validation', () => {
 describe('ElevenLabsTTSProvider.synthesize credit gate', () => {
     it('throws 402 BEFORE hitting ElevenLabs when actor lacks credits', async () => {
         const provider = makeProvider();
-        hasCreditsSpy.mockResolvedValueOnce(false);
+        admitSpy.mockResolvedValueOnce(null);
 
         await expect(
             withTestActor(() => provider.synthesize({ text: 'hi' })),
@@ -510,7 +510,7 @@ describe('ElevenLabsTTSProvider.synthesize request shape', () => {
                 fields: { key, got: value },
             });
             expect(fetchSpy).not.toHaveBeenCalled();
-            expect(hasCreditsSpy).not.toHaveBeenCalled();
+            expect(admitSpy).not.toHaveBeenCalled();
             expect(incrementUsageSpy).not.toHaveBeenCalled();
         },
     );
@@ -893,7 +893,7 @@ describe('ElevenLabsTTSProvider.synthesize metering', () => {
         expect(cost).toBe(expectedCost);
     });
 
-    it('asks for hasEnoughCredits with the same total it later meters', async () => {
+    it('reserves the same total it later meters', async () => {
         const provider = makeProvider();
         fetchSpy.mockResolvedValueOnce(audioResponse());
 
@@ -904,7 +904,7 @@ describe('ElevenLabsTTSProvider.synthesize metering', () => {
 
         const expectedCost =
             ELEVENLABS_TTS_COSTS['eleven_multilingual_v2'] * text.length;
-        expect(hasCreditsSpy.mock.calls[0]![1]).toBe(expectedCost);
+        expect(admitSpy.mock.calls[0]![1]).toBe(expectedCost);
     });
 });
 

src/backend/drivers/ai-tts/providers/gemini/GeminiTTSProvider.test.ts

@@ -61,7 +61,7 @@ const INTERACTIONS_URL =
 
 let server: PuterServer;
 let fetchSpy: MockInstance<typeof fetch>;
-let hasCreditsSpy: MockInstance<MeteringService['hasEnoughCredits']>;
+let admitSpy: MockInstance<MeteringService['reserveCreditsIfAffordable']>;
 let batchIncrementUsagesSpy: MockInstance<
     MeteringService['batchIncrementUsages']
 >;
@@ -183,13 +183,16 @@ const payingUser = () =>
 /** Spies on the credit holds taken, recording the amount and each release. */
 const trackHolds = () => {
     const metering = server.services.metering;
-    const realReserve = metering.reserveCredits.bind(metering);
+    const realReserve = Object.getPrototypeOf(
+        metering,
+    ).reserveCreditsIfAffordable.bind(metering) as typeof metering.reserveCreditsIfAffordable;
     const held: number[] = [];
     const released = vi.fn();
-    vi.spyOn(metering, 'reserveCredits').mockImplementation(
+    vi.spyOn(metering, 'reserveCreditsIfAffordable').mockImplementation(
         async (actor, amount, opts) => {
             held.push(amount);
             const hold = await realReserve(actor, amount, opts);
+            if (!hold) return null;
             return {
                 ...hold,
                 release: async () => {
@@ -214,7 +217,7 @@ beforeEach(() => {
         .mockRejectedValue(new Error('unexpected fetch')) as MockInstance<
         typeof fetch
     >;
-    hasCreditsSpy = vi.spyOn(server.services.metering, 'hasEnoughCredits');
+    admitSpy = vi.spyOn(server.services.metering, 'reserveCreditsIfAffordable');
     batchIncrementUsagesSpy = vi.spyOn(
         server.services.metering,
         'batchIncrementUsages',
@@ -332,7 +335,7 @@ describe('GeminiTTSProvider.synthesize test_mode', () => {
             url: 'https://puter-sample-data.puter.site/tts_example.mp3',
             content_type: 'audio',
         });
-        expect(hasCreditsSpy).not.toHaveBeenCalled();
+        expect(admitSpy).not.toHaveBeenCalled();
         expect(fetchSpy).not.toHaveBeenCalled();
     });
 });
@@ -406,7 +409,7 @@ describe('GeminiTTSProvider.synthesize argument validation', () => {
             legacyCode: 'input_too_large',
             fields: { key: 'text', max: 3000 },
         });
-        expect(hasCreditsSpy).not.toHaveBeenCalled();
+        expect(admitSpy).not.toHaveBeenCalled();
         expect(fetchSpy).not.toHaveBeenCalled();
     });
 
@@ -434,7 +437,7 @@ describe('GeminiTTSProvider.synthesize argument validation', () => {
             legacyCode: 'input_too_large',
             fields: { key: 'instructions', max: 3000 },
         });
-        expect(hasCreditsSpy).not.toHaveBeenCalled();
+        expect(admitSpy).not.toHaveBeenCalled();
         expect(fetchSpy).not.toHaveBeenCalled();
     });
 });
@@ -443,7 +446,7 @@ describe('GeminiTTSProvider.synthesize argument validation', () => {
 
 describe('GeminiTTSProvider.synthesize credit gate', () => {
     it('throws 402 before calling Gemini when the actor lacks credits', async () => {
-        hasCreditsSpy.mockResolvedValueOnce(false);
+        admitSpy.mockResolvedValueOnce(null);
         await expect(
             withTestActor(() => makeProvider().synthesize({ text: 'hi' })),
         ).rejects.toMatchObject({ statusCode: 402 });
@@ -473,9 +476,10 @@ describe('GeminiTTSProvider.synthesize credit gate', () => {
                         actor,
                     ),
                 ).rejects.toMatchObject({ statusCode: 402 });
-                expect(hasCreditsSpy).toHaveBeenCalledWith(
+                expect(admitSpy).toHaveBeenCalledWith(
                     actor,
                     FLASH_RESERVATION,
+                    undefined,
                 );
                 expect(fetchSpy).not.toHaveBeenCalled();
                 expect(batchIncrementUsagesSpy).not.toHaveBeenCalled();
@@ -1365,9 +1369,10 @@ describe('GeminiTTSProvider.synthesize scheduled rates', () => {
                 server.clients.event.off('ai.cost.factor.*', factor);
             }
 
-            expect(hasCreditsSpy).toHaveBeenCalledWith(
+            expect(admitSpy).toHaveBeenCalledWith(
                 expect.anything(),
                 reserved * 1.5,
+                undefined,
             );
             expect(held).toEqual([reserved * 1.5]);
             expect(metered(':input').costOverride).toBe(7 * inputRate * 1.5);

src/backend/drivers/ai-tts/providers/openai/OpenAITTSProvider.test.ts

@@ -84,7 +84,7 @@ vi.mock('openai', () => {
 // ── Test harness ────────────────────────────────────────────────────
 
 let server: PuterServer;
-let hasCreditsSpy: MockInstance<MeteringService['hasEnoughCredits']>;
+let admitSpy: MockInstance<MeteringService['reserveCreditsIfAffordable']>;
 let incrementUsageSpy: MockInstance<MeteringService['incrementUsage']>;
 
 beforeAll(async () => {
@@ -108,7 +108,7 @@ const mockAudioResponse = (bytes = 'opus-audio') => new Response(bytes);
 beforeEach(() => {
     speechCreateMock.mockReset();
     openAICtor.mockReset();
-    hasCreditsSpy = vi.spyOn(server.services.metering, 'hasEnoughCredits');
+    admitSpy = vi.spyOn(server.services.metering, 'reserveCreditsIfAffordable');
     incrementUsageSpy = vi.spyOn(server.services.metering, 'incrementUsage');
 });
 
@@ -205,7 +205,7 @@ describe('OpenAITTSProvider.synthesize test_mode', () => {
             url: 'https://puter-sample-data.puter.site/tts_example.mp3',
             content_type: 'audio',
         });
-        expect(hasCreditsSpy).not.toHaveBeenCalled();
+        expect(admitSpy).not.toHaveBeenCalled();
         expect(speechCreateMock).not.toHaveBeenCalled();
     });
 });
@@ -283,7 +283,7 @@ describe('OpenAITTSProvider.synthesize argument validation', () => {
 describe('OpenAITTSProvider.synthesize credit gate', () => {
     it('throws 402 BEFORE hitting OpenAI when actor lacks credits', async () => {
         const provider = makeProvider();
-        hasCreditsSpy.mockResolvedValueOnce(false);
+        admitSpy.mockResolvedValueOnce(null);
 
         await expect(
             withTestActor(() => provider.synthesize({ text: 'hi' })),
@@ -298,7 +298,9 @@ describe('OpenAITTSProvider.synthesize credit gate', () => {
             user: { id: 7, uuid: `tts-hold-${Date.now()}`, username: 'hold' },
         });
         const userId = actor.user!.uuid;
-        hasCreditsSpy.mockResolvedValue(true);
+        admitSpy.mockImplementation((who, amount, opts) =>
+            server.services.metering.reserveCredits(who, amount, opts),
+        );
         let heldDuringCall = -1;
         speechCreateMock.mockImplementationOnce(async () => {
             heldDuringCall = await server.stores.creditHold.outstanding(userId);
@@ -324,7 +326,9 @@ describe('OpenAITTSProvider.synthesize credit gate', () => {
         const actor = makeActor({
             user: { id: 8, uuid: `tts-fail-${Date.now()}`, username: 'fail' },
         });
-        hasCreditsSpy.mockResolvedValue(true);
+        admitSpy.mockImplementation((who, amount, opts) =>
+            server.services.metering.reserveCredits(who, amount, opts),
+        );
         speechCreateMock.mockRejectedValueOnce(new Error('upstream down'));
 
         await expect(
@@ -463,7 +467,7 @@ describe('OpenAITTSProvider.synthesize metering', () => {
         expect(cost).toBe(expectedCost);
     });
 
-    it('asks for hasEnoughCredits with the same total it later meters', async () => {
+    it('reserves the same total it later meters', async () => {
         const provider = makeProvider();
         speechCreateMock.mockResolvedValueOnce(mockAudioResponse());
 
@@ -473,8 +477,8 @@ describe('OpenAITTSProvider.synthesize metering', () => {
         );
 
         const expectedCost = OPENAI_TTS_COSTS['tts-1'] * text.length;
-        // First call to hasEnoughCredits should match the metered cost.
-        const creditCall = hasCreditsSpy.mock.calls[0]!;
+        // The first reservation should match the metered cost.
+        const creditCall = admitSpy.mock.calls[0]!;
         expect(creditCall[1]).toBe(expectedCost);
     });
 });

src/backend/drivers/ai-tts/providers/speechify/SpeechifyTTSProvider.test.ts

@@ -56,7 +56,7 @@ import { SPEECHIFY_TTS_COSTS } from './costs.js';
 
 let server: PuterServer;
 let fetchSpy: MockInstance<typeof fetch>;
-let hasCreditsSpy: MockInstance<MeteringService['hasEnoughCredits']>;
+let admitSpy: MockInstance<MeteringService['reserveCreditsIfAffordable']>;
 let incrementUsageSpy: MockInstance<MeteringService['incrementUsage']>;
 
 beforeAll(async () => {
@@ -82,7 +82,7 @@ const audioResponse = (audioData = Buffer.from('audio-bytes').toString('base64')
 
 beforeEach(() => {
     fetchSpy = vi.spyOn(globalThis, 'fetch') as MockInstance<typeof fetch>;
-    hasCreditsSpy = vi.spyOn(server.services.metering, 'hasEnoughCredits');
+    admitSpy = vi.spyOn(server.services.metering, 'reserveCreditsIfAffordable');
     incrementUsageSpy = vi.spyOn(server.services.metering, 'incrementUsage');
 });
 
@@ -159,7 +159,7 @@ describe('SpeechifyTTSProvider.synthesize test_mode', () => {
             url: 'https://puter-sample-data.puter.site/tts_example.mp3',
             content_type: 'audio',
         });
-        expect(hasCreditsSpy).not.toHaveBeenCalled();
+        expect(admitSpy).not.toHaveBeenCalled();
         expect(fetchSpy).not.toHaveBeenCalled();
     });
 });
@@ -206,7 +206,7 @@ describe('SpeechifyTTSProvider.synthesize argument validation', () => {
 describe('SpeechifyTTSProvider.synthesize credit gate', () => {
     it('throws 402 BEFORE hitting Speechify when actor lacks credits', async () => {
         const provider = makeProvider();
-        hasCreditsSpy.mockResolvedValueOnce(false);
+        admitSpy.mockResolvedValueOnce(null);
 
         await expect(
             withTestActor(() => provider.synthesize({ text: 'hi' })),
@@ -324,7 +324,7 @@ describe('SpeechifyTTSProvider.synthesize metering', () => {
         expect(cost).toBe(expectedCost);
     });
 
-    it('asks for hasEnoughCredits with the same total it later meters', async () => {
+    it('reserves the same total it later meters', async () => {
         const provider = makeProvider();
         fetchSpy.mockResolvedValueOnce(audioResponse());
 
@@ -332,7 +332,7 @@ describe('SpeechifyTTSProvider.synthesize metering', () => {
         await withTestActor(() => provider.synthesize({ text }));
 
         const expectedCost = SPEECHIFY_TTS_COSTS['simba-3.2'] * text.length;
-        expect(hasCreditsSpy.mock.calls[0]![1]).toBe(expectedCost);
+        expect(admitSpy.mock.calls[0]![1]).toBe(expectedCost);
     });
 });
 

src/backend/drivers/ai-tts/providers/xai/XAITTSProvider.test.ts

@@ -56,7 +56,7 @@ import { XAI_TTS_COSTS } from './costs.js';
 
 let server: PuterServer;
 let fetchSpy: MockInstance<typeof fetch>;
-let hasCreditsSpy: MockInstance<MeteringService['hasEnoughCredits']>;
+let admitSpy: MockInstance<MeteringService['reserveCreditsIfAffordable']>;
 let incrementUsageSpy: MockInstance<MeteringService['incrementUsage']>;
 
 beforeAll(async () => {
@@ -79,7 +79,7 @@ const audioResponse = (body = 'audio-bytes', contentType = 'audio/mpeg') =>
 
 beforeEach(() => {
     fetchSpy = vi.spyOn(globalThis, 'fetch') as MockInstance<typeof fetch>;
-    hasCreditsSpy = vi.spyOn(server.services.metering, 'hasEnoughCredits');
+    admitSpy = vi.spyOn(server.services.metering, 'reserveCreditsIfAffordable');
     incrementUsageSpy = vi.spyOn(server.services.metering, 'incrementUsage');
 });
 
@@ -160,7 +160,7 @@ describe('XAITTSProvider.synthesize test_mode', () => {
             url: 'https://puter-sample-data.puter.site/tts_example.mp3',
             content_type: 'audio',
         });
-        expect(hasCreditsSpy).not.toHaveBeenCalled();
+        expect(admitSpy).not.toHaveBeenCalled();
         expect(fetchSpy).not.toHaveBeenCalled();
     });
 });
@@ -195,7 +195,7 @@ describe('XAITTSProvider.synthesize argument validation', () => {
 describe('XAITTSProvider.synthesize credit gate', () => {
     it('throws 402 BEFORE hitting xAI when actor lacks credits', async () => {
         const provider = makeProvider();
-        hasCreditsSpy.mockResolvedValueOnce(false);
+        admitSpy.mockResolvedValueOnce(null);
 
         await expect(
             withTestActor(() => provider.synthesize({ text: 'hi' })),
@@ -327,7 +327,7 @@ describe('XAITTSProvider.synthesize metering', () => {
         expect(cost).toBe(expectedCost);
     });
 
-    it('asks for hasEnoughCredits with the same total it later meters', async () => {
+    it('reserves the same total it later meters', async () => {
         const provider = makeProvider();
         fetchSpy.mockResolvedValueOnce(audioResponse());
 
@@ -335,7 +335,7 @@ describe('XAITTSProvider.synthesize metering', () => {
         await withTestActor(() => provider.synthesize({ text }));
 
         const expectedCost = XAI_TTS_COSTS['xai-tts'] * text.length;
-        expect(hasCreditsSpy.mock.calls[0]![1]).toBe(expectedCost);
+        expect(admitSpy.mock.calls[0]![1]).toBe(expectedCost);
     });
 });
 

src/backend/drivers/ai-video/VideoGenerationDriver.test.ts

@@ -94,7 +94,7 @@ vi.mock('../../util/secureHttp.js', async (importOriginal) => ({
 
 let server: PuterServer;
 let driver: VideoGenerationDriver;
-let hasCreditsSpy: MockInstance<MeteringService['hasEnoughCredits']>;
+let admitSpy: MockInstance<MeteringService['reserveCreditsIfAffordable']>;
 
 beforeAll(async () => {
     server = await setupTestServer({
@@ -122,8 +122,10 @@ beforeEach(() => {
     togetherVideosCreateMock.mockReset();
     togetherVideosRetrieveMock.mockReset();
     secureFetchMock.mockReset();
-    hasCreditsSpy = vi.spyOn(server.services.metering, 'hasEnoughCredits');
-    hasCreditsSpy.mockResolvedValue(true);
+    admitSpy = vi.spyOn(server.services.metering, 'reserveCreditsIfAffordable');
+    admitSpy.mockImplementation((who, amount, opts) =>
+            server.services.metering.reserveCredits(who, amount, opts),
+        );
     vi.spyOn(server.services.metering, 'getRemainingUsage').mockResolvedValue(
         100_000_000_000,
     );

src/backend/drivers/ai-video/providers/gemini/GeminiVideoProvider.test.ts

@@ -106,7 +106,7 @@ const MP4 = Buffer.concat([
 let server: PuterServer;
 let videoDriver: VideoGenerationDriver;
 let fetchSpy: MockInstance<typeof fetch>;
-let hasCreditsSpy: MockInstance<MeteringService['hasEnoughCredits']>;
+let admitSpy: MockInstance<MeteringService['reserveCreditsIfAffordable']>;
 let batchSpy: MockInstance<MeteringService['batchIncrementUsages']>;
 
 const generate = (args: Record<string, unknown> = {}) =>
@@ -139,9 +139,11 @@ beforeEach(() => {
     secureFetchMock.mockReset();
     secureFetchMock.mockRejectedValue(new Error('unexpected secureFetch'));
     // The full hold is more than a new account's allowance.
-    hasCreditsSpy = vi
-        .spyOn(server.services.metering, 'hasEnoughCredits')
-        .mockResolvedValue(true);
+    admitSpy = vi
+        .spyOn(server.services.metering, 'reserveCreditsIfAffordable')
+        .mockImplementation((who, amount, opts) =>
+            server.services.metering.reserveCredits(who, amount, opts),
+        );
     batchSpy = vi.spyOn(server.services.metering, 'batchIncrementUsages');
 });
 
@@ -589,7 +591,7 @@ describe('GeminiVideoProvider test_mode', () => {
     it('returns the sample clip without network, credits or metering', async () => {
         expect(await testMode()).toBe(SAMPLE_URL);
         expect(fetchSpy).not.toHaveBeenCalled();
-        expect(hasCreditsSpy).not.toHaveBeenCalled();
+        expect(admitSpy).not.toHaveBeenCalled();
         expect(batchSpy).not.toHaveBeenCalled();
     });
 
@@ -1028,7 +1030,7 @@ describe('GeminiVideoProvider source video', () => {
 
         const path = await writeVideo(user, 'dog.mp4', MP4);
         const read = vi.spyOn(server.stores.s3Object, 'getObjectStream');
-        hasCreditsSpy.mockResolvedValue(false);
+        admitSpy.mockResolvedValue(null);
         countOnly();
         await expect(
             withActor(user.actor, () => generate({ input_video: path })),
@@ -1573,12 +1575,12 @@ describe('GeminiVideoProvider countTokens preflight', () => {
 describe('GeminiVideoProvider credit hold', () => {
     it('throws 402 after counting tokens, before generating', async () => {
         const { actor } = await makeUser();
-        hasCreditsSpy.mockResolvedValueOnce(false);
+        admitSpy.mockResolvedValueOnce(null);
         fetchSpy.mockResolvedValueOnce(Response.json({ totalTokens: 18 }));
         await expect(withActor(actor, () => generate())).rejects.toMatchObject({
             statusCode: 402,
         });
-        expect(hasCreditsSpy.mock.calls[0]![1]).toBe(HOLD);
+        expect(admitSpy.mock.calls[0]![1]).toBe(HOLD);
         expect(fetchSpy).toHaveBeenCalledTimes(1);
         expect(batchSpy).not.toHaveBeenCalled();
     });

src/backend/drivers/ai-video/providers/together/TogetherVideoProvider.test.ts

@@ -85,7 +85,7 @@ vi.mock('together-ai', () => {
 // ── Test harness ────────────────────────────────────────────────────
 
 let server: PuterServer;
-let hasCreditsSpy: MockInstance<MeteringService['hasEnoughCredits']>;
+let admitSpy: MockInstance<MeteringService['reserveCreditsIfAffordable']>;
 let remainingUsageSpy: MockInstance<MeteringService['getRemainingUsage']>;
 let incrementUsageSpy: MockInstance<MeteringService['incrementUsage']>;
 
@@ -117,11 +117,13 @@ beforeEach(() => {
     videosCreateMock.mockReset();
     videosRetrieveMock.mockReset();
     togetherCtor.mockReset();
-    hasCreditsSpy = vi.spyOn(server.services.metering, 'hasEnoughCredits');
+    admitSpy = vi.spyOn(server.services.metering, 'reserveCreditsIfAffordable');
     // Default to "has credits" so per-test setup only needs to override
     // for the explicit credit-gate scenarios. SYSTEM_ACTOR has no uuid,
     // so the live `getRemainingUsage` path can short-circuit to 0.
-    hasCreditsSpy.mockResolvedValue(true);
+    admitSpy.mockImplementation((who, amount, opts) =>
+            server.services.metering.reserveCredits(who, amount, opts),
+        );
     remainingUsageSpy = vi.spyOn(server.services.metering, 'getRemainingUsage');
     remainingUsageSpy.mockResolvedValue(AMPLE_CREDIT);
     incrementUsageSpy = vi.spyOn(server.services.metering, 'incrementUsage');
@@ -197,7 +199,7 @@ describe('TogetherVideoProvider.generate test_mode', () => {
             provider.generate({ prompt: 'hi', test_mode: true }),
         );
         expect(result).toBe('https://assets.puter.site/txt2vid.mp4');
-        expect(hasCreditsSpy).not.toHaveBeenCalled();
+        expect(admitSpy).not.toHaveBeenCalled();
         expect(videosCreateMock).not.toHaveBeenCalled();
     });
 });
@@ -238,7 +240,7 @@ const DIRECTOR = 'togetherai:minimax/video-01-director';
 describe('TogetherVideoProvider.generate credit gate', () => {
     it('throws 402 BEFORE hitting Together when actor lacks credits', async () => {
         const provider = makeProvider();
-        hasCreditsSpy.mockResolvedValueOnce(false);
+        admitSpy.mockResolvedValueOnce(null);
 
         await expect(
             withTestActor(() =>
@@ -715,7 +717,7 @@ describe('TogetherVideoProvider.generate per-second models', () => {
         expect('height' in sent).toBe(false);
         expect('ratio' in sent).toBe(false);
         // The flat-rate gate is not consulted for per-second models.
-        expect(hasCreditsSpy).not.toHaveBeenCalled();
+        expect(admitSpy).not.toHaveBeenCalled();
 
         const seedance = TOGETHER_VIDEO_GENERATION_MODELS.find(
             (m) => m.model === 'ByteDance/Seedance-2.5',

src/backend/drivers/util/aiCostFactor.test.ts

@@ -324,8 +324,10 @@ describe('AI cost factor', () => {
         it('gates and holds at the factored cost', async () => {
             listen(1.3);
             const check = vi
-                .spyOn(metering, 'hasEnoughCredits')
-                .mockResolvedValue(true);
+                .spyOn(metering, 'reserveCreditsIfAffordable')
+                .mockImplementation((who, amount, opts) =>
+                    metering.reserveCredits(who, amount, opts),
+                );
             const reserve = vi.spyOn(metering, 'reserveCredits');
             try {
                 const hold = await scoped.reserveAiCredits(
@@ -334,7 +336,11 @@ describe('AI cost factor', () => {
                     1000,
                 );
                 await hold?.release();
-                expect(check).toHaveBeenCalledWith(actor, 1300);
+                expect(check).toHaveBeenCalledExactlyOnceWith(
+                    actor,
+                    1300,
+                    undefined,
+                );
                 expect(reserve).toHaveBeenCalledWith(actor, 1300, undefined);
             } finally {
                 check.mockRestore();
@@ -342,10 +348,40 @@ describe('AI cost factor', () => {
             }
         });
 
+        it('admits one of two concurrent holds the balance only covers once', async () => {
+            listen(1.3);
+            vi.spyOn(metering, 'getAllowedUsage').mockResolvedValue({
+                remaining: 20_000_000,
+                monthUsageAllowance: 20_000_000,
+                addons: {},
+            });
+            const holds = await Promise.all(
+                [0, 1].map(() =>
+                    scoped.reserveAiCredits(
+                        actor,
+                        'openai:gpt-realtime:realtime:audio_output',
+                        12_500_000,
+                    ),
+                ),
+            );
+            try {
+                expect(holds.filter((h) => h !== null)).toHaveLength(1);
+                // The factor applies once: 12.5M at 1.3 is 16.25M held.
+                expect(await metering.getOutstandingHolds(actor)).toBe(
+                    16_250_000,
+                );
+            } finally {
+                await Promise.all(holds.map((h) => h?.release()));
+                vi.restoreAllMocks();
+            }
+        });
+
         it('passes a hold lifetime through to the service', async () => {
             const check = vi
-                .spyOn(metering, 'hasEnoughCredits')
-                .mockResolvedValue(true);
+                .spyOn(metering, 'reserveCreditsIfAffordable')
+                .mockImplementation((who, amount, opts) =>
+                    metering.reserveCredits(who, amount, opts),
+                );
             const reserve = vi.spyOn(metering, 'reserveCredits');
             try {
                 const hold = await scoped.reserveAiCredits(
@@ -367,8 +403,12 @@ describe('AI cost factor', () => {
         it('takes no hold when the factored cost is unaffordable', async () => {
             listen(1.3);
             const check = vi
-                .spyOn(metering, 'hasEnoughCredits')
-                .mockImplementation(async (_actor, amount) => amount <= 1000);
+                .spyOn(metering, 'reserveCreditsIfAffordable')
+                .mockImplementation(async (who, amount, opts) =>
+                    amount <= 1000
+                        ? metering.reserveCredits(who, amount, opts)
+                        : null,
+                );
             const reserve = vi.spyOn(metering, 'reserveCredits');
             try {
                 const hold = await scoped.reserveAiCredits(
@@ -409,8 +449,10 @@ describe('AI cost factor', () => {
         it('holds the factored cost while run executes, then releases it', async () => {
             listen(1.3);
             const check = vi
-                .spyOn(metering, 'hasEnoughCredits')
-                .mockResolvedValue(true);
+                .spyOn(metering, 'reserveCreditsIfAffordable')
+                .mockImplementation((who, amount, opts) =>
+                    metering.reserveCredits(who, amount, opts),
+                );
             try {
                 let heldDuringRun = 0;
                 const result = await withAiCreditHold(
@@ -448,8 +490,10 @@ describe('AI cost factor', () => {
             };
             server.clients.event.on('ai.cost.factor.*', slowFactor as never);
             const check = vi
-                .spyOn(metering, 'hasEnoughCredits')
-                .mockResolvedValue(true);
+                .spyOn(metering, 'reserveCreditsIfAffordable')
+                .mockImplementation((who, amount, opts) =>
+                    metering.reserveCredits(who, amount, opts),
+                );
             try {
                 await runWithContext({ actor }, () =>
                     withAiCreditHold(
@@ -485,8 +529,10 @@ describe('AI cost factor', () => {
 
         it('releases the hold when the usage write fails', async () => {
             const check = vi
-                .spyOn(metering, 'hasEnoughCredits')
-                .mockResolvedValue(true);
+                .spyOn(metering, 'reserveCreditsIfAffordable')
+                .mockImplementation((who, amount, opts) =>
+                    metering.reserveCredits(who, amount, opts),
+                );
             const write = vi
                 .spyOn(metering, 'incrementUsage')
                 .mockRejectedValueOnce(new Error('ledger down'));
@@ -515,8 +561,10 @@ describe('AI cost factor', () => {
 
         it('releases at once when nothing was recorded', async () => {
             const check = vi
-                .spyOn(metering, 'hasEnoughCredits')
-                .mockResolvedValue(true);
+                .spyOn(metering, 'reserveCreditsIfAffordable')
+                .mockImplementation((who, amount, opts) =>
+                    metering.reserveCredits(who, amount, opts),
+                );
             try {
                 await runWithContext({ actor }, () =>
                     withAiCreditHold(
@@ -535,8 +583,10 @@ describe('AI cost factor', () => {
 
         it('releases the hold when run throws', async () => {
             const check = vi
-                .spyOn(metering, 'hasEnoughCredits')
-                .mockResolvedValue(true);
+                .spyOn(metering, 'reserveCreditsIfAffordable')
+                .mockImplementation((who, amount, opts) =>
+                    metering.reserveCredits(who, amount, opts),
+                );
             const boom = new Error('upstream down');
             try {
                 await expect(
@@ -552,8 +602,8 @@ describe('AI cost factor', () => {
 
         it('refuses with a 402 and never runs when the cost is unaffordable', async () => {
             const check = vi
-                .spyOn(metering, 'hasEnoughCredits')
-                .mockResolvedValue(false);
+                .spyOn(metering, 'reserveCreditsIfAffordable')
+                .mockResolvedValue(null);
             const run = vi.fn();
             try {
                 await expect(
@@ -575,8 +625,10 @@ describe('AI cost factor', () => {
         const relay = async (source: Readable) => {
             const record = vi.fn();
             const check = vi
-                .spyOn(metering, 'hasEnoughCredits')
-                .mockResolvedValue(true);
+                .spyOn(metering, 'reserveCreditsIfAffordable')
+                .mockImplementation((who, amount, opts) =>
+                    metering.reserveCredits(who, amount, opts),
+                );
             try {
                 const result = await withStreamedAiCharge(
                     scoped,
@@ -624,8 +676,10 @@ describe('AI cost factor', () => {
                 landCharge = resolve;
             });
             const check = vi
-                .spyOn(metering, 'hasEnoughCredits')
-                .mockResolvedValue(true);
+                .spyOn(metering, 'reserveCreditsIfAffordable')
+                .mockImplementation((who, amount, opts) =>
+                    metering.reserveCredits(who, amount, opts),
+                );
             try {
                 const result = await withStreamedAiCharge(
                     scoped,
@@ -655,8 +709,10 @@ describe('AI cost factor', () => {
             vi.useFakeTimers({ toFake: ['setInterval', 'clearInterval'] });
             const refresh = vi.spyOn(server.stores.creditHold, 'refresh');
             const check = vi
-                .spyOn(metering, 'hasEnoughCredits')
-                .mockResolvedValue(true);
+                .spyOn(metering, 'reserveCreditsIfAffordable')
+                .mockImplementation((who, amount, opts) =>
+                    metering.reserveCredits(who, amount, opts),
+                );
             let landCharge = () => {};
             const charge = new Promise<void>((resolve) => {
                 landCharge = resolve;
@@ -697,8 +753,10 @@ describe('AI cost factor', () => {
             vi.useFakeTimers({ toFake: ['setInterval', 'clearInterval'] });
             const refresh = vi.spyOn(server.stores.creditHold, 'refresh');
             const check = vi
-                .spyOn(metering, 'hasEnoughCredits')
-                .mockResolvedValue(true);
+                .spyOn(metering, 'reserveCreditsIfAffordable')
+                .mockImplementation((who, amount, opts) =>
+                    metering.reserveCredits(who, amount, opts),
+                );
             let opened = () => {};
             const opening = new Promise<void>((resolve) => {
                 opened = resolve;
@@ -741,8 +799,10 @@ describe('AI cost factor', () => {
 
         it('releases the hold when recording the charge throws', async () => {
             const check = vi
-                .spyOn(metering, 'hasEnoughCredits')
-                .mockResolvedValue(true);
+                .spyOn(metering, 'reserveCreditsIfAffordable')
+                .mockImplementation((who, amount, opts) =>
+                    metering.reserveCredits(who, amount, opts),
+                );
             try {
                 const result = await withStreamedAiCharge(
                     scoped,

src/backend/drivers/util/aiCostFactor.ts

@@ -354,10 +354,12 @@ export function withAiCostFactor(
             ? await costFactor(actor, aiModelKey(usageType))
             : 1;
         const cost = factor === 1 ? amount : scaleCost(amount, factor);
-        if (!(await metering.hasEnoughCredits(actor, cost))) return null;
-        return outlastingWrites(
-            await metering.reserveCredits(actor, cost, opts),
+        const hold = await metering.reserveCreditsIfAffordable(
+            actor,
+            cost,
+            opts,
         );
+        return hold && outlastingWrites(hold);
     };
 
     const reserveCredits = async (

src/backend/services/metering/MeteringService.test.ts

@@ -4290,6 +4290,295 @@ describe('MeteringService', () => {
         });
     });
 
+    describe('reserveCreditsIfAffordable', () => {
+        const BUDGET = 20_000_000;
+        const HOLD = 16_200_000;
+
+        afterEach(() => {
+            vi.restoreAllMocks();
+        });
+
+        /** Spends the fresh actor's allowance down to exactly `balance`. */
+        const withBalance = async (balance: number) => {
+            const { remaining } = await target.getAllowedUsage(actor);
+            if (remaining > balance) {
+                await target.incrementUsage(
+                    actor,
+                    'kv:read',
+                    1,
+                    remaining - balance,
+                );
+            }
+            expect((await target.getAllowedUsage(actor)).remaining).toBe(
+                balance,
+            );
+        };
+
+        it('admits exactly one of two concurrent holds that only fit alone', async () => {
+            await withBalance(BUDGET);
+            const holds = await Promise.all([
+                target.reserveCreditsIfAffordable(actor, HOLD),
+                target.reserveCreditsIfAffordable(actor, HOLD),
+            ]);
+
+            expect(holds.filter((h) => h !== null)).toHaveLength(1);
+            expect(await target.getOutstandingHolds(actor)).toBe(HOLD);
+            await Promise.all(holds.map((h) => h?.release()));
+        });
+
+        it('compares against the gross balance, counting live holds once', async () => {
+            await withBalance(BUDGET);
+            const other = await target.reserveCredits(actor, 5_000_000);
+
+            expect(
+                await target.reserveCreditsIfAffordable(actor, 15_000_001),
+            ).toBeNull();
+            const fits = await target.reserveCreditsIfAffordable(
+                actor,
+                15_000_000,
+            );
+            expect(fits).not.toBeNull();
+            expect(await target.getOutstandingHolds(actor)).toBe(BUDGET);
+
+            // A release gives the headroom back for a retry.
+            await other.release();
+            expect(
+                await target.reserveCreditsIfAffordable(actor, 5_000_000),
+            ).not.toBeNull();
+        });
+
+        it('counts allowance and purchased credit together', async () => {
+            await withBalance(1_000_000);
+            await target.updateAddonCredit(actor.user.uuid!, 2_000_000);
+
+            expect(
+                await target.reserveCreditsIfAffordable(actor, 3_000_001),
+            ).toBeNull();
+            expect(
+                await target.reserveCreditsIfAffordable(actor, 3_000_000),
+            ).not.toBeNull();
+        });
+
+        it('reads the balance again when usage lands and a hold is released after the read', async () => {
+            await withBalance(BUDGET);
+            // A request still running, about to record its usage and release.
+            const running = await target.reserveCredits(actor, HOLD);
+            const settle = async () => {
+                await target.incrementUsage(actor, 'kv:read', 1, HOLD);
+                await running.release();
+            };
+            // The admission's balance read finishes first, then the
+            // settlement lands before its reservation runs.
+            const read = target.getAllowedUsage.bind(target);
+            let settled = false;
+            vi.spyOn(target, 'getAllowedUsage').mockImplementation(
+                async (...args) => {
+                    const balance = await read(...args);
+                    if (!settled) {
+                        settled = true;
+                        await settle();
+                    }
+                    return balance;
+                },
+            );
+
+            expect(await target.reserveCreditsIfAffordable(actor, HOLD)).toBe(
+                null,
+            );
+            expect(await target.getOutstandingHolds(actor)).toBe(0);
+        });
+
+        it('would over-admit that interleaving without the version check', async () => {
+            await withBalance(BUDGET);
+            const running = await target.reserveCredits(actor, HOLD);
+            const read = target.getAllowedUsage.bind(target);
+            let settled = false;
+            vi.spyOn(target, 'getAllowedUsage').mockImplementation(
+                async (...args) => {
+                    const balance = await read(...args);
+                    if (!settled) {
+                        settled = true;
+                        await target.incrementUsage(actor, 'kv:read', 1, HOLD);
+                        await running.release();
+                    }
+                    return balance;
+                },
+            );
+            vi.spyOn(server.stores.creditHold, 'version').mockResolvedValue('');
+
+            const hold = await target.reserveCreditsIfAffordable(actor, HOLD);
+            expect(hold).not.toBeNull();
+            await hold?.release();
+        });
+
+        it('marks the balance changed once a usage write lands', async () => {
+            const before = await server.stores.creditHold.version(
+                actor.user.uuid!,
+            );
+            await target.incrementUsage(actor, 'kv:read', 1, 1_000);
+            expect(
+                await server.stores.creditHold.version(actor.user.uuid!),
+            ).not.toBe(before);
+        });
+
+        it('lets the balance decide, holding nothing, when the cache is unavailable', async () => {
+            await withBalance(BUDGET);
+            vi.spyOn(server.stores.creditHold, 'reserve').mockResolvedValue({
+                outcome: 'unavailable',
+            });
+
+            const hold = await target.reserveCreditsIfAffordable(actor, HOLD);
+            expect(hold).not.toBeNull();
+            expect(await target.getOutstandingHolds(actor)).toBe(0);
+            expect(
+                await target.reserveCreditsIfAffordable(actor, BUDGET + 1),
+            ).toBeNull();
+        });
+
+        it('reads the balance again while it keeps changing, then refuses', async () => {
+            await withBalance(BUDGET);
+            const reserve = vi
+                .spyOn(server.stores.creditHold, 'reserve')
+                .mockResolvedValue({ outcome: 'stale' });
+
+            expect(await target.reserveCreditsIfAffordable(actor, HOLD)).toBe(
+                null,
+            );
+            expect(reserve).toHaveBeenCalledTimes(5);
+            // Every attempt checks the version; none falls back to skipping it.
+            expect(reserve.mock.calls.every(([, , , v]) => v !== '')).toBe(
+                true,
+            );
+            expect(await target.getOutstandingHolds(actor)).toBe(0);
+        });
+
+        it('admits once the balance holds still', async () => {
+            await withBalance(BUDGET);
+            const reserve = vi.spyOn(server.stores.creditHold, 'reserve');
+            reserve
+                .mockResolvedValueOnce({ outcome: 'stale' })
+                .mockResolvedValueOnce({ outcome: 'stale' });
+
+            const hold = await target.reserveCreditsIfAffordable(actor, HOLD);
+            expect(hold).not.toBeNull();
+            expect(reserve).toHaveBeenCalledTimes(3);
+            await hold?.release();
+        });
+
+        it('reads purchased credit consistently only while some is left', async () => {
+            await withBalance(BUDGET);
+            const get = vi.spyOn(server.stores.kv, 'get');
+            const consistentAddonReads = () =>
+                get.mock.calls.filter(
+                    ([args]) =>
+                        args.consistentRead &&
+                        String(args.key).endsWith(':addons'),
+                ).length;
+            // With none, the cached record that says so answers.
+            await target.getAllowedUsage(actor);
+            get.mockClear();
+            await (
+                await target.reserveCreditsIfAffordable(actor, 1000)
+            )?.release();
+            expect(consistentAddonReads()).toBe(0);
+
+            await target.updateAddonCredit(actor.user.uuid!, 5_000);
+            get.mockClear();
+            await (
+                await target.reserveCreditsIfAffordable(actor, 1000)
+            )?.release();
+            expect(consistentAddonReads()).toBe(1);
+        });
+
+        it('marks the balance changed on credit, allowance and manual usage changes', async () => {
+            const uuid = actor.user.uuid!;
+            const versions = [await server.stores.creditHold.version(uuid)];
+            await target.updateAddonCredit(uuid, 1_000);
+            versions.push(await server.stores.creditHold.version(uuid));
+            await target.setActorCurrentMonthUsageTotal(actor, 5_000);
+            versions.push(await server.stores.creditHold.version(uuid));
+            expect(new Set(versions).size).toBe(3);
+        });
+
+        it('treats the system actor, a userless actor and amounts it can’t hold as the plain check does', async () => {
+            for (const [who, amount] of [
+                [SYSTEM_ACTOR, HOLD],
+                [actor, 0],
+                [actor, -5],
+            ] as const) {
+                const hold = await target.reserveCreditsIfAffordable(
+                    who,
+                    amount,
+                );
+                expect(hold).not.toBeNull();
+            }
+            for (const amount of [Number.NaN, Number.POSITIVE_INFINITY]) {
+                expect(
+                    await target.reserveCreditsIfAffordable(actor, amount),
+                ).toBeNull();
+            }
+            await expect(
+                target.reserveCreditsIfAffordable({ user: {} } as Actor, HOLD),
+            ).rejects.toThrow();
+            expect(await target.getOutstandingHolds(actor)).toBe(0);
+        });
+
+        it('passes the hold lifetime through and renews it', async () => {
+            await withBalance(BUDGET);
+            const hold = await target.reserveCreditsIfAffordable(actor, 750, {
+                ttlMs: 500,
+            });
+            await new Promise((r) => setTimeout(r, 620));
+            expect(await target.getOutstandingHolds(actor)).toBe(0);
+            await hold?.extend?.();
+            expect(await target.getOutstandingHolds(actor)).toBe(750);
+            await hold?.release();
+            expect(await target.getOutstandingHolds(actor)).toBe(0);
+        });
+    });
+
+    describe('settling a charge while a flush is out', () => {
+        it('splits a charge over the allowance using usage a flush has claimed', async () => {
+            const uuid = actor.user.uuid!;
+            const { monthUsageAllowance: allowance } =
+                await target.getActorSubscription(actor);
+            await target.updateAddonCredit(uuid, 1_000_000);
+            const Service = target.constructor as typeof MeteringService;
+            const threshold = Service.PRECISION_THRESHOLD;
+            // Keeps the first charge buffered instead of read exactly.
+            Service.PRECISION_THRESHOLD = 2;
+            await target.incrementUsage(actor, 'kv:read', 1, allowance - 5);
+            Service.PRECISION_THRESHOLD = threshold;
+
+            // A flush claims it and stalls before writing it onward.
+            const kv = server.stores.kv;
+            const realIncr = kv.incr.bind(kv);
+            let release: () => void = () => {};
+            const gate = new Promise<void>((r) => (release = r));
+            const write = vi
+                .spyOn(kv, 'incr')
+                .mockImplementation(async (...args) => {
+                    await gate;
+                    return realIncr(...args);
+                });
+            const flushing = server.stores.meteringBuffer.flushCycle();
+            await vi.waitFor(() => expect(write).toHaveBeenCalled());
+            write.mockImplementation(realIncr);
+
+            // 5 µ¢ of this is left in the allowance; the rest is credit.
+            await target.incrementUsage(actor, 'kv:read', 1, 10);
+            release();
+            await flushing;
+            write.mockRestore();
+            await waitFor(async () => {
+                const addons = await target.getActorAddons(actor, {
+                    consistentRead: true,
+                });
+                expect(addons.consumedPurchaseCredits).toBe(5);
+            });
+        });
+    });
+
     // ── Resolver registration ────────────────────────────────────────
 
     describe('resolver registration', () => {

src/backend/services/metering/MeteringService.ts

@@ -698,6 +698,8 @@ export class MeteringService extends PuterService {
                 actorAddons,
                 totalBatchCost,
             );
+            // Before any hold this usage stands for is released.
+            await this.stores.creditHold.bump(userId);
 
             this.maybeAlertOveruse({
                 actor,
@@ -729,6 +731,10 @@ export class MeteringService extends PuterService {
                 ? ({ ...own, ...charged } as UsageByType)
                 : (charged ?? own);
         } catch (e) {
+            // Part of the usage may have landed before the failure.
+            if (actor?.user?.uuid) {
+                await this.stores.creditHold.bump(actor.user.uuid);
+            }
             console.error('[metering] batchIncrementUsages failed', {
                 actor,
                 usages,
@@ -1432,6 +1438,7 @@ export class MeteringService extends PuterService {
         }
 
         this.invalidateActorCredits(userId);
+        await this.stores.creditHold.bump(userId);
         await Promise.all([
             this.stores.meteringBuffer.forgetSummed(actorUsageKey),
             this.stores.meteringBuffer.forgetSummed(
@@ -1545,7 +1552,86 @@ export class MeteringService extends PuterService {
             opts.ttlMs,
         );
         if (!member) return NO_CREDIT_HOLD;
+        return this.#holdHandle(userId, member, opts.ttlMs);
+    }
 
+    /**
+     * Commit part of an actor's budget only if it fits beside what their other
+     * operations hold; null when it doesn't. The check and the hold are one
+     * step in the cache, and a usage write or release that lands after the
+     * balance read sends the reservation back to read it again. When the cache
+     * can't answer, the balance alone decides and nothing is held.
+     */
+    async reserveCreditsIfAffordable(
+        actor: Actor,
+        amount: number,
+        opts: { ttlMs?: number } = {},
+    ): Promise<CreditHold | null> {
+        const userId = actor?.user?.uuid;
+        if (
+            !userId ||
+            isSystemActor(actor) ||
+            !Number.isFinite(amount) ||
+            !(amount > 0)
+        ) {
+            // Nothing to hold; the plain check decides, as it always has.
+            return (await this.hasEnoughCredits(actor, amount))
+                ? NO_CREDIT_HOLD
+                : null;
+        }
+
+        for (let attempt = 1; ; attempt++) {
+            const version = await this.stores.creditHold.version(userId);
+            // Read after the version, so a write it misses bumps the version.
+            const { remaining } = await this.getAllowedUsage(actor, {
+                exact: true,
+            });
+            const budget = remaining || 0;
+            const result =
+                version === null
+                    ? ({ outcome: 'unavailable' } as const)
+                    : await this.stores.creditHold.reserve(
+                          userId,
+                          amount,
+                          budget,
+                          version,
+                          opts.ttlMs,
+                      );
+            switch (result.outcome) {
+                case 'accepted':
+                    return this.#holdHandle(userId, result.member, opts.ttlMs);
+                case 'insufficient':
+                    return null;
+                case 'unavailable':
+                    return budget >= amount ? NO_CREDIT_HOLD : null;
+                case 'stale':
+                    break;
+            }
+            // A balance that never holds still long enough to read is refused
+            // rather than checked against a read that may be out of date.
+            if (attempt >= MeteringService.RESERVE_ATTEMPTS) {
+                console.warn(
+                    `[metering] credit reservation refused for ${userId}: balance kept changing`,
+                );
+                return null;
+            }
+            await new Promise((resolve) =>
+                setTimeout(
+                    resolve,
+                    Math.random() *
+                        MeteringService.RESERVE_BACKOFF_MS *
+                        attempt,
+                ),
+            );
+        }
+    }
+
+    /** Reservations tried while the balance keeps changing under them. */
+    private static readonly RESERVE_ATTEMPTS = 5;
+    /** Upper bound of the randomized wait before each retry, times the attempt. */
+    private static readonly RESERVE_BACKOFF_MS = 20;
+
+    #holdHandle(userId: string, member: string, ttlMs?: number): CreditHold {
         let released = false;
         return {
             release: async () => {
@@ -1555,11 +1641,7 @@ export class MeteringService extends PuterService {
             },
             extend: async () => {
                 if (released) return;
-                await this.stores.creditHold.refresh(
-                    userId,
-                    member,
-                    opts.ttlMs,
-                );
+                await this.stores.creditHold.refresh(userId, member, ttlMs);
             },
         };
     }
@@ -1571,14 +1653,22 @@ export class MeteringService extends PuterService {
         return this.stores.creditHold.outstanding(userId);
     }
 
-    async getAllowedUsage(actor: Actor): Promise<{
+    /**
+     * `exact` reads purchased credit consistently, for a spend decision that
+     * has to see the consumption a write just recorded. A cached record with no
+     * credit left still answers: it can only understate the balance.
+     */
+    async getAllowedUsage(
+        actor: Actor,
+        { exact = false }: { exact?: boolean } = {},
+    ): Promise<{
         remaining: number;
         monthUsageAllowance: number;
         addons: UsageAddons;
     }> {
         const [userSubscription, addons, totals] = await Promise.all([
             this.getActorSubscription(actor),
-            this.#addonsForSettle(actor),
+            this.#addonsForSettle(actor, { consistentRead: exact }),
             this.currentMonthTotals(actor),
         ]);
 
@@ -2245,13 +2335,16 @@ export class MeteringService extends PuterService {
     }
 
     /** `getActorAddons`, through `#spentAddons`. Shared by gates and settles. */
-    async #addonsForSettle(actor: Actor): Promise<UsageAddons> {
+    async #addonsForSettle(
+        actor: Actor,
+        { consistentRead }: { consistentRead?: boolean } = {},
+    ): Promise<UsageAddons> {
         const uuid = actor.user?.uuid;
         const cached = uuid ? this.#spentAddons.get(uuid) : undefined;
         if (cached && cached.expiresAt > Date.now()) return cached.addons;
 
         const drops = this.#spentAddonsDrops;
-        const addons = await this.getActorAddons(actor);
+        const addons = await this.getActorAddons(actor, { consistentRead });
         if (!uuid) return addons;
         this.#spentAddons.delete(uuid);
         const creditLeft =
@@ -2382,6 +2475,7 @@ export class MeteringService extends PuterService {
         // Credit that lands while the account is being turned away has to take
         // effect on the next request, not at the end of the cache window.
         this.invalidateActorCredits(userId);
+        await this.stores.creditHold.bump(userId);
     }
 
     /**
@@ -2429,6 +2523,7 @@ export class MeteringService extends PuterService {
         });
         // Every node drops its cached policy, and the budget answer with it.
         this.invalidateActorSubscription(userUuid);
+        await this.stores.creditHold.bump(userUuid);
     }
 
     /**

src/backend/services/realtime/README.md

@@ -11,7 +11,10 @@ Direct clients are documented in the [Realtime WebSocket API reference](../../..
 
 The relay forwards native OpenAI JSON events unchanged after validating the
 event envelope, except that `rate_limits.updated` (Puter's provider account) is
-dropped and provider organization IDs are removed from error messages. An event must be an object with a nonempty string `type` of at
+dropped and provider organization IDs are removed from diagnostic messages in
+`error`, `response.done.status_details.error`, and
+`conversation.item.input_audio_transcription.failed.error`, and from provider
+close reasons. Conversation content is preserved. An event must be an object with a nonempty string `type` of at
 most 128 characters. Binary messages and malformed envelopes close the session.
 Usage fields consumed by metering are validated before use. Event field order
 does not affect billing.
@@ -46,7 +49,8 @@ traffic is not rate limited: OpenAI sends audio faster than real time, and
 backpressure bounds what a slow client can queue. Usage is priced as each event
 arrives, before any forwarding decision, and recorded serially off the
 forwarding path through the AI cost-factor hook. Pricing follows the model the
-session reports, falling back to the connection's; a client `session.update`
+session reports. A missing model uses the last known model, while an explicitly
+unpriced model closes the connection; a client `session.update`
 that changes the model is refused. So are `conversation.item.retrieve` and MCP
 tools in `session.update` or `response.create`, since a retrieved item or MCP
 output can exceed the upstream message cap.
@@ -65,9 +69,53 @@ Each response holds a fixed amount of the account's budget
 until its usage is recorded, so concurrent sessions can't overdraw it; a session
 opens only if one hold fits. Input transcription is priced at the costlier of
 the transcription models in force at commit and at completion. Session attempts
-are limited per credential before authentication runs.
+are limited per credential after signature verification. Local, bounded IP and
+node admission limits protect signature verification and authentication lookups.
+Upgrades use Express's configured proxy trust policy and the `ip.validate` gate.
+Authentication uses `touch: false` on both initial connection and rechecks, so
+opening or maintaining a realtime socket does not update session activity metadata.
+
+Input transcription holds credit per item, at a fixed budget for the selected
+transcription model and that model's cost factor. Audio and the configuration
+that enables transcription are forwarded only while a reserved spare item
+exists. Each provider commit takes one, and the pool refills to two spares in
+the background, up to 64 pending plus spare items. A commit with no spare left
+reserves its own item. A model change, requested or reported, releases the spares
+and reserves new ones at the new model's price. Committed items keep their hold
+and model. Disabling transcription keeps the spares until the connection ends.
+If the account can't cover another item, client reads pause while the session
+still holds items that may free credit, and the session is refused with
+`insufficient_funds` once it holds none.
+
+Audio the provider may commit without the relay seeing the acknowledgement is
+tracked apart from the pool, as a duration at the session's input format. Without
+turn detection that is all audio since the last acknowledged commit or clear.
+With server turn detection it is only speech from `speech_started`, since the
+provider drops silence, plus the buffer after an explicit commit. Each started
+160 seconds of it claims one held item, and an acknowledged commit, a clear, or
+an `input_audio_buffer_commit_empty` error returns those items to the spares.
+The session is never closed for its length. If the upstream closes first, each
+claimed item is billed. Each committed item retains its model
+until completion, failure, or bounded settlement. Missing usage is billed the
+item's fixed budget. Overflow closes the connection without evicting existing
+pending identities.
+
+The post-record continuation check asks whether settled credit remains. It
+excludes outstanding holds and accepts fractional positive credit. Admission of
+new billable work continues to use the atomic hold path, which includes every
+outstanding reservation.
+
+Text, transcripts and raw audio are forwarded without new content logging.
+The relay does not invoke `ai.prompt.validate`. A realtime adapter needs the host
+listeners' chat payload and denial contracts before that hook can safely apply
+to instructions and conversation text. Raw audio and generated transcripts need
+separate policy decisions.
 
 Credential checks run in batches of at most 16 with no overlapping sweeps.
+Session and access-token revocation events close affected sockets and invalidate
+their auth cache entries. Subscription eligibility is checked independently of
+authentication and after subscription invalidations. A failed verification check after a 60-second
+retry grace from the first failed lookup closes with a retryable internal error. Periodic checks remain the missed-event fallback.
 When the drain starts, open sessions get a `puter.reconnect` event and new
 sessions receive `server_restarting` and close with 1012. Open sessions can
 finish an in-flight response for up to five seconds at shutdown, then close

src/backend/stores/metering/CreditHoldStore.test.ts

@@ -21,6 +21,7 @@ import { afterAll, beforeAll, describe, expect, it, vi } from 'vitest';
 
 import { PuterServer } from '../../server.js';
 import { setupTestServer } from '../../testUtil.js';
+import type { IConfig, IRedisConfig } from '../../types.js';
 import type { CreditHoldStore } from './CreditHoldStore.js';
 
 let server: PuterServer;
@@ -142,3 +143,204 @@ describe('CreditHoldStore', () => {
         spy.mockRestore();
     });
 });
+
+// Opt in to a real Redis Cluster with PUTER_TEST_REDIS_CLUSTER=host:port.
+const clusterNode = process.env.PUTER_TEST_REDIS_CLUSTER;
+const backends: { name: string; redis: IRedisConfig }[] = [
+    { name: 'the redis mock', redis: { useMock: true } },
+    ...(clusterNode
+        ? [
+              {
+                  name: `redis cluster ${clusterNode}`,
+                  redis: {
+                      useMock: false,
+                      tls: false,
+                      startupNodes: [
+                          {
+                              host: clusterNode.split(':')[0],
+                              port: Number(clusterNode.split(':')[1]),
+                          },
+                      ],
+                  },
+              },
+          ]
+        : []),
+];
+
+describe.each(backends)('CreditHoldStore.reserve on $name', ({ redis }) => {
+    // Two backends sharing one cache, as separate instances do in production.
+    let servers: PuterServer[];
+    let a: CreditHoldStore;
+    let b: CreditHoldStore;
+    const BUDGET = 20_000_000;
+    const HOLD = 16_200_000;
+
+    beforeAll(async () => {
+        servers = await Promise.all(
+            [0, 1].map(() => setupTestServer({ redis } as IConfig)),
+        );
+        [a, b] = servers.map((s) => s.stores.creditHold as CreditHoldStore);
+    });
+
+    afterAll(async () => {
+        await Promise.all((servers ?? []).map((s) => s.shutdown()));
+    });
+
+    const reserve = async (
+        on: CreditHoldStore,
+        id: string,
+        amount: number,
+        budget = BUDGET,
+        ttlMs?: number,
+    ) => on.reserve(id, amount, budget, (await on.version(id))!, ttlMs);
+
+    it('admits exactly one of two concurrent holds that only fit alone', async () => {
+        const id = user();
+        const results = await Promise.all([
+            reserve(a, id, HOLD),
+            reserve(b, id, HOLD),
+        ]);
+
+        expect(results.map((r) => r.outcome).sort()).toEqual([
+            'accepted',
+            'insufficient',
+        ]);
+        expect(await a.outstanding(id)).toBe(HOLD);
+        expect(await b.outstanding(id)).toBe(HOLD);
+    });
+
+    it('admits exact headroom and refuses one unit more', async () => {
+        const id = user();
+        expect((await reserve(a, id, 15_000_000)).outcome).toBe('accepted');
+        expect((await reserve(b, id, 5_000_001)).outcome).toBe('insufficient');
+        expect((await reserve(b, id, 5_000_000)).outcome).toBe('accepted');
+        expect(await a.outstanding(id)).toBe(BUDGET);
+    });
+
+    it('rounds a fractional amount up once', async () => {
+        const id = user();
+        expect((await reserve(a, id, 9.2, 10)).outcome).toBe('accepted');
+        expect(await a.outstanding(id)).toBe(10);
+        expect((await reserve(a, id, 0.5, 10)).outcome).toBe('insufficient');
+    });
+
+    it('admits several holds that fit together, and keeps actors apart', async () => {
+        const [id, other] = [user(), user()];
+        const results = await Promise.all(
+            [a, b, a, b].map((s) => reserve(s, id, 5_000_000)),
+        );
+        expect(results.every((r) => r.outcome === 'accepted')).toBe(true);
+        expect((await reserve(a, other, HOLD)).outcome).toBe('accepted');
+        expect(await a.outstanding(id)).toBe(BUDGET);
+        expect(await a.outstanding(other)).toBe(HOLD);
+    });
+
+    it('leaves nothing behind when it refuses', async () => {
+        const id = user();
+        await reserve(a, id, HOLD);
+        await reserve(b, id, HOLD);
+        await reserve(b, id, HOLD, 0);
+        expect(await a.outstanding(id)).toBe(HOLD);
+    });
+
+    it('frees headroom on release and on expiry', async () => {
+        const id = user();
+        const first = await reserve(a, id, HOLD);
+        expect((await reserve(b, id, HOLD)).outcome).toBe('insufficient');
+        await a.release(id, first.outcome === 'accepted' ? first.member : null);
+        expect((await reserve(b, id, HOLD, BUDGET, 50)).outcome).toBe(
+            'accepted',
+        );
+        await vi.waitFor(
+            async () =>
+                expect((await reserve(a, id, HOLD)).outcome).toBe('accepted'),
+            { timeout: 2000, interval: 25 },
+        );
+    });
+
+    it('keeps a long hold when a short one is reserved beside it', async () => {
+        const id = user();
+        await reserve(a, id, 1000);
+        await reserve(b, id, 500, BUDGET, 50);
+        const pttl = await (
+            servers[0].clients.redis as unknown as {
+                pttl: (key: string) => Promise<number>;
+            }
+        ).pttl(`meter:holds:{${id}}`);
+        expect(pttl).toBeGreaterThan(500_000);
+    });
+
+    it('refuses a budget read before a usage write landed, but not one before a release', async () => {
+        const id = user();
+        // A release alone leaves the balance as it was.
+        const before = (await a.version(id))!;
+        const held = await reserve(a, id, 1000);
+        await b.release(id, held.outcome === 'accepted' ? held.member : null);
+        const after = await a.reserve(id, 1000, BUDGET, before);
+        expect(after.outcome).toBe('accepted');
+        await a.release(id, after.outcome === 'accepted' ? after.member : null);
+
+        const read = (await a.version(id))!;
+        await b.bump(id);
+        expect((await a.reserve(id, 1000, BUDGET, read)).outcome).toBe('stale');
+        expect(await a.outstanding(id)).toBe(0);
+
+        // Skipping the check still can't overlap another hold.
+        await reserve(a, id, HOLD);
+        expect((await a.reserve(id, HOLD, BUDGET, '')).outcome).toBe(
+            'insufficient',
+        );
+    });
+
+    it('keeps renewal and release consistent when they race', async () => {
+        const id = user();
+        const held = await reserve(a, id, HOLD, BUDGET, 200);
+        const member = held.outcome === 'accepted' ? held.member : null;
+        await Promise.all([a.refresh(id, member), b.release(id, member)]);
+        // Whichever ran last decides; a renewal that lost the race only
+        // brings the hold back until its owner releases it again.
+        await a.release(id, member);
+        expect(await a.outstanding(id)).toBe(0);
+        expect((await reserve(b, id, HOLD)).outcome).toBe('accepted');
+    });
+
+    it('refuses amounts it can’t hold without touching the hold set', async () => {
+        const id = user();
+        await reserve(a, id, 1000);
+        for (const amount of [0, -5_000, Number.NaN, Infinity]) {
+            expect((await reserve(a, id, amount)).outcome).toBe('insufficient');
+        }
+        expect(await a.outstanding(id)).toBe(1000);
+    });
+
+    it('starts a missing version from a random value', async () => {
+        const id = user();
+        expect(await a.version(id)).toBe('0');
+        await b.bump(id);
+        const first = (await a.version(id))!;
+        expect(first).not.toBe('1');
+        await b.bump(id);
+        expect(Number(await a.version(id))).toBe(Number(first) + 1);
+    });
+
+    it('reports an unreachable cache as unavailable, not as insufficient', async () => {
+        const id = user();
+        const client = servers[0].clients.redis as unknown as {
+            creditHoldReserve: () => Promise<unknown>;
+            get: () => Promise<unknown>;
+        };
+        const reserveSpy = vi
+            .spyOn(client, 'creditHoldReserve')
+            .mockRejectedValueOnce(new Error('cache down'));
+        expect((await a.reserve(id, 1000, BUDGET, '0')).outcome).toBe(
+            'unavailable',
+        );
+        const getSpy = vi
+            .spyOn(client, 'get')
+            .mockRejectedValueOnce(new Error('cache down'));
+        expect(await a.version(id)).toBeNull();
+        reserveSpy.mockRestore();
+        getSpy.mockRestore();
+        expect(await a.outstanding(id)).toBe(0);
+    });
+});

src/backend/stores/metering/CreditHoldStore.ts

@@ -48,6 +48,25 @@ const KEY_TTL_SLACK_MS = 60 * 1000;
 
 const holdsKey = (userId: string): string => `meter:holds:{${userId}}`;
 
+/**
+ * Counts changes to an actor's balance and holds, so a reservation can tell
+ * whether the balance it read is still current. Shares the hold key's slot.
+ */
+const versionKey = (userId: string): string =>
+    `meter:holds:{${userId}}:version`;
+
+/** Outlives any read-then-reserve window by orders of magnitude. */
+const VERSION_TTL_MS = 60 * 60 * 1000;
+
+/** What a conditional reservation came to. */
+export type CreditReservation =
+    | { outcome: 'accepted'; member: string }
+    | { outcome: 'insufficient' }
+    // The balance changed since `version` was read; read it again.
+    | { outcome: 'stale' }
+    // The cache couldn't answer; nothing was held.
+    | { outcome: 'unavailable' };
+
 // -- Scripts ----------------------------------------------------------
 
 /**
@@ -79,8 +98,8 @@ return 1
  * name (`<id>:<amount>`) so one sorted set carries both the deadline and the
  * number, and pruning and summing happen in the same pass.
  */
-const SUM_SCRIPT = `
-local dropped = redis.call('ZREMRANGEBYSCORE', KEYS[1], '-inf', ARGV[1])
+const pruneAndSum = (now: string) => `
+local dropped = redis.call('ZREMRANGEBYSCORE', KEYS[1], '-inf', ${now})
 local total = 0
 local members = redis.call('ZRANGE', KEYS[1], 0, -1)
 for i = 1, #members do
@@ -89,13 +108,65 @@ for i = 1, #members do
         total = total + (tonumber(string.sub(members[i], sep + 1)) or 0)
     end
 end
+`;
+
+const SUM_SCRIPT = `${pruneAndSum('ARGV[1]')}
 return { tostring(total), dropped }
 `;
 
+/**
+ * KEYS: the actor's hold set, its version. ARGV: member, deadline, key ttl,
+ * now, amount, budget, expected version ('' skips the check).
+ *
+ * Takes the hold only if it fits in `budget` beside the live holds, in one step
+ * so two reservations can't both fit in the same headroom. The version check
+ * refuses a budget read before a usage write or release that has since landed.
+ */
+const RESERVE_SCRIPT = `
+if ARGV[7] ~= '' and (redis.call('GET', KEYS[2]) or '0') ~= ARGV[7] then
+    return { 'stale', 0 }
+end
+${pruneAndSum('ARGV[4]')}
+if total + tonumber(ARGV[5]) > tonumber(ARGV[6]) then
+    return { 'insufficient', dropped }
+end
+local ttl = redis.call('PTTL', KEYS[1])
+redis.call('ZADD', KEYS[1], ARGV[2], ARGV[1])
+if tonumber(ARGV[3]) > ttl then
+    redis.call('PEXPIRE', KEYS[1], ARGV[3])
+end
+return { 'accepted', dropped }
+`;
+
+/**
+ * Bumps the version in KEYS[n], starting a missing one from a random value so a
+ * version read before the key expired can't match its successor.
+ */
+const bumpVersion = (key: string, seed: string, ttl: string) => `
+if redis.call('EXISTS', ${key}) == 0 then
+    redis.call('SET', ${key}, ${seed})
+end
+redis.call('INCR', ${key})
+redis.call('PEXPIRE', ${key}, ${ttl})
+`;
+
+/** KEYS: the actor's hold version. ARGV: version ttl, seed. */
+const BUMP_SCRIPT = `
+${bumpVersion('KEYS[1]', 'ARGV[2]', 'ARGV[1]')}
+return 1
+`;
+
+/** A random starting version; see `bumpVersion`. */
+const versionSeed = (): string =>
+    String(Math.floor((Math.random() * Number.MAX_SAFE_INTEGER) / 2));
+
 type ScriptRunner = {
     creditHoldTake(...args: string[]): Promise<number>;
     creditHoldSum(...args: string[]): Promise<[string, number]>;
+    creditHoldReserve(...args: string[]): Promise<[string, number]>;
     zrem(key: string, member: string): Promise<number>;
+    creditHoldBump(...args: string[]): Promise<number>;
+    get(key: string): Promise<string | null>;
 };
 
 // -- CreditHoldStore --------------------------------------------------
@@ -135,6 +206,14 @@ export class CreditHoldStore extends PuterStore {
             numberOfKeys: 1,
             lua: SUM_SCRIPT,
         });
+        client.defineCommand('creditHoldReserve', {
+            numberOfKeys: 2,
+            lua: RESERVE_SCRIPT,
+        });
+        client.defineCommand('creditHoldBump', {
+            numberOfKeys: 1,
+            lua: BUMP_SCRIPT,
+        });
     }
 
     /**
@@ -195,7 +274,92 @@ export class CreditHoldStore extends PuterStore {
         }
     }
 
-    /** Give a hold back. Safe to call twice; the second call is a no-op. */
+    /**
+     * The actor's balance version, to pass to `reserve` once the balance has
+     * been read. Null when the cache can't answer.
+     */
+    async version(userId: string): Promise<string | null> {
+        try {
+            return (await this.#redis.get(versionKey(userId))) ?? '0';
+        } catch (e) {
+            console.warn(
+                `[metering] credit hold version unreadable for ${userId}: ${(e as Error).message}`,
+            );
+            return null;
+        }
+    }
+
+    /**
+     * Commit `amount` only if it fits in `budget` beside the holds already
+     * live, as one step. `budget` is the gross balance read after `version`;
+     * pass `version: ''` to skip the staleness check.
+     */
+    async reserve(
+        userId: string,
+        amount: number,
+        budget: number,
+        version: string,
+        ttlMs: number = DEFAULT_HOLD_TTL_MS,
+    ): Promise<CreditReservation> {
+        // Nothing to hold, and a negative hold would lower everyone else's.
+        if (!userId || !Number.isFinite(amount) || amount <= 0) {
+            return { outcome: 'insufficient' };
+        }
+        const units = Math.ceil(amount);
+        const member = `${randomUUID()}:${units}`;
+        const now = Date.now();
+        try {
+            const [outcome, dropped] = await this.#redis.creditHoldReserve(
+                holdsKey(userId),
+                versionKey(userId),
+                member,
+                String(now + ttlMs),
+                String(ttlMs + KEY_TTL_SLACK_MS),
+                String(now),
+                String(units),
+                String(Math.floor(Math.min(budget, Number.MAX_SAFE_INTEGER))),
+                version,
+            );
+            if (dropped > 0) expiredHoldsCounter.add(dropped);
+            if (outcome === 'accepted') return { outcome, member };
+            if (outcome === 'insufficient' || outcome === 'stale') {
+                return { outcome };
+            }
+            throw new Error(`unexpected reservation outcome ${outcome}`);
+        } catch (e) {
+            console.warn(
+                `[metering] credit hold not reserved for ${userId}: ${(e as Error).message}`,
+            );
+            return { outcome: 'unavailable' };
+        }
+    }
+
+    /**
+     * Marks the actor's balance as changed, so a reservation that read it
+     * before the change reads it again. Call once a usage write has landed.
+     */
+    async bump(userId: string): Promise<void> {
+        if (!userId) return;
+        try {
+            await this.#redis.creditHoldBump(
+                versionKey(userId),
+                String(VERSION_TTL_MS),
+                versionSeed(),
+            );
+        } catch (e) {
+            console.warn(
+                `[metering] credit hold version not bumped for ${userId}: ${(e as Error).message}`,
+            );
+        }
+    }
+
+    /**
+     * Give a hold back. Safe to call twice; the second call releases nothing.
+     *
+     * The version isn't bumped here: the usage a hold stands for bumps it when
+     * it's recorded, before the hold is released, and a release with no usage
+     * leaves the balance as it was.
+     */
     async release(userId: string, member: string | null): Promise<void> {
         if (!userId || !member) return;
         try {

src/backend/stores/metering/MeteringBufferStore.test.ts

@@ -420,6 +420,625 @@ describe('MeteringBufferStore', () => {
             expect(await storedTotal(key)).toBe(0);
         });
 
+        /** Holds `method` on `target` until the returned release is called. */
+        const holdCalls = <T extends object>(on: T, method: keyof T) => {
+            let release: () => void = () => {};
+            const gate = new Promise<void>((r) => (release = r));
+            const real = (on[method] as (...a: unknown[]) => unknown).bind(on);
+            const spy = vi
+                .spyOn(on, method as never)
+                .mockImplementation((async (...args: unknown[]) => {
+                    await gate;
+                    return real(...args);
+                }) as never);
+            return { spy, release };
+        };
+        const readTotal = async () =>
+            ((await target.get({ key })).res as { total?: number } | null)
+                ?.total ?? 0;
+
+        it('counts usage a flush has claimed but not yet written onward', async () => {
+            await target.incr({ key, pathAndAmountMap: { total: 10 } });
+            const write = holdCalls(kv, 'incr');
+            try {
+                const flushing = target.flushCycle();
+                await vi.waitFor(() => expect(write.spy).toHaveBeenCalled());
+                expect(await readTotal()).toBe(10);
+                write.release();
+                await flushing;
+            } finally {
+                write.spy.mockRestore();
+            }
+            expect(await readTotal()).toBe(10);
+            expect(await storedTotal(key)).toBe(10);
+        });
+
+        it('counts usage written onward until its settle lands', async () => {
+            await target.incr({ key, pathAndAmountMap: { total: 10 } });
+            await target.flushCycle();
+            await target.incr({ key, pathAndAmountMap: { total: 5 } });
+            const redis = server.clients.redis as unknown as {
+                meterSettle: (...args: string[]) => Promise<number>;
+            };
+            const settle = holdCalls(redis, 'meterSettle');
+            try {
+                const flushing = target.flushCycle();
+                await vi.waitFor(() => expect(settle.spy).toHaveBeenCalled());
+                expect(await storedTotal(key)).toBe(15);
+                expect(await readTotal()).toBe(15);
+                settle.release();
+                await flushing;
+            } finally {
+                settle.spy.mockRestore();
+            }
+            expect(await readTotal()).toBe(15);
+        });
+
+        it('counts a claim in array reads too', async () => {
+            await target.incr({ key, pathAndAmountMap: { total: 4 } });
+            const write = holdCalls(kv, 'incr');
+            try {
+                const flushing = target.flushCycle();
+                await vi.waitFor(() => expect(write.spy).toHaveBeenCalled());
+                const { res } = await target.get({ key: [key] });
+                expect((res as [{ total: number }])[0].total).toBe(4);
+                write.release();
+                await flushing;
+            } finally {
+                write.spy.mockRestore();
+            }
+        });
+
+        it('counts a claim in the running total incr returns', async () => {
+            await target.incr({ key, pathAndAmountMap: { total: 10 } });
+            const write = holdCalls(kv, 'incr');
+            try {
+                const flushing = target.flushCycle();
+                await vi.waitFor(() => expect(write.spy).toHaveBeenCalled());
+                const { res } = await target.incr({
+                    key,
+                    pathAndAmountMap: { total: 5 },
+                });
+                expect((res as { total: number }).total).toBe(15);
+                write.release();
+                await flushing;
+            } finally {
+                write.spy.mockRestore();
+            }
+        });
+
+        it('counts another flush’s claim in an exact read', async () => {
+            await target.incr({ key, pathAndAmountMap: { total: 10 } });
+            const write = holdCalls(kv, 'incr');
+            try {
+                const flushing = target.flushCycle();
+                await vi.waitFor(() => expect(write.spy).toHaveBeenCalled());
+                const { res } = await target.readExact({ key });
+                expect((res as { total: number }).total).toBe(10);
+                write.release();
+                await flushing;
+            } finally {
+                write.spy.mockRestore();
+            }
+            const { res } = await target.readExact({ key });
+            expect((res as { total: number }).total).toBe(10);
+        });
+
+        it('misses nothing in an exact read when a flush lands between its reads', async () => {
+            await target.incr({ key, pathAndAmountMap: { total: 10 } });
+            const write = holdCalls(kv, 'incr');
+            const flushing = target.flushCycle();
+            await vi.waitFor(() => expect(write.spy).toHaveBeenCalled());
+
+            // The store read sees the counter from before the flush's write;
+            // the flush then writes it and leaves its claim before any claim
+            // read that follows the store read.
+            let storeReadStarted = false;
+            let flushed!: Promise<void>;
+            const realGet = kv.get.bind(kv);
+            const get = vi.spyOn(kv, 'get').mockImplementation(async (args) => {
+                if (!args.consistentRead || args.key !== key) {
+                    return realGet(args);
+                }
+                if (storeReadStarted) return realGet(args);
+                storeReadStarted = true;
+                const before = await realGet(args);
+                write.release();
+                flushed = flushing.then(() => {});
+                await flushed;
+                return before;
+            });
+            const redis = server.clients.redis as unknown as {
+                meterRead: (...args: string[]) => Promise<unknown>;
+            };
+            const realRead = redis.meterRead.bind(redis);
+            const read = vi
+                .spyOn(redis, 'meterRead')
+                .mockImplementation(async (...args: string[]) => {
+                    if (storeReadStarted) {
+                        await vi.waitFor(() => expect(flushed).toBeDefined());
+                        await flushed;
+                    }
+                    return realRead(...args);
+                });
+            try {
+                const { res } = await target.readExact({ key });
+                expect((res as { total: number }).total).toBe(10);
+            } finally {
+                get.mockRestore();
+                read.mockRestore();
+                write.spy.mockRestore();
+                await flushing;
+            }
+            expect(await storedTotal(key)).toBe(10);
+        });
+
+        it('counts nothing twice in an exact read when a flush lands during its store read', async () => {
+            await target.incr({ key, pathAndAmountMap: { total: 10 } });
+            const write = holdCalls(kv, 'incr');
+            const flushing = target.flushCycle();
+            await vi.waitFor(() => expect(write.spy).toHaveBeenCalled());
+
+            // The claim was read with the amount still on it; the store read
+            // then sees it written.
+            let landed = false;
+            const realGet = kv.get.bind(kv);
+            const get = vi.spyOn(kv, 'get').mockImplementation(async (args) => {
+                if (args.consistentRead && args.key === key && !landed) {
+                    landed = true;
+                    write.release();
+                    await flushing;
+                }
+                return realGet(args);
+            });
+            try {
+                const { res } = await target.readExact({ key });
+                expect((res as { total: number }).total).toBe(10);
+            } finally {
+                get.mockRestore();
+                write.spy.mockRestore();
+                await flushing;
+            }
+        });
+
+        it('counts usage behind another flush’s claim in an exact read', async () => {
+            await target.incr({ key, pathAndAmountMap: { total: 10 } });
+            const write = holdCalls(kv, 'incr');
+            try {
+                const flushing = target.flushCycle();
+                await vi.waitFor(() => expect(write.spy).toHaveBeenCalled());
+                // Arrives while the claim is out, so it can't be flushed yet.
+                await target.incr({ key, pathAndAmountMap: { total: 5 } });
+                const { res } = await target.readExact({ key });
+                expect((res as { total: number }).total).toBe(15);
+                write.release();
+                await flushing;
+            } finally {
+                write.spy.mockRestore();
+            }
+        });
+
+        /**
+         * Lets a held flush finish during the first consistent store read of
+         * `key`, which then answers with what the store holds afterwards.
+         */
+        const landDuringStoreRead = (
+            release: () => void,
+            flushing: Promise<unknown>,
+        ) => {
+            let landed = false;
+            const realGet = kv.get.bind(kv);
+            return vi.spyOn(kv, 'get').mockImplementation(async (args) => {
+                const ours = Array.isArray(args.key)
+                    ? args.key.includes(key)
+                    : args.key === key;
+                if (args.consistentRead && ours && !landed) {
+                    landed = true;
+                    release();
+                    await flushing;
+                }
+                return realGet(args);
+            });
+        };
+
+        for (const shape of ['single', 'array'] as const) {
+            it(`counts nothing twice in ${shape === 'single' ? 'a single' : 'an array'} read without a base when a flush lands during it`, async () => {
+                await target.incr({ key, pathAndAmountMap: { total: 10 } });
+                // No cached base: the counter is new to the store.
+                await target.forgetBase(key);
+                const write = holdCalls(kv, 'incr');
+                const flushing = target.flushCycle();
+                await vi.waitFor(() => expect(write.spy).toHaveBeenCalled());
+                const get = landDuringStoreRead(write.release, flushing);
+                try {
+                    const { res } = await target.get({
+                        key: shape === 'single' ? key : [key],
+                    });
+                    const value = (
+                        shape === 'single' ? res : (res as unknown[])[0]
+                    ) as { total: number };
+                    expect(value.total).toBe(10);
+                } finally {
+                    get.mockRestore();
+                    write.spy.mockRestore();
+                    await flushing;
+                }
+            });
+        }
+
+        it('reads a written-through increment once the cache is back', async () => {
+            await target.incr({ key, pathAndAmountMap: { total: 10 } });
+            await target.flushCycle();
+            const redis = server.clients.redis as unknown as {
+                meterIncr: (...args: string[]) => Promise<unknown>;
+            };
+            const failing = vi
+                .spyOn(redis, 'meterIncr')
+                .mockRejectedValueOnce(new Error('cache down'));
+            const { res, exact } = await target.incr({
+                key,
+                pathAndAmountMap: { total: 5 },
+            });
+            failing.mockRestore();
+            expect(exact).toBe(true);
+            expect((res as { total: number }).total).toBe(15);
+            expect(await readTotal()).toBe(15);
+        });
+
+        it('reads the store consistently when no base is cached', async () => {
+            await kv.incr({ key, pathAndAmountMap: { total: 3 } });
+            const get = vi.spyOn(kv, 'get');
+            try {
+                expect(await readTotal()).toBe(3);
+                expect(get).toHaveBeenCalledWith(
+                    expect.objectContaining({ key, consistentRead: true }),
+                );
+            } finally {
+                get.mockRestore();
+            }
+        });
+
+        for (const shape of ['single', 'array', 'exact'] as const) {
+            it(`does not retry a ${shape} store read when only new increments arrive`, async () => {
+                await kv.incr({ key, pathAndAmountMap: { total: 100 } });
+                await target.incrAux({ key, pathAndAmountMap: { total: 10 } });
+                const dynamo = server.clients.dynamo;
+                const realGet = dynamo.get.bind(dynamo);
+                const realBatchGet = dynamo.batchGet.bind(dynamo);
+                let storeReads = 0;
+                const increment = async () => {
+                    storeReads++;
+                    await target.incrAux({
+                        key,
+                        pathAndAmountMap: { total: 5 },
+                    });
+                };
+                const get = vi
+                    .spyOn(dynamo, 'get')
+                    .mockImplementation(async (...args) => {
+                        const result = await realGet(...args);
+                        if (args[1].key === key) await increment();
+                        return result;
+                    });
+                const batchGet = vi
+                    .spyOn(dynamo, 'batchGet')
+                    .mockImplementation(async (...args) => {
+                        const result = await realBatchGet(...args);
+                        if (args[0].some(({ items }) => items.key === key))
+                            await increment();
+                        return result;
+                    });
+                const redis = server.clients.redis as unknown as {
+                    meterRead: (...args: string[]) => Promise<unknown>;
+                };
+                const read = vi.spyOn(redis, 'meterRead');
+                try {
+                    const { res } =
+                        shape === 'exact'
+                            ? await target.readExact({ key })
+                            : await target.get({
+                                  key: shape === 'single' ? key : [key],
+                              });
+                    const value = (
+                        shape === 'array' ? (res as unknown[])[0] : res
+                    ) as { total: number };
+                    expect(value.total).toBe(110);
+                    expect(storeReads).toBe(1);
+                    expect(read).toHaveBeenCalledTimes(2);
+                } finally {
+                    get.mockRestore();
+                    batchGet.mockRestore();
+                    read.mockRestore();
+                }
+                expect(await readTotal()).toBe(115);
+            });
+
+            it(`retries a ${shape} read when new increments hide a completed flush`, async () => {
+                await kv.incr({ key, pathAndAmountMap: { total: 0 } });
+                await target.incrAux({ key, pathAndAmountMap: { total: 10 } });
+                const dynamo = server.clients.dynamo;
+                const write = holdCalls(dynamo, 'update');
+                const flushing = target.flushCycle();
+                await vi.waitFor(() => expect(write.spy).toHaveBeenCalled());
+                const realGet = dynamo.get.bind(dynamo);
+                const realBatchGet = dynamo.batchGet.bind(dynamo);
+                let storeReads = 0;
+                const land = async () => {
+                    if (++storeReads !== 1) return;
+                    write.release();
+                    await flushing;
+                    await target.incrAux({
+                        key,
+                        pathAndAmountMap: { total: 20 },
+                    });
+                };
+                const get = vi
+                    .spyOn(dynamo, 'get')
+                    .mockImplementation(async (...args) => {
+                        if (args[1].key === key) await land();
+                        return realGet(...args);
+                    });
+                const batchGet = vi
+                    .spyOn(dynamo, 'batchGet')
+                    .mockImplementation(async (...args) => {
+                        if (args[0].some(({ items }) => items.key === key))
+                            await land();
+                        return realBatchGet(...args);
+                    });
+                try {
+                    const { res } =
+                        shape === 'exact'
+                            ? await target.readExact({ key })
+                            : await target.get({
+                                  key: shape === 'single' ? key : [key],
+                              });
+                    const value = (
+                        shape === 'array' ? (res as unknown[])[0] : res
+                    ) as { total: number };
+                    expect(value.total).toBe(30);
+                    expect(storeReads).toBe(2);
+                } finally {
+                    get.mockRestore();
+                    batchGet.mockRestore();
+                    write.release();
+                    await flushing;
+                    write.spy.mockRestore();
+                }
+            });
+        }
+
+        it('keeps changed counters together in a batch retry', async () => {
+            const keys = [`${key}:a`, `${key}:b`];
+            await Promise.all(
+                keys.map((k) =>
+                    kv.incr({ key: k, pathAndAmountMap: { total: 0 } }),
+                ),
+            );
+            await Promise.all(
+                keys.map((k) =>
+                    target.incrAux({ key: k, pathAndAmountMap: { total: 10 } }),
+                ),
+            );
+            const dynamo = server.clients.dynamo;
+            const realBatchGet = dynamo.batchGet.bind(dynamo);
+            const write = holdCalls(dynamo, 'update');
+            const flushing = target.flushCycle();
+            await vi.waitFor(() => expect(write.spy).toHaveBeenCalledTimes(2));
+            const batches: string[][] = [];
+            const batchGet = vi
+                .spyOn(dynamo, 'batchGet')
+                .mockImplementation(async (...args) => {
+                    batches.push(
+                        args[0].map(({ items }) => items.key as string),
+                    );
+                    if (batches.length === 1) {
+                        write.release();
+                        await flushing;
+                    }
+                    return realBatchGet(...args);
+                });
+            const get = vi.spyOn(dynamo, 'get');
+            try {
+                expect((await target.get({ key: keys })).res).toEqual([
+                    { total: 10 },
+                    { total: 10 },
+                ]);
+                expect(batches).toHaveLength(2);
+                expect(batches.map((batch) => batch.sort())).toEqual([
+                    keys,
+                    keys,
+                ]);
+                expect(get).not.toHaveBeenCalled();
+            } finally {
+                batchGet.mockRestore();
+                get.mockRestore();
+                write.release();
+                await flushing;
+                write.spy.mockRestore();
+            }
+        });
+
+        it('detects a whole flush between snapshots with no outstanding claim', async () => {
+            await kv.incr({ key, pathAndAmountMap: { total: 0 } });
+            await target.incrAux({ key, pathAndAmountMap: { total: 10 } });
+            const dynamo = server.clients.dynamo;
+            const realGet = dynamo.get.bind(dynamo);
+            let reads = 0;
+            const get = vi
+                .spyOn(dynamo, 'get')
+                .mockImplementation(async (...args) => {
+                    if (args[1].key === key && ++reads === 1) {
+                        await target.flushCycle();
+                        await target.incrAux({
+                            key,
+                            pathAndAmountMap: { total: 20 },
+                        });
+                    }
+                    return realGet(...args);
+                });
+            try {
+                expect(await readTotal()).toBe(30);
+                expect(reads).toBe(2);
+            } finally {
+                get.mockRestore();
+            }
+        });
+
+        it('retries a decreasing buffer even when the flush metadata is unchanged', async () => {
+            await kv.incr({ key, pathAndAmountMap: { total: 100 } });
+            await target.incrAux({ key, pathAndAmountMap: { total: 10 } });
+            const dynamo = server.clients.dynamo;
+            const realGet = dynamo.get.bind(dynamo);
+            let reads = 0;
+            const get = vi
+                .spyOn(dynamo, 'get')
+                .mockImplementation(async (...args) => {
+                    const result = await realGet(...args);
+                    if (args[1].key === key && ++reads === 1) {
+                        await target.incrAux({
+                            key,
+                            pathAndAmountMap: { total: -5 },
+                        });
+                    }
+                    return result;
+                });
+            try {
+                expect(await readTotal()).toBe(105);
+                expect(reads).toBe(2);
+            } finally {
+                get.mockRestore();
+            }
+        });
+
+        it('detects applied paths while the claim id and fence token stay unchanged', async () => {
+            await kv.incr({ key, pathAndAmountMap: { total: 0 } });
+            await target.incrAux({ key, pathAndAmountMap: { total: 10 } });
+            const dynamo = server.clients.dynamo;
+            const redis = server.clients.redis as unknown as {
+                meterSettle: (...args: string[]) => Promise<number>;
+            };
+            const write = holdCalls(dynamo, 'update');
+            const settle = holdCalls(redis, 'meterSettle');
+            const flushing = target.flushCycle();
+            await vi.waitFor(() => expect(write.spy).toHaveBeenCalled());
+            const realGet = dynamo.get.bind(dynamo);
+            let reads = 0;
+            const get = vi
+                .spyOn(dynamo, 'get')
+                .mockImplementation(async (...args) => {
+                    if (args[1].key === key && ++reads === 1) {
+                        write.release();
+                        await vi.waitFor(() =>
+                            expect(settle.spy).toHaveBeenCalled(),
+                        );
+                        await target.incrAux({
+                            key,
+                            pathAndAmountMap: { total: 20 },
+                        });
+                    }
+                    return realGet(...args);
+                });
+            try {
+                expect(await readTotal()).toBe(30);
+                expect(reads).toBe(2);
+            } finally {
+                get.mockRestore();
+                write.release();
+                settle.release();
+                await flushing;
+                write.spy.mockRestore();
+                settle.spy.mockRestore();
+            }
+        });
+
+        it('does not retry unchanged amounts when another counter advances the bucket token', async () => {
+            await kv.incr({ key, pathAndAmountMap: { total: 100 } });
+            let other = `${key}:other`;
+            for (let i = 0; bucketTag(other) !== bucketTag(key); i++)
+                other = `${key}:${i}`;
+            await kv.incr({ key: other, pathAndAmountMap: { total: 0 } });
+            await target.incrAux({
+                key: other,
+                pathAndAmountMap: { total: 10 },
+            });
+            const dynamo = server.clients.dynamo;
+            const realGet = dynamo.get.bind(dynamo);
+            let reads = 0;
+            const get = vi
+                .spyOn(dynamo, 'get')
+                .mockImplementation(async (...args) => {
+                    if (args[1].key === key && ++reads === 1)
+                        await target.flushCycle();
+                    return realGet(...args);
+                });
+            try {
+                expect(await readTotal()).toBe(100);
+                expect(reads).toBe(1);
+            } finally {
+                get.mockRestore();
+            }
+        });
+
+        it('recovers a failed initial cache snapshot before retrying the batch', async () => {
+            await kv.incr({ key, pathAndAmountMap: { total: 100 } });
+            await target.incrAux({ key, pathAndAmountMap: { total: 10 } });
+            const redis = server.clients.redis as unknown as {
+                meterRead: (...args: string[]) => Promise<unknown>;
+            };
+            const read = vi
+                .spyOn(redis, 'meterRead')
+                .mockRejectedValueOnce(new Error('cache unavailable'));
+            const batchGet = vi.spyOn(server.clients.dynamo, 'batchGet');
+            try {
+                expect((await target.get({ key: [key] })).res).toEqual([
+                    { total: 110 },
+                ]);
+                expect(batchGet).toHaveBeenCalledTimes(2);
+            } finally {
+                read.mockRestore();
+                batchGet.mockRestore();
+            }
+        });
+
+        it('bounds concurrent cache reads while preserving array order', async () => {
+            const keys = Array.from({ length: 25 }, (_, i) => `${key}:${i}`);
+            await Promise.all(
+                keys.map((k, i) =>
+                    target.incrAux({
+                        key: k,
+                        pathAndAmountMap: { total: i + 1 },
+                    }),
+                ),
+            );
+            const redis = server.clients.redis as unknown as {
+                meterRead: (...args: string[]) => Promise<unknown>;
+            };
+            const realRead = redis.meterRead.bind(redis);
+            let active = 0;
+            let peak = 0;
+            const read = vi
+                .spyOn(redis, 'meterRead')
+                .mockImplementation(async (...args) => {
+                    active++;
+                    peak = Math.max(peak, active);
+                    try {
+                        await new Promise((resolve) => setTimeout(resolve, 1));
+                        return await realRead(...args);
+                    } finally {
+                        active--;
+                    }
+                });
+            try {
+                expect((await target.get({ key: keys })).res).toEqual(
+                    keys.map((_, i) => ({ total: i + 1 })),
+                );
+                expect(peak).toBe(20);
+                expect(active).toBe(0);
+            } finally {
+                read.mockRestore();
+            }
+        });
+
         it('reads an unknown counter as absent', async () => {
             const { res } = await target.get({ key });
             expect(res).toBeNull();
@@ -906,12 +1525,16 @@ describe('MeteringBufferStore', () => {
                 '1000000000',
             );
 
+            // Another deployment's write, which only a replacing settle would
+            // bring into the base.
+            await kv.incr({ key, pathAndAmountMap: { total: 1000 } });
             await target.incr({ key, pathAndAmountMap: { total: 5 } });
             await target.flushCycle();
 
-            expect(await storedTotal(key)).toBe(105);
+            expect(await storedTotal(key)).toBe(1105);
+            // The newer base keeps its view, plus what this flush wrote.
             expect(Number(await server.clients.redis.hget(base, 'total'))).toBe(
-                100,
+                105,
             );
         });
 
@@ -1438,6 +2061,30 @@ describe('MeteringBufferStore', () => {
             ).toEqual({});
         });
 
+        it('reads a re-driven write that already landed, with a warm base', async () => {
+            await target.incr({ key, pathAndAmountMap: { total: 100 } });
+            await target.flushCycle();
+            await target.incr({ key, pathAndAmountMap: { total: 5 } });
+
+            const passThrough = kv.incr.bind(kv);
+            const lost = vi
+                .spyOn(kv, 'incr')
+                .mockImplementationOnce(
+                    async (...args: Parameters<typeof kv.incr>) => {
+                        await passThrough(...args);
+                        throw new Error('request timed out');
+                    },
+                );
+            await target.flushCycle();
+            lost.mockRestore();
+            await ageClaim();
+            await target.flushCycle();
+
+            expect(await storedTotal(key)).toBe(105);
+            const { res } = await target.get({ key });
+            expect((res as { total: number }).total).toBe(105);
+        });
+
         it('applies a re-driven write whose first copy never landed', async () => {
             await target.incr({ key, pathAndAmountMap: { total: 5 } });
             const boom = vi
@@ -1742,6 +2389,17 @@ describe('MeteringBufferStore', () => {
                     order.push('dropFromClaim');
                     return realHdel(...args);
                 });
+            // A written batch leaves the claim through this script.
+            const redis = server.clients.redis as unknown as {
+                meterApply: (...args: string[]) => Promise<number>;
+            };
+            const realApply = redis.meterApply.bind(redis);
+            const applySpy = vi
+                .spyOn(redis, 'meterApply')
+                .mockImplementation((...args: string[]) => {
+                    order.push('dropFromClaim');
+                    return realApply(...args);
+                });
             const alarmSpy = vi
                 .spyOn(server.clients.alarm, 'create')
                 .mockImplementation(() => {
@@ -1751,6 +2409,7 @@ describe('MeteringBufferStore', () => {
             await target.flushCycle();
             incrSpy.mockRestore();
             hdelSpy.mockRestore();
+            applySpy.mockRestore();
             alarmSpy.mockRestore();
 
             expect(order).toEqual(['dropFromClaim', 'alarm']);
@@ -1783,7 +2442,13 @@ describe('MeteringBufferStore', () => {
             // right up until the TTL takes the amounts with it.
             const tag = bucketTag(key);
             await server.clients.redis.del(`meter:dirty:{${tag}}`);
+            // Every few cycles a flush reconciles on its own; keep this one
+            // from doing so, whatever the earlier tests left the count at.
+            const scheduled = vi
+                .spyOn(target, 'reconcile')
+                .mockResolvedValue(undefined);
             expect(await target.flushCycle()).toBe(0);
+            scheduled.mockRestore();
             expect(await storedTotal(key)).toBe(0);
 
             const logged = vi

src/backend/stores/metering/MeteringBufferStore.ts

@@ -83,6 +83,19 @@ interface IncrInput {
 
 type FlatAmounts = Record<string, number>;
 
+interface BufferedRead {
+    delta: FlatAmounts;
+    base: FlatAmounts;
+    claim: FlatAmounts;
+    claimId: string;
+    writeToken: string;
+}
+
+interface StoreAndBufferRead {
+    stored: unknown;
+    buffered: FlatAmounts;
+}
+
 /** A claim's write that was recorded before it was sent; see `INTENT_SCRIPT`. */
 interface SettleIntent {
     writer: string;
@@ -126,8 +139,8 @@ const ORPHAN_AGE_MS = 30_000;
 /** Long enough that a counter for the current month can never expire. */
 const BUFFER_TTL_MS = 40 * 24 * 60 * 60 * 1000;
 
-/** How many counters are written onward at once, to keep the load even. */
-const SETTLE_CONCURRENCY = 20;
+/** Cache reads per call or counter writes per cycle in flight at once. */
+const BUFFER_IO_CONCURRENCY = 20;
 
 /** Roughly a minute between compression reports, so they don't flood the log. */
 const CYCLES_PER_COMPRESSION_REPORT = 12;
@@ -152,6 +165,12 @@ const UNWRITABLE_PATH_MEMO_LIMIT = 1000;
  */
 const EXACT_READ_MEMO_LIMIT = 10_000;
 
+/**
+ * Store reads a consistent read makes while the buffer keeps shrinking under
+ * it; see `#readStoreAndBuffer`.
+ */
+const EXACT_READ_ATTEMPTS = 3;
+
 /** Write units past which settling a counter raises the large-item alarm. */
 const LARGE_SETTLE_WRITE_UNITS = 100;
 
@@ -339,6 +358,15 @@ const toScriptArgs = (amounts: Record<string, number>): string[] => {
     return args;
 };
 
+/** Whether two sets of amounts hold the same paths and values. */
+const sameAmounts = (a: FlatAmounts, b: FlatAmounts): boolean => {
+    const paths = Object.keys(a);
+    return (
+        paths.length === Object.keys(b).length &&
+        paths.every((path) => a[path] === b[path])
+    );
+};
+
 /** The subset of `amounts` at `paths`. */
 const pickAmounts = (amounts: FlatAmounts, paths: string[]): FlatAmounts =>
     Object.fromEntries(paths.map((path) => [path, amounts[path]!]));
@@ -380,11 +408,12 @@ export const isBilledCounter = (key: string): boolean =>
 // -- Scripts ----------------------------------------------------------
 
 /**
- * KEYS: delta, base, dirty set, tracked set. ARGV: ttl, member, then
- * path/amount pairs.
+ * KEYS: delta, base, dirty set, tracked set, claimed. ARGV: ttl, member,
+ * pending key prefix, then path/amount pairs.
  *
- * Returns the delta and the base together so a running total can be served
- * without a second round trip. Amounts are floats — costs are fractional.
+ * Returns the delta, the base and any outstanding claim together, so a running
+ * total can be served without a second round trip (see `READ_SCRIPT` for the
+ * claim). Amounts are floats — costs are fractional.
  *
  * The counter joins both sets here. The dirty set is the working list a flush
  * takes from and hands back; the tracked set is only ever added to here and
@@ -392,7 +421,7 @@ export const isBilledCounter = (key: string): boolean =>
  * working list does not.
  */
 const INCR_SCRIPT = `
-for i = 3, #ARGV, 2 do
+for i = 4, #ARGV, 2 do
     redis.call('HINCRBYFLOAT', KEYS[1], ARGV[i], ARGV[i + 1])
 end
 redis.call('PEXPIRE', KEYS[1], ARGV[1])
@@ -400,12 +429,48 @@ redis.call('SADD', KEYS[3], ARGV[2])
 redis.call('PEXPIRE', KEYS[3], ARGV[1])
 redis.call('SADD', KEYS[4], ARGV[2])
 redis.call('PEXPIRE', KEYS[4], ARGV[1])
-return { redis.call('HGETALL', KEYS[1]), redis.call('HGETALL', KEYS[2]) }
+local claim = {}
+local nonce = redis.call('HGET', KEYS[5], ARGV[2])
+if nonce then claim = redis.call('HGETALL', ARGV[3] .. nonce) end
+return { redis.call('HGETALL', KEYS[1]), redis.call('HGETALL', KEYS[2]), claim }
 `;
 
-/** KEYS: delta, base. Reads both without marking the counter for flushing. */
+/**
+ * KEYS: delta, base, claimed, fence token. ARGV: counter, pending key prefix.
+ *
+ * Reads both without marking the counter for flushing, plus the counter's
+ * outstanding claim: amounts a flush has taken but not yet written onward are
+ * in neither the delta nor the base. The claim's key is built here, which is
+ * safe for the reason given at `RECONCILE_SCRIPT`.
+ */
 const READ_SCRIPT = `
-return { redis.call('HGETALL', KEYS[1]), redis.call('HGETALL', KEYS[2]) }
+local claim = {}
+local nonce = redis.call('HGET', KEYS[3], ARGV[1])
+if nonce then claim = redis.call('HGETALL', ARGV[2] .. nonce) end
+return {
+    redis.call('HGETALL', KEYS[1]), redis.call('HGETALL', KEYS[2]), claim,
+    nonce or '', redis.call('GET', KEYS[4]) or ''
+}
+`;
+
+/**
+ * KEYS: pending, base. ARGV: path/amount pairs just written onward.
+ *
+ * Takes written paths off a claim and, when a base is cached, adds them to it
+ * in the same step, so a read counts them all the way to the settle that
+ * replaces the base with the store's own view. Without a base, reads go to the
+ * store, which already has them.
+ */
+const APPLY_SCRIPT = `
+redis.call('HDEL', KEYS[1], '${INTENT_FIELD}')
+local based = redis.call('EXISTS', KEYS[2]) == 1
+for i = 1, #ARGV, 2 do
+    redis.call('HDEL', KEYS[1], ARGV[i])
+    if based then
+        redis.call('HINCRBYFLOAT', KEYS[2], ARGV[i], ARGV[i + 1])
+    end
+end
+return 1
 `;
 
 /**
@@ -651,9 +716,29 @@ end
 return redis.call('HGETALL', KEYS[1])
 `;
 
+/**
+ * KEYS: pending, base, base sequence. ARGV: paths found already applied.
+ *
+ * Takes paths an earlier copy of the write already applied off a claim, and
+ * drops the cached base in the same step: the base may or may not have them,
+ * and the store does, so the next read seeds a fresh one from the store.
+ */
+const FENCED_SCRIPT = `
+redis.call('HDEL', KEYS[1], '${INTENT_FIELD}')
+for i = 1, #ARGV do
+    redis.call('HDEL', KEYS[1], ARGV[i])
+end
+redis.call('DEL', KEYS[2], KEYS[3])
+return 1
+`;
+
 type ScriptRunner = {
-    meterIncr(...args: string[]): Promise<[string[], string[]]>;
-    meterRead(...args: string[]): Promise<[string[], string[]]>;
+    meterIncr(...args: string[]): Promise<[string[], string[], string[]]>;
+    meterRead(
+        ...args: string[]
+    ): Promise<[string[], string[], string[], string, string]>;
+    meterApply(...args: string[]): Promise<number>;
+    meterFenced(...args: string[]): Promise<number>;
     meterDrain(...args: string[]): Promise<[string[], number]>;
     meterClaim(...args: string[]): Promise<string[] | null>;
     /** `[1, amounts]` when re-claimed, `[0, hadIndexEntry]` when not. */
@@ -770,6 +855,8 @@ export class MeteringBufferStore extends PuterStore {
                 `[metering] buffered incr failed, writing through: ${(e as Error).message}`,
             );
             const { res } = await this.#writeThrough(input);
+            // The cached base doesn't have this write; the next read reseeds it.
+            await this.forgetBase(input.key);
             return { res, exact: true };
         }
     }
@@ -817,43 +904,40 @@ export class MeteringBufferStore extends PuterStore {
 
         const keys = key;
         const results: (unknown | null)[] = new Array(keys.length).fill(null);
-        const deltas: FlatAmounts[] = new Array(keys.length).fill(
-            {} as FlatAmounts,
+        const snapshots: (BufferedRead | null)[] = new Array(keys.length).fill(
+            null,
         );
         const misses: number[] = [];
 
-        await Promise.all(
-            keys.map(async (k, i) => {
-                try {
-                    const { delta, base } = await this.#readBuffered(k);
-                    if (Object.keys(base).length > 0) {
-                        results[i] = mergedOrNull(base, delta);
-                        return;
-                    }
-                    // No cached base yet — the store is the only place left to
-                    // ask, and it's cheaper to ask once for every key like it.
-                    deltas[i] = delta;
-                    misses.push(i);
-                } catch (e) {
-                    console.warn(
-                        `[metering] buffered read failed, reading through: ${(e as Error).message}`,
-                    );
-                    misses.push(i);
-                }
-            }),
+        const reads = await runWithConcurrencyLimitSettled(
+            keys,
+            BUFFER_IO_CONCURRENCY,
+            (k) => this.#readBuffered(k),
         );
+        reads.forEach((read, i) => {
+            if (read.status === 'fulfilled') {
+                const { delta, base } = read.value;
+                if (Object.keys(base).length > 0) {
+                    results[i] = mergedOrNull(base, delta);
+                    return;
+                }
+                snapshots[i] = read.value;
+            } else {
+                console.warn(
+                    `[metering] buffered read failed, reading through: ${(read.reason as Error).message}`,
+                );
+            }
+            misses.push(i);
+        });
 
         if (misses.length > 0) {
-            // Unlike the per-key fallbacks above, a failure here is not
-            // absorbed: a caller deciding on a balance must know its answer
-            // is incomplete rather than silently read a buffered-only view.
-            const { res: fetched } = await this.stores.kv.get({
-                key: misses.map((i) => keys[i]!),
-            });
-            const fetchedValues = fetched as (unknown | null)[];
+            const fetched = await this.#readStoreAndBuffer(
+                misses.map((i) => keys[i]!),
+                misses.map((i) => snapshots[i]!),
+            );
             misses.forEach((i, idx) => {
-                const persisted = flattenAmounts(fetchedValues[idx]);
-                results[i] = mergedOrNull(persisted, deltas[i]!);
+                const { stored, buffered } = fetched[idx]!;
+                results[i] = mergedOrNull(flattenAmounts(stored), buffered);
             });
         }
 
@@ -897,7 +981,11 @@ export class MeteringBufferStore extends PuterStore {
                 `[metering] exact read could not flush ${key}: ${(e as Error).message}`,
             );
         }
-        return this.stores.kv.get({ key, consistentRead: true });
+        // Whatever is still buffered, a claim another deployment holds and
+        // usage that arrived behind it included, isn't in the store yet.
+        const [{ stored, buffered }] = await this.#readStoreAndBuffer(key);
+        if (Object.keys(buffered).length === 0) return { res: stored };
+        return { res: mergedOrNull(flattenAmounts(stored), buffered) };
     }
 
     #rememberExactRead(key: string, now: number): void {
@@ -1115,13 +1203,21 @@ export class MeteringBufferStore extends PuterStore {
         this.#definedScripts = true;
         const client = this.clients.redis;
         client.defineCommand('meterIncr', {
-            numberOfKeys: 4,
+            numberOfKeys: 5,
             lua: INCR_SCRIPT,
         });
         client.defineCommand('meterRead', {
-            numberOfKeys: 2,
+            numberOfKeys: 4,
             lua: READ_SCRIPT,
         });
+        client.defineCommand('meterApply', {
+            numberOfKeys: 2,
+            lua: APPLY_SCRIPT,
+        });
+        client.defineCommand('meterFenced', {
+            numberOfKeys: 3,
+            lua: FENCED_SCRIPT,
+        });
         client.defineCommand('meterDrain', {
             numberOfKeys: 2,
             lua: DRAIN_SCRIPT,
@@ -1172,18 +1268,23 @@ export class MeteringBufferStore extends PuterStore {
         pathAndAmountMap,
     }: IncrInput): Promise<{ delta: FlatAmounts; base: FlatAmounts }> {
         const tag = bucketTag(key);
-        const [delta, base] = await this.#redis.meterIncr(
+        const [delta, base, claim] = await this.#redis.meterIncr(
             deltaKey(tag, key),
             baseKey(tag, key),
             dirtyKey(tag),
             trackedKey(tag),
+            claimedKey(tag),
             String(BUFFER_TTL_MS),
             key,
+            pendingKey(tag, ''),
             ...toScriptArgs(pathAndAmountMap),
         );
         this.#absorbedCount++;
         absorbedCounter.add(1);
-        return { delta: pairsToAmounts(delta), base: pairsToAmounts(base) };
+        return {
+            delta: addAmounts(pairsToAmounts(delta), parseClaim(claim).amounts),
+            base: pairsToAmounts(base),
+        };
     }
 
     /**
@@ -1196,7 +1297,9 @@ export class MeteringBufferStore extends PuterStore {
      * is over within seconds.
      */
     async #seedBase(key: string): Promise<FlatAmounts> {
-        const { res } = await this.stores.kv.get({ key });
+        // Consistent, or a write that just landed could be missing from the
+        // base until the next settle replaces it.
+        const { res } = await this.stores.kv.get({ key, consistentRead: true });
         const persisted = flattenAmounts(res);
         const seeded = await this.#redis.meterSeed(
             baseKey(bucketTag(key), key),
@@ -1212,25 +1315,107 @@ export class MeteringBufferStore extends PuterStore {
      * This deployment's cached delta and base for a counter, straight from
      * redis.
      */
-    async #readBuffered(
-        key: string,
-    ): Promise<{ delta: FlatAmounts; base: FlatAmounts }> {
+    async #readBuffered(key: string): Promise<BufferedRead> {
         const tag = bucketTag(key);
-        const [delta, base] = await this.#redis.meterRead(
-            deltaKey(tag, key),
-            baseKey(tag, key),
-        );
-        return { delta: pairsToAmounts(delta), base: pairsToAmounts(base) };
+        const [delta, base, claim, claimId, writeToken] =
+            await this.#redis.meterRead(
+                deltaKey(tag, key),
+                baseKey(tag, key),
+                claimedKey(tag),
+                tokenKey(tag),
+                key,
+                pendingKey(tag, ''),
+            );
+        const claimed = parseClaim(claim).amounts;
+        // Claimed amounts count like buffered ones until their settle.
+        return {
+            delta: addAmounts(pairsToAmounts(delta), claimed),
+            base: pairsToAmounts(base),
+            claim: claimed,
+            claimId,
+            writeToken,
+        };
     }
 
     async #readThrough(key: string): Promise<unknown | null> {
-        const { delta, base } = await this.#readBuffered(key);
-        const resolved =
-            Object.keys(base).length > 0
-                ? base
-                : flattenAmounts((await this.stores.kv.get({ key })).res);
+        const snapshot = await this.#readBuffered(key);
+        const { delta, base } = snapshot;
+        if (Object.keys(base).length > 0) return mergedOrNull(base, delta);
+        const [{ stored, buffered }] = await this.#readStoreAndBuffer(key, [
+            snapshot,
+        ]);
+        return mergedOrNull(flattenAmounts(stored), buffered);
+    }
 
-        return mergedOrNull(resolved, delta);
+    /**
+     * Order buffer snapshots around consistent store reads to avoid losing
+     * flushed usage. Retry changed claims together; new increments alone do not
+     * move amounts to the store and do not invalidate the first snapshot.
+     */
+    async #readStoreAndBuffer(
+        key: string | string[],
+        snapshots?: (BufferedRead | null)[],
+    ): Promise<StoreAndBufferRead[]> {
+        const multi = Array.isArray(key);
+        const keys = multi ? key : [key];
+        const initial = snapshots ?? [await this.#readBuffered(keys[0]!)];
+        let pending = keys.map((k, i) => ({
+            key: k,
+            index: i,
+            before: initial[i] ?? null,
+        }));
+        const results: StoreAndBufferRead[] = new Array(keys.length);
+        for (let attempt = 1; pending.length > 0; attempt++) {
+            const { res } = await this.stores.kv.get({
+                key: multi ? pending.map((item) => item.key) : pending[0]!.key,
+                consistentRead: true,
+            });
+            const stored = multi ? (res as unknown[]) : [res];
+            const checks =
+                attempt < EXACT_READ_ATTEMPTS
+                    ? await runWithConcurrencyLimitSettled(
+                          pending,
+                          BUFFER_IO_CONCURRENCY,
+                          (item) => this.#readBuffered(item.key),
+                      )
+                    : [];
+            const retry: typeof pending = [];
+            pending.forEach((item, i) => {
+                const check = checks[i];
+                if (check?.status === 'fulfilled') {
+                    const after = check.value;
+                    const before = item.before;
+                    // The token catches a whole claim starting and finishing
+                    // between snapshots, even when new increments hide it.
+                    const unchanged =
+                        before &&
+                        (sameAmounts(before.delta, after.delta) ||
+                            (before.writeToken === after.writeToken &&
+                                before.claimId === after.claimId &&
+                                sameAmounts(before.claim, after.claim) &&
+                                Object.entries(before.delta).every(
+                                    ([path, amount]) =>
+                                        (after.delta[path] ?? 0) >= amount,
+                                ) &&
+                                Object.entries(after.delta).every(
+                                    ([path, amount]) =>
+                                        amount >= (before.delta[path] ?? 0),
+                                )));
+                    if (!unchanged) {
+                        retry.push({ ...item, before: after });
+                        return;
+                    }
+                } else if (check?.status === 'rejected' && !multi) {
+                    throw check.reason;
+                }
+                results[item.index] = {
+                    stored: stored[i],
+                    buffered: item.before?.delta ?? {},
+                };
+            });
+            pending = retry;
+        }
+        return results;
     }
 
     // -- Internals: flush ---------------------------------------------
@@ -1302,7 +1487,7 @@ export class MeteringBufferStore extends PuterStore {
 
         const outcomes = await runWithConcurrencyLimitSettled(
             work,
-            SETTLE_CONCURRENCY,
+            BUFFER_IO_CONCURRENCY,
             (run) => run(),
         );
         for (const outcome of outcomes) {
@@ -1590,7 +1775,12 @@ export class MeteringBufferStore extends PuterStore {
                 if (err instanceof KvFencedWriteError) {
                     // Applied already, by an earlier copy of this write.
                     fencedCounter.add(1);
-                    await this.#dropFromClaim(tag, nonce, paths);
+                    await this.#redis.meterFenced(
+                        pendingKey(tag, nonce),
+                        baseKey(tag, key),
+                        baseSeqKey(tag, key),
+                        ...paths,
+                    );
                     continue;
                 }
                 if (!isPermanentSettleError(err)) throw e;
@@ -1618,7 +1808,11 @@ export class MeteringBufferStore extends PuterStore {
             // before anything else can fail: a re-drive then picks up only what
             // is still outstanding. The alarm below is the "anything else" — it
             // comes after.
-            await this.#dropFromClaim(tag, nonce, paths);
+            await this.#redis.meterApply(
+                pendingKey(tag, nonce),
+                baseKey(tag, key),
+                ...toScriptArgs(batch),
+            );
 
             if (usage.write >= LARGE_SETTLE_WRITE_UNITS) {
                 this.#recordLargeSettle(key, usage.write);

src/docs/src/AI/chat.md

@@ -399,6 +399,23 @@ The code implementation is available in our [web search example](/playground/ai-
 
 List of OpenAI models that support the web search can be found in their [API compatibility documentation](https://platform.openai.com/docs/guides/tools-web-search#api-compatibility).
 
+#### Prompt Caching
+
+OpenAI models cache prompt prefixes on their own. Requests from the same app and user share one cache by default, and you can pick the cache with `prompt_cache_key`. Their `usage` reports the tokens read from the cache as `cached_tokens`.
+
+GPT-5.6 and later models charge for cache writes and let you choose how long an entry lives. Pass `prompt_cache_options` with a `ttl` of `"30m"` (the default) or `"12h"`. The `usage` reports the tokens written with the 30 minute lifetime as `cache_write_tokens` and the tokens written with the 12 hour lifetime as `cache_write_12h_tokens`. Writing a 30 minute entry costs 1.25 times the model's input rate, and writing a 12 hour entry costs 2.5 times the input rate. Reads cost the same for both lifetimes. To mark where a reusable prefix ends, add `prompt_cache_breakpoint: { mode: "explicit" }` to a content part. A breakpoint can carry its own `ttl`, which overrides the request's. OpenAI only takes a 12 hour lifetime, or a lifetime on a breakpoint, through its Responses API, so a request that uses either is sent there.
+
+```js
+puter.ai.chat('<your message>', {
+    model: 'gpt-6-luna',
+    prompt_cache_options: { ttl: '12h' }
+});
+```
+
+Older OpenAI models charge nothing for cache writes. Pass `prompt_cache_retention` with `"in_memory"` for an entry that lives a few minutes or `"24h"` for one that can live up to a day. The 24 hour option is the default, and GPT-5.5 and later models only support it.
+
+The `usageDetails` object on every result carries the same counts under provider-neutral names, with one field per lifetime, such as `cacheWrite30mTokens` and `cacheWrite12hTokens`. See the [ChatResponse](/Objects/chatresponse/) object for the full list.
+
 ### Anthropic models
 
 #### Prompt Caching

src/docs/src/AI/convo.md

@@ -41,12 +41,12 @@ The conversation exposes these properties and methods.
 | --- | --- |
 | `state` | `prepared`, `connecting`, `connected`, or `closed`. |
 | `model` | Resolved model name. |
-| `connect()` | Opens the connection and applies settings. Resolves after the provider acknowledges session configuration. Concurrent calls share one attempt. Calling it while connected opens no additional connection. During a reconnection, it resolves when the reconnection succeeds and rejects if the conversation closes instead. |
+| `connect()` | Opens the connection and applies settings. Resolves after the provider acknowledges session configuration. Concurrent calls share one connection Promise, including bounded retries for transient setup failures. Calling it while connected opens no additional connection. During a reconnection, it resolves when the reconnection succeeds and rejects if the conversation closes instead. |
 | `configure(options)` | Updates the given session settings and resolves after the provider acknowledges this update. Settings it isn't given, including ones set through native events, are left alone. Accepts the factory options except `model`. One update can be pending at a time. Provider rules apply to changes such as switching a voice after audio has been generated. |
 | `sendText(text)` | Adds a user message and requests a response. Text must be nonempty and at most 8192 characters. |
 | `appendAudio(pcm)` | Appends an `Int16Array` containing PCM16, 24 kHz mono audio. A chunk contains at most 12000 samples. |
 | `commitAudio()` | Commits buffered audio and requests a response. Requires turn detection to be off, through `turnDetection: false` or a native session update. The provider requires at least 100 ms of buffered audio. |
-| `interrupt(position?)` | Stops built-in playback immediately and waits for cancellation and playback-history synchronization. A reply requested but not yet started is cancelled as soon as it starts. Custom players provide `{ itemId, contentIndex, playedMs }`. An idle call resolves immediately. |
+| `interrupt(position?)` | Stops built-in playback immediately and waits for cancellation and playback-history synchronization. A reply requested but not yet started is cancelled as soon as it starts. Custom players provide `{ itemId, contentIndex, playedMs }`. An idle call resolves immediately. Readiness failures reject the returned Promise with `session_not_ready` or `session_closed`. |
 | `send(event)` | Sends a native OpenAI JSON event. |
 | `on(type, handler)` | Registers a listener and returns an unsubscribe function. Use `'*'` to receive every native and convenience event. |
 | `off(type, handler)` | Removes a listener. |
@@ -54,9 +54,9 @@ The conversation exposes these properties and methods.
 
 Attach listeners before connecting to receive initial session events. Closing during connection rejects the pending attempt.
 
-If the connection drops because of network loss, a server restart or a provider error, the conversation reconnects on its own. While it reconnects, `state` is `connecting`, a `reconnecting` event fires, and pending operations reject with `connection_lost`. The new session gets every setting the provider acknowledged, from the factory options, `configure()` and native `session.update` events. Then `ready` fires again with `reconnected: true`. Listeners, the microphone and the speaker carry over. Microphone audio captured while reconnecting is dropped.
+If the connection drops because of network loss, a server restart or a provider error, the conversation reconnects on its own. Normal closes with code 1000 end the conversation. While it reconnects, `state` is `connecting`, a `reconnecting` event fires, and pending operations reject with `connection_lost`. The new session gets every setting the provider acknowledged, from the factory options, `configure()` and native `session.update` events. Then `ready` fires again with `reconnected: true`. Listeners, the microphone and the speaker carry over. Microphone audio captured while reconnecting is dropped.
 
-The conversation also restores recent context. Before `ready` fires, it adds back up to 40 of the most recent conversation items, 48 KiB in total. Restored items are user text, user speech that has a transcript, assistant replies as text, and function calls with their outputs. User speech has a transcript only when input transcription is configured through native session settings. An assistant reply that was interrupted, or still playing when the connection dropped, is cut to what the user saw or heard. The cut is estimated from how much of the audio played, so it can be off by a few words. Images, speech without a transcript, deleted items, and replies still generating when the connection dropped are left out. Restored items get new item IDs, don't fire item events, and count as input tokens on the next response. Item IDs from before the reconnect don't work in later events. If the provider refuses a restored item, an `error` event fires with code `context_restore_failed` and the conversation stays connected.
+The conversation also restores recent context. Before `ready` fires, it adds back up to 40 of the most recent conversation items, 48 KiB in total. Restored items are user text, user speech that has a transcript, assistant replies as text, and function calls with their outputs. User speech has a transcript only when input transcription is configured through native session settings. An assistant reply that was interrupted, or still playing when the connection dropped, is cut to what the user saw or heard. The cut is estimated from how much of the audio played, so it can be off by a few words. Images, speech without a transcript, deleted items, and replies still generating when the connection dropped are left out. Restored items get new item IDs, don't fire item events, and count as input tokens on the next response. Item IDs from before the reconnect don't work in later events. Restoration uses a contiguous suffix of restorable items. An oversized newest item leaves that suffix empty. Older items left out to fit the window fire a `context_trimmed` event with the count in `omittedItems`; this is routine and not an error. A provider refusal or a failure to send the restored items fires one `error` event with code `context_restore_failed` per restoration. In both cases the conversation stays connected. Items are preserved without truncating text, function arguments or function results.
 
 When Puter knows ahead of time that the server a session runs on will restart, it sends a `puter.reconnect` event, which also reaches your listeners. Without that notice, a restart drops the connection and the conversation reconnects as above. Within a few seconds, the conversation opens a replacement session in the background while the current one keeps working. It switches once no reply is generating or playing, no user turn is being spoken or transcribed, no function call is waiting for its output, and nothing you sent is waiting on the provider. The switch goes through the same steps as a reconnect, and the `reconnecting` event has code 1012. If the replacement can't open yet, the conversation keeps the current session and tries again later. A refusal that retrying can't fix, such as `insufficient_funds`, stops the attempts. If the server closes the session first, the conversation switches to the replacement, or reconnects if none is open.
 
@@ -72,6 +72,7 @@ The conversation emits these events alongside native events.
 | --- | --- |
 | `ready` | `model`, `provider`, and `reconnected: true` after a reconnection |
 | `reconnecting` | `code`, `reason` of the dropped connection. After a `puter.reconnect` event, `code` is 1012. |
+| `context_trimmed` | `omittedItems`, the number of restorable items left out of the restored context after a reconnection. Fires before `ready`. |
 | `text` | `delta`, `responseId` |
 | `transcript` | `role`, `text`, `final`. Assistant deltas use `final: false`. Completed assistant and user transcripts use `final: true`. User transcripts require transcription to be configured through native session settings. |
 | `audio` | `pcm`, `sampleRate`, `responseId`, `itemId`, `contentIndex`. The PCM chunk is an `Int16Array`. |

src/docs/src/AI/realtime.md

@@ -30,6 +30,8 @@ Browser WebSocket clients pass `realtime` and `openai-insecure-api-key.<PUTER_TO
 
 The socket can open before authentication and provider setup finish. Listen for errors and closure immediately. Wait for `session.created`, send your session settings, then wait for `session.updated` before submitting a turn.
 
+To open a replacement while another connection remains healthy, set the optional `purpose=handover` query parameter. These attempts share a smaller per-credential budget, checked before the general connection-attempt budget. Initial connections and dropped-connection recovery use the URL without this parameter. The limits are listed in [rate limits and quotas](/rate-limits-and-quotas/).
+
 ## Text example
 
 Install the `ws` package and set `PUTER_TOKEN` to your Puter token. Run this example as a Node.js ES module:
@@ -109,8 +111,14 @@ A new connection starts an empty conversation. To keep context, add earlier item
 
 ## Errors, billing, and limits
 
-API errors arrive as `{ "type": "error", "error": { "code": "...", "message": "..." } }`. Handle socket errors and close frames too. Authentication failures use `invalid_api_key`. Other relay codes include `model_not_found`, `insufficient_funds`, `subscription_required`, `rate_limit_exceeded`, `invalid_event`, `connection_timeout`, `provider_unavailable`, `upstream_error`, and `server_restarting`.
+API errors arrive as `{ "type": "error", "error": { "code": "...", "message": "..." } }`. Handle socket errors and close frames too. Invalid, missing, or revoked credentials use `invalid_api_key`. If Puter can't check a credential or the account's plan, the error is `internal_error` and the session closes with 1011, so try again after a short, randomized delay. Other relay codes include `permission_denied`, `model_not_found`, `insufficient_funds`, `subscription_required`, `rate_limit_exceeded`, `invalid_event`, `connection_timeout`, `provider_unavailable`, `upstream_error`, and `server_restarting`.
 
-Policy failures generally close with 1008, oversized client messages with 1009, upstream or setup failures with 1011, and server restarts with 1012. Authentication and model failures can arrive after the WebSocket handshake succeeds.
+Policy failures generally close with 1008, oversized client messages with 1009, upstream or setup failures with 1011, server restarts with 1012, and temporary server overload with 1013. Reconnect after 1011, 1012, or 1013. Authentication and model failures can arrive after the WebSocket handshake succeeds.
 
 The endpoint requires a paid Puter plan. Usage is charged after completed responses and input transcriptions. While a response generates, part of your balance is held for it, so a session opens only if your balance covers one response. If the provider connection closes before a response reports its usage, the response is charged the full amount held for it. Each account can open 20 sessions at once by default. Each JSON message you send is limited to 64 KiB, including reassembled fragments. Messages from the provider can be up to 4 MiB. Stream audio in small chunks. All message rates, queue caps, timeouts, and other bounds are published in [rate limits and quotas](/rate-limits-and-quotas/).
+
+Input transcription holds a small amount of your balance per transcribed item, priced at the transcription model you select. Two items are reserved ahead of your audio and replenished as the provider commits them, so a session holds only its spare items plus the items still awaiting a transcript. Changing the transcription model reprices the spare items. If your balance can't cover another item, audio waits while earlier items settle; once none are left to settle, the session closes with `insufficient_funds`. Failed transcriptions, items without final usage, and audio whose commit the provider never acknowledges before the connection closes are each charged that model's fixed per-item amount. Unacknowledged audio is charged one item per started 160 seconds. With server turn detection, only detected speech counts, so silence is never charged. The amounts, timeout and audio limits are listed in [rate limits and quotas](/rate-limits-and-quotas/).
+
+Provider-reported realtime models must have a known price. A missing model uses the last known model. An explicitly unpriced model closes the connection with `upstream_error`.
+
+After recording usage, the connection can continue while settled credit is positive, including a fractional balance. Each new billable operation still needs its full reservation after accounting for other outstanding holds.

src/docs/src/Objects/chatresponse.md

@@ -64,7 +64,7 @@ Extra detail on why generation stopped (e.g. a refusal classification). Provider
 
 #### `usageDetails` (Object)
 
-A provider-neutral usage breakdown, present alongside `usage` on every result. `inputTokens` excludes cache reads/writes; `outputTokens` includes reasoning tokens. Fields: `inputTokens`, `outputTokens`, `cacheReadTokens`, `cacheWrite5mTokens`, `cacheWrite1hTokens`, `reasoningTokens`, `webSearchRequests`, `webFetchRequests`, `speed` (`"fast"` or `"standard"`), `serviceTier`, and `iterations` (a per-pass breakdown when the upstream ran several passes, e.g. compaction or an advisor sub-call).
+A provider-neutral usage breakdown, present alongside `usage` on every result. `inputTokens` excludes cache reads/writes; `outputTokens` includes reasoning tokens. Fields: `inputTokens`, `outputTokens`, `cacheReadTokens`, `cacheWrite5mTokens`, `cacheWrite30mTokens`, `cacheWrite1hTokens`, `cacheWrite12hTokens`, `reasoningTokens`, `webSearchRequests`, `webFetchRequests`, `speed` (`"fast"` or `"standard"`), `serviceTier`, and `iterations` (a per-pass breakdown when the upstream ran several passes, e.g. compaction or an advisor sub-call). Each `cacheWrite*Tokens` field counts the tokens written to the cache with that lifetime: Claude and Moonshot write 5 minute and 1 hour entries, OpenAI writes 30 minute and 12 hour entries.
 
 Prefer `usageDetails` over `usage` for anything beyond the raw billing totals. Claude's `usage.thinking_tokens` is informational: it's included in `output_tokens` and not billed separately — `usageDetails.reasoningTokens` carries the same count.
 

src/docs/src/Objects/chatresponsechunk.md

@@ -102,7 +102,7 @@ Extra detail on why generation stopped (e.g. a refusal classification). Provider
 
 #### `usageDetails` (Object)
 
-A provider-neutral usage breakdown, present on the final `usage` chunk. `inputTokens` excludes cache reads/writes; `outputTokens` includes reasoning tokens. Fields: `inputTokens`, `outputTokens`, `cacheReadTokens`, `cacheWrite5mTokens`, `cacheWrite1hTokens`, `reasoningTokens`, `webSearchRequests`, `webFetchRequests`, `speed` (`"fast"` or `"standard"`), `serviceTier`, and `iterations` (a per-pass breakdown when the upstream ran several passes, e.g. compaction or an advisor sub-call).
+A provider-neutral usage breakdown, present on the final `usage` chunk. `inputTokens` excludes cache reads/writes; `outputTokens` includes reasoning tokens. Fields: `inputTokens`, `outputTokens`, `cacheReadTokens`, `cacheWrite5mTokens`, `cacheWrite30mTokens`, `cacheWrite1hTokens`, `cacheWrite12hTokens`, `reasoningTokens`, `webSearchRequests`, `webFetchRequests`, `speed` (`"fast"` or `"standard"`), `serviceTier`, and `iterations` (a per-pass breakdown when the upstream ran several passes, e.g. compaction or an advisor sub-call). Each `cacheWrite*Tokens` field counts the tokens written to the cache with that lifetime: Claude and Moonshot write 5 minute and 1 hour entries, OpenAI writes 30 minute and 12 hour entries.
 
 #### `message` (String)
 

src/docs/src/rate-limits-and-quotas.md

@@ -102,20 +102,32 @@ Realtime sessions ([`puter.ai.convo()`](/AI/convo/), `/puterai/openai/v1/realtim
 | Event type length | 1–128 characters | Invalid client envelopes receive `invalid_event` and close with 1008. Invalid upstream envelopes close with 1011. |
 | Client message rate | 100/s, burst 100 | Error `rate_limit_exceeded`, close 1008. Ping and pong frames count toward this allowance. |
 | Client upload rate | 128 KiB/s, burst 64 KiB | Reads pause to refill the budget. More than 64 KiB of overdraft closes with `rate_limit_exceeded`. |
-| Input pending session setup | 32 messages or 64 KiB | Error `rate_limit_exceeded`, close 1008. |
+| Client events waiting for forwarding | 32 messages or 64 KiB | Error `rate_limit_exceeded`, close 1008. |
 | Forwarding queue in either direction | Reads pause at 128 KiB. Admission stops above 192 KiB toward the provider and above 4 MiB plus 128 KiB toward the client. | A full queue closes with `rate_limit_exceeded`. |
 | Client that stops reading | 30 seconds of paused upstream reads | Close 1008. |
-| Pending usage records | 32 | Error `rate_limit_exceeded`, close 1008. Records already received are still billed. |
+| Pending usage records | 32 | Error `rate_limit_exceeded`, close 1013. Records already received are still billed. |
 | Numeric usage fields | Finite, nonnegative, at most 1 billion | Invalid upstream usage closes with 1011. A `null` usage counts as none. |
 | Session setup timeout | 15 seconds | Error `connection_timeout`, close 1011. |
 | Upstream handshake timeout | 10 seconds | Close 1011. |
 | Heartbeat interval | 30 seconds | A missing pong terminates the connection on the next heartbeat. |
-| Credential cache and recheck | Cache 60 seconds, sweep every 15 seconds, at most 16 checks in parallel | Invalid credentials close with 1008. Overlapping sweeps are skipped. |
-| Session attempts per credential | 60 per minute | Error `rate_limit_exceeded`, close 1008. |
+| Credential cache and recheck | Cache 60 seconds, sweep every 15 seconds, at most 16 checks in parallel | Invalid credentials close with 1008. A check that fails at connection gets `internal_error` and closes with 1011. Once failures have continued for 60 seconds from the first failed lookup, the next failed check closes with `internal_error` and 1011. Subscription eligibility is checked independently on each sweep and after a plan invalidation. Revocation events close the affected credentials. Overlapping sweeps are skipped. |
+| Session attempts per signature-verified credential | 60 per minute | Error `rate_limit_exceeded`, close 1008. |
+| Pre-auth attempts | 120 per client IP and 600 per node per minute | Local memory admission runs before the WebSocket handshake and signature verification. Exceeding either rate returns HTTP 429. Client IP follows the configured proxy trust policy. The shared memory limiter caps its state at 10,000 keys with a 1-hour retention floor and a 60-second sweep. |
+| Unauthenticated upgrade sockets, including closing sockets | 64 per node | Further upgrades receive HTTP 503. The slot is retained until successful admission or transport closure. |
+| Authentication setups in progress | 64 per node | Further upgrades receive HTTP 503. |
+| Presented credential | 8192 UTF-8 bytes | Longer or malformed credentials receive `invalid_api_key`. Unverified credentials allocate no distributed credential limiter state. Limiter lookup failures close with `internal_error` and 1011. |
+| Credit held per transcription item | The selected model's budget for 8,000 audio input, 8,000 text input and 4,096 text output tokens, or 160 seconds for duration-priced models, at that model's cost factor. Before cost factors: `gpt-4o-transcribe` 10,896,000 micro-cents, `gpt-4o-mini-transcribe` 5,448,000, `whisper-1` 1,600,000, `gpt-transcribe` 1,200,000, and 10,896,000 for any other model | Two spare items are reserved before transcription configuration or audio is forwarded, and replenished as the provider commits items. Enabling `gpt-4o-transcribe` therefore holds 21,792,000 micro-cents, or $0.21792, before cost factors. A model change releases the spare items and reserves new ones at the new price. The hold is a budget rather than a cap on reported usage. |
+| Transcription credit exhausted | When the account can't cover another item | Client reads pause while the session still holds items that may free credit. Once it holds none, error `insufficient_funds`, close 1008. |
+| Pending transcription identity | 64 items, spare items included | Reaching the cap pauses client reads until items settle. Provider commits beyond the cap close the connection with `rate_limit_exceeded` and 1013, and bill unresolved work conservatively. Unresolved item identities are retained. |
+| Transcription usage timeout | 30 seconds per committed item | Missing usage, transcription failure, or an upstream close bills the item's model budget before cost factors. A late or duplicate completion is ignored. |
+| Transcription reservation lifetime | 90 seconds, renewed on the 30-second heartbeat | Credit stays held until accepted usage is recorded. Unused reservation credit is released when the connection ends. |
+| Audio awaiting a commit acknowledgement | One held item per 160 seconds, at the session's input format | Counts all audio since the last commit or clear without turn detection, or only detected speech with server turn detection. Longer audio holds more items rather than closing the session. If the connection closes before the commit is acknowledged, each held item is billed. |
+| Completed transcription identity history | 128 items | Recent duplicate commits are ignored. Pending identities have a separate lifetime. |
+| Replacement attempts marked `purpose=handover` | 20 per credential per minute | This shared limit is checked before the general 60-attempt limit. A refused probe consumes no general attempt. Initial and dropped-session recovery attempts retain their general budget. |
 | Credit held per response | 8,000 audio input and 4,096 audio output tokens at the session model's rates, held until the response's usage is recorded | A session opens only if the account can cover one hold. A response the account can't cover gets `insufficient_funds`, close 1008, and is billed for what it generated. A response whose usage never arrives because the provider connection closed first is billed the full hold. |
 | Restart notice (`puter.reconnect`) | At most once a minute per session | Repeated announcements within the minute aren't sent. |
 | In-flight response drain at shutdown | 5 seconds | Close 1012. |
-| Billing a response after the client disconnects | 5 seconds | The response is cancelled and billed for what it generated, including one that was requested but starts only after the disconnect. A response that doesn't report its usage within the 5 seconds is billed the credit held for it. |
+| Billing a response after the client disconnects | 5 seconds | The response is cancelled and billed for what it generated, including one that was requested but starts only after the disconnect. Pending input transcriptions share this settlement window. Audio whose commit was not acknowledged is committed during settlement. Accepted work without final usage is billed conservatively. A response that does not report its usage within the 5 seconds is billed the credit held for it. |
 
 Send audio as a stream of small chunks. The message cap applies to text, configuration, tool output, and audio alike.
 
@@ -129,6 +141,7 @@ The [`puter.ai.convo()`](/AI/convo/) SDK also applies these limits before sendin
 | PCM chunk | 12000 samples at 24 kHz, or 500 ms | Throws `input_too_large`. |
 | Native JSON traversal | Depth 16, 2048 visited values, 2048 array entries or object fields | Throws `input_too_large` before serialization. |
 | Outbound buffered data | 128 KiB for audio, 192 KiB for other events | Throws `queue_full`. The built-in microphone drops the chunk instead. |
+| Incoming server event | 4 MiB of UTF-8 | The conversation closes with code 4009 and doesn't reconnect. |
 | Pending acknowledgments | 8 | Rejects with `operation_in_progress`. |
 | Concurrent configuration updates | 1 | Rejects with `operation_in_progress`. |
 | Authentication and provider acknowledgment timeout | 10 seconds | Rejects preparation or the pending operation. |
@@ -137,10 +150,10 @@ The [`puter.ai.convo()`](/AI/convo/) SDK also applies these limits before sendin
 | Capture chunk duration | 20 ms | AudioWorklet sends 480 PCM16 samples per chunk. |
 | Unacknowledged capture chunks | 25, or 500 ms | Further chunks are dropped until the page catches up. |
 | Queued playback | 300 seconds | Further audio for the reply is dropped and `queue_full` is reported once. |
-| Reconnection attempts | 10, backing off from 500 ms to 10 seconds, each delay randomized between half and one and a half times its value | The conversation closes with the original close code. |
-| Replacement session after a restart notice | Opened within 3 seconds of the notice, then retried from 1 second, backing off to 10 seconds, each delay randomized between half and one and a half times its value. Settings on a held replacement are acknowledged within 3 seconds. | The current session keeps working until the conversation switches or the server closes it. A refusal that retrying can't fix stops the attempts. |
+| Connection and reconnection attempts | 10, backing off from 500 ms to 10 seconds, each delay randomized between half and one and a half times its value | Initial transient failures retry through the original connection Promise. Terminal credential, model, funds, normal-close and oversized-event failures stop retries. An established conversation closes with the original close code after retries are exhausted. |
+| Replacement session after a restart notice | Opened within 3 seconds of the notice, then retried from 1 second, backing off to 10 seconds, each delay randomized between half and one and a half times its value. Settings on a held replacement are acknowledged within 3 seconds. | The current session keeps working until the conversation switches or the server closes it. Probes stop after 3 attempts or 30 seconds. Conversations sharing one SDK instance and credential share a budget of 20 probes per minute. Dropped-session recovery uses its separate attempt loop. A refusal that retrying cannot fix stops the probes. |
 | Offline wait while reconnecting | 2 minutes per reconnection, in browsers that report being offline | Attempts continue after the wait. |
-| Context restored after a reconnection | The 40 most recent restorable items, 48 KiB in total | Older items are left out. |
+| Context restored after a reconnection | The 40 most recent restorable items, 48 KiB in total | Restoration uses a contiguous suffix of restorable items. If the newest item exceeds the byte budget, the suffix is empty. Omitted items fire a nonfatal `context_trimmed` event with `omittedItems`. `context_restore_failed` is reserved for a provider refusal or a failed send. Text, function arguments and function results are preserved without truncation. |
 | Remembered canceled responses | 32 | Older response IDs are evicted from the suppression set. |
 
 
@@ -284,6 +297,8 @@ Each call is also capped, the same for every account:
 
 A `get()` or batch `set()` over its cap, or an `offset` over 5,000, is rejected with `bad_request` and nothing is read or written. A `limit` over 1,000 is lowered to 1,000, and the page's `cursor` picks up from there.
 
+Internal metering reads check up to 20 counters in Redis concurrently per call. Store-backed metering reads make up to 3 attempts when a flush overlaps the read. Each metering flush writes up to 20 counters concurrently.
+
 ### Filesystem
 
 Per minute unless stated:

src/puter-js/src/modules/ai/ai.test.js

@@ -171,6 +171,20 @@ describe('ai.chat driver payloads', () => {
         });
     });
 
+    it('chat(prompt, options) forwards the OpenAI prompt-cache options', async () => {
+        await ai.chat('hello', {
+            prompt_cache_key: 'ck',
+            prompt_cache_retention: '24h',
+            prompt_cache_options: { mode: 'explicit', ttl: '12h' },
+        });
+        expect(lastBody().args).toEqual({
+            messages: [{ content: 'hello' }],
+            prompt_cache_key: 'ck',
+            prompt_cache_retention: '24h',
+            prompt_cache_options: { mode: 'explicit', ttl: '12h' },
+        });
+    });
+
     it('chat(prompt, options) forwards temperature: 0 and max_tokens: 0', async () => {
         await ai.chat('hello', {
             temperature: 0,

src/puter-js/src/modules/ai/chat.js

@@ -27,6 +27,9 @@ const PARAMS_TO_PASS = [
     'outputFormat',
     'thinking',
     'streamToolInput',
+    'prompt_cache_key',
+    'prompt_cache_retention',
+    'prompt_cache_options',
 ];
 
 // Parameters renamed between the SDK's camelCase option and the driver's

src/puter-js/src/modules/ai/convo.js

@@ -1,6 +1,10 @@
 import { fetchUrl } from '../../lib/networkUtils.js';
 import { promptIfUpgradeRequired } from '../../lib/upgradePrompt.js';
-import { RealtimeSession, createRealtimeSocket } from './convoTransport.js';
+import {
+    CLOSE_MESSAGE_TOO_LARGE,
+    RealtimeSession,
+    createRealtimeSocket,
+} from './convoTransport.js';
 import { RealtimeEvents } from './realtimeEvents.js';
 import { ConvoMicrophone, ConvoSpeaker } from './convoMedia.js';
 import { ConvoHistory } from './convoHistory.js';
@@ -20,6 +24,7 @@ import { ConvoHistory } from './convoHistory.js';
  *     timer: ReturnType<typeof setTimeout> | null;
  *     retry: ReturnType<typeof setTimeout> | null;
  *     failures: number;
+ *     startedAt: number;
  *     refused: boolean;
  *     probe: RealtimeSession | null;
  *     created: RealtimeServerEvent | null;
@@ -45,6 +50,17 @@ const SESSION_TIMEOUT_MS = 20_000;
 // Close codes after which a dropped connection is replaced: going away,
 // abnormal closure, server error, service restart, try again later.
 const RECONNECT_CODES = new Set([1001, 1006, 1011, 1012, 1013]);
+/**
+ * Why a replacement session ended: one that hit the size limit is refused for
+ * good, anything else can be retried.
+ *
+ * @param {{ type: string; code?: number }} event
+ * @returns {string}
+ */
+const closeFailure = (event) =>
+    event.type === 'close' && event.code === CLOSE_MESSAGE_TOO_LARGE
+        ? 'message_too_large'
+        : 'session_closed';
 // Failures while reconnecting that are worth another attempt.
 const RETRYABLE_ERRORS = new Set([
     'session_closed',
@@ -56,7 +72,7 @@ const RETRYABLE_ERRORS = new Set([
     'rate_limit_exceeded',
     'internal_error',
 ]);
-// Ten attempts over about a minute, long enough for a server restart.
+// Bound setup retries so a persistent outage eventually closes the conversation.
 const RECONNECT_ATTEMPTS = 10;
 const RECONNECT_DELAY_MS = 500;
 const RECONNECT_MAX_DELAY_MS = 10_000;
@@ -76,6 +92,11 @@ const REPLACEMENT_SPREAD_MS = 3_000;
 // Acknowledgment timeout on a held replacement, whose socket may have died
 // with the connection it was meant to replace.
 const REPLACEMENT_ACK_MS = 3_000;
+/** @type {WeakMap<object, { token: string; attempts: number[] }>} */
+const handoverBudgets = new WeakMap();
+const MAX_HANDOVER_ATTEMPTS_PER_MINUTE = 20;
+const MAX_REPLACEMENT_ATTEMPTS = 3;
+const REPLACEMENT_BUDGET_MS = 30_000;
 const TRANSCRIPT_TIMEOUT_MS = 30_000;
 // Bounds for the idle check's bookkeeping.
 const MAX_OWED = 64;
@@ -257,6 +278,8 @@ export class Conversation extends RealtimeEvents {
     #connection = null;
     /** @type {{ type: 'close'; code: number; reason: string } | null} */
     #lastClose = null;
+    /** @type {string | undefined} */
+    #setupErrorCode;
     /**
      * @type {Set<{
      *     type: string;
@@ -393,7 +416,7 @@ export class Conversation extends RealtimeEvents {
         this.#state = 'connecting';
         this.#connection = (async () => {
             try {
-                await this.#open();
+                await this.#openInitial();
                 this.#state = 'connected';
                 this.emitRealtime({
                     type: 'ready',
@@ -415,6 +438,47 @@ export class Conversation extends RealtimeEvents {
         return this.#connection;
     }
 
+    /** @returns {Promise<void>} */
+    async #openInitial() {
+        const offlineUntil = Date.now() + OFFLINE_WAIT_MS;
+        for (let attempt = 0; attempt < RECONNECT_ATTEMPTS; attempt++) {
+            if (attempt) await this.#waitForRecovery(attempt - 1, offlineUntil);
+            if (this.#state === 'closed')
+                throw failure('session_closed', 'Conversation is closed');
+            try {
+                await this.#open();
+                return;
+            } catch (error) {
+                this.#endHandover();
+                this.#detach();
+                this.#resetTurnState();
+                this.#rejectPending(
+                    failure('connection_lost', 'Connection lost; reconnecting'),
+                );
+                if (
+                    this.#state === 'closed' ||
+                    !RETRYABLE_ERRORS.has(error?.code) ||
+                    attempt === RECONNECT_ATTEMPTS - 1
+                )
+                    throw error;
+            }
+        }
+    }
+
+    /**
+     * @param {number} attempt
+     * @param {number} offlineUntil
+     * @returns {Promise<void>}
+     */
+    async #waitForRecovery(attempt, offlineUntil) {
+        const delay = Math.min(
+            RECONNECT_DELAY_MS * 2 ** attempt,
+            RECONNECT_MAX_DELAY_MS,
+        );
+        await this.#pause(delay * (0.5 + Math.random()));
+        if (this.#state !== 'closed') await this.#whileOffline(offlineUntil);
+    }
+
     /**
      * Opens a socket, waits for the provider session and applies settings.
      *
@@ -428,6 +492,8 @@ export class Conversation extends RealtimeEvents {
      * @returns {Promise<void>}
      */
     async #open(reapply = false, prepared = null) {
+        this.#lastClose = null;
+        this.#setupErrorCode = undefined;
         if (prepared) {
             this.#session = prepared.session;
             this.#unsubscribe = this.#session.on('*', (event) =>
@@ -512,10 +578,13 @@ export class Conversation extends RealtimeEvents {
         this.#replayEvents.clear();
         this.#replayReported = false;
         this.#history.replayed([]);
-        const entries = this.#history.replay(
+        const { entries, omittedItems } = this.#history.replay(
             MAX_REPLAY_ITEMS,
             MAX_REPLAY_BYTES,
         );
+        // Routine trimming to the restore window, not a failure.
+        if (omittedItems)
+            this.emitRealtime({ type: 'context_trimmed', omittedItems });
         if (!entries.length) return;
         const events = entries.map(({ item }) => ({
             type: 'conversation.item.create',
@@ -587,14 +656,7 @@ export class Conversation extends RealtimeEvents {
                 return;
             }
             if (!ready) {
-                const delay = Math.min(
-                    RECONNECT_DELAY_MS * 2 ** attempt,
-                    RECONNECT_MAX_DELAY_MS,
-                );
-                // Jittered so clients dropped together don't return together.
-                await this.#pause(delay * (0.5 + Math.random()));
-                if (this.#state === 'closed') return;
-                await this.#whileOffline(offlineUntil);
+                await this.#waitForRecovery(attempt, offlineUntil);
                 if (this.#state === 'closed') return;
             }
             try {
@@ -749,10 +811,27 @@ export class Conversation extends RealtimeEvents {
      * @returns {Promise<void>}
      */
     async #openReplacement(handover) {
+        if (Date.now() - handover.startedAt >= REPLACEMENT_BUDGET_MS) {
+            handover.refused = true;
+            return;
+        }
+        let budget = handoverBudgets.get(this.#puter);
+        if (!budget || budget.token !== this.#puter.authToken) {
+            budget = { token: this.#puter.authToken, attempts: [] };
+            handoverBudgets.set(this.#puter, budget);
+        }
+        budget.attempts = budget.attempts.filter(
+            (time) => time > Date.now() - 60_000,
+        );
+        if (budget.attempts.length >= MAX_HANDOVER_ATTEMPTS_PER_MINUTE) {
+            handover.refused = true;
+            return;
+        }
+        budget.attempts.push(Date.now());
         let session;
         try {
             session = new RealtimeSession(
-                createRealtimeSocket(this.#puter, this.model),
+                createRealtimeSocket(this.#puter, this.model, 'handover'),
             );
         } catch {
             return;
@@ -770,7 +849,10 @@ export class Conversation extends RealtimeEvents {
             };
             const timer = setTimeout(
                 () => done({ code: 'operation_timeout' }),
-                SESSION_TIMEOUT_MS,
+                Math.min(
+                    SESSION_TIMEOUT_MS,
+                    REPLACEMENT_BUDGET_MS - (Date.now() - handover.startedAt),
+                ),
             );
             const off = session.on('*', (event) => {
                 if (event.type === 'session.created') done({ created: event });
@@ -779,7 +861,7 @@ export class Conversation extends RealtimeEvents {
                         code: String(event.error?.code ?? 'upstream_error'),
                     });
                 else if (event.type === 'close')
-                    done({ code: 'session_closed' });
+                    done({ code: closeFailure(event) });
             });
             handover.stopProbe = () => done({});
         });
@@ -799,7 +881,7 @@ export class Conversation extends RealtimeEvents {
                 handover.probe === session &&
                 ['close', 'error', RECONNECT_NOTICE].includes(event.type)
             )
-                this.#replacementFailed(handover, 'session_closed');
+                this.#replacementFailed(handover, closeFailure(event));
         });
         this.#scheduleHandover();
     }
@@ -816,7 +898,11 @@ export class Conversation extends RealtimeEvents {
         handover.created = null;
         handover.stopProbe = null;
         if (session && session.socket.readyState < 2) session.close();
-        if (code && !RETRYABLE_ERRORS.has(code)) {
+        if (
+            (code && !RETRYABLE_ERRORS.has(code)) ||
+            handover.failures >= MAX_REPLACEMENT_ATTEMPTS - 1 ||
+            Date.now() - handover.startedAt >= REPLACEMENT_BUDGET_MS
+        ) {
             handover.refused = true;
             return;
         }
@@ -1086,7 +1172,11 @@ export class Conversation extends RealtimeEvents {
      * @returns {Promise<void>}
      */
     interrupt(position) {
-        this.assertConnected();
+        try {
+            this.assertConnected();
+        } catch (error) {
+            return Promise.reject(error);
+        }
         return this.#interrupt(position, 'manual');
     }
 
@@ -1280,7 +1370,14 @@ export class Conversation extends RealtimeEvents {
                 code: event.code,
                 reason: event.reason,
             };
-            if (this.#state === 'connecting') {
+            // An event over the size limit would only arrive again, so it ends
+            // the conversation even mid-reconnect.
+            if (
+                this.#state === 'connecting' &&
+                (RECONNECT_CODES.has(event.code) ||
+                    (event.code !== 1000 &&
+                        RETRYABLE_ERRORS.has(this.#setupErrorCode)))
+            ) {
                 // `connect()` or the reconnect loop handles the failure.
                 this.#rejectPending(
                     failure(
@@ -1296,6 +1393,8 @@ export class Conversation extends RealtimeEvents {
             return;
         }
         if (event.type === 'error') {
+            if (this.#state === 'connecting')
+                this.#setupErrorCode = event.error?.code;
             const entry = this.#replayEvents.get(event.error?.event_id);
             if (entry) {
                 this.#replayEvents.delete(event.error.event_id);
@@ -1314,6 +1413,7 @@ export class Conversation extends RealtimeEvents {
                 timer: null,
                 retry: null,
                 failures: 0,
+                startedAt: Date.now(),
                 refused: false,
                 probe: null,
                 created: null,

src/puter-js/src/modules/ai/convo.test.js

@@ -33,14 +33,14 @@ const owner = () => ({
     env: 'nodejs',
 });
 const conversations = new Set();
-const make = (options = {}) => {
-    const c = new Conversation(owner(), options);
+const make = (options = {}, puter = owner()) => {
+    const c = new Conversation(puter, options);
     conversations.add(c);
     return c;
 };
 const socket = () => FakeWebSocket.instances.at(-1);
-const connected = async (options = {}) => {
-    const c = make(options);
+const connected = async (options = {}, puter = owner()) => {
+    const c = make(options, puter);
     const ready = c.connect();
     socket().deliver({ type: 'session.created', session: {} });
     await Promise.resolve();
@@ -61,6 +61,212 @@ afterEach(() => {
     vi.restoreAllMocks();
 });
 
+describe('interrupt readiness', () => {
+    it.each(['prepared', 'closed', 'reconnecting'])(
+        'rejects in %s state',
+        async (state) => {
+            const c = state === 'reconnecting' ? await connected() : make();
+            if (state === 'closed') c.close();
+            if (state === 'reconnecting') socket().close(1012, 'restart');
+            let result;
+            expect(() => {
+                result = c.interrupt();
+            }).not.toThrow();
+            await expect(result).rejects.toMatchObject({
+                code:
+                    state === 'closed' ? 'session_closed' : 'session_not_ready',
+            });
+        },
+    );
+});
+
+describe('initial recovery', () => {
+    it('resolves the original connect after a transient failure', async () => {
+        vi.useFakeTimers();
+        const c = make();
+        const ready = c.connect();
+        socket().close(1012, 'restart');
+        await vi.advanceTimersByTimeAsync(2_000);
+        expect(FakeWebSocket.instances).toHaveLength(2);
+        socket().deliver({ type: 'session.created', session: {} });
+        await Promise.resolve();
+        socket().deliver({ type: 'session.updated', session: {} });
+        await ready;
+        expect(c.state).toBe('connected');
+    });
+
+    it.each(['upstream_error', 'internal_error', 'rate_limit_exceeded'])(
+        'retries an initial %s refusal followed by policy close',
+        async (code) => {
+            fakeTime();
+            const c = make();
+            const ready = c.connect();
+            socket().deliver({ type: 'error', error: { code } });
+            socket().close(1008, code);
+            await vi.advanceTimersByTimeAsync(1_000);
+            expect(FakeWebSocket.instances).toHaveLength(2);
+            socket().deliver({ type: 'session.created', session: {} });
+            await Promise.resolve();
+            socket().deliver({ type: 'session.updated', session: {} });
+            await ready;
+            expect(c.state).toBe('connected');
+        },
+    );
+
+    it('stops at a terminal credential failure after a transient initial close', async () => {
+        fakeTime();
+        const c = make();
+        const closed = vi.fn();
+        c.on('close', closed);
+        const rejected = expect(c.connect()).rejects.toMatchObject({
+            code: 'invalid_api_key',
+        });
+        socket().close(1012, 'restart');
+        await vi.advanceTimersByTimeAsync(1_000);
+        socket().deliver({ type: 'error', error: { code: 'invalid_api_key' } });
+        await rejected;
+        await vi.advanceTimersByTimeAsync(60_000);
+        expect(c.state).toBe('closed');
+        expect(closed).toHaveBeenCalledOnce();
+        expect(closed.mock.calls[0][0].code).not.toBe(1012);
+        expect(FakeWebSocket.instances).toHaveLength(2);
+    });
+
+    it('cancels an initial retry when closed', async () => {
+        vi.useFakeTimers();
+        const c = make();
+        const result = expect(c.connect()).rejects.toMatchObject({
+            code: 'session_closed',
+        });
+        socket().close(1012, 'restart');
+        await Promise.resolve();
+        c.close();
+        await vi.runAllTimersAsync();
+        await result;
+        expect(FakeWebSocket.instances).toHaveLength(1);
+    });
+});
+
+describe('bounded overlapping handovers', () => {
+    it('hands over idle conversations as slots become available at the twenty-session cap', async () => {
+        fakeTime();
+        const puter = owner();
+        const active = [];
+        const originals = [];
+        for (let i = 0; i < 11; i++) {
+            active.push(await connected({}, puter));
+            originals.push(socket());
+        }
+        for (const ws of originals)
+            ws.deliver({ type: 'puter.reconnect', reason: 'restart' });
+        await vi.advanceTimersByTimeAsync(SPREAD);
+        const probes = FakeWebSocket.instances.slice(11);
+        expect(probes).toHaveLength(11);
+        expect(
+            probes.every(
+                (ws) =>
+                    new URL(ws.url).searchParams.get('purpose') === 'handover',
+            ),
+        ).toBe(true);
+        for (const ws of probes.slice(0, 9))
+            ws.deliver({ type: 'session.created', session: {} });
+        for (const ws of probes.slice(9))
+            ws.deliver({
+                type: 'error',
+                error: { code: 'rate_limit_exceeded' },
+            });
+        await vi.advanceTimersByTimeAsync(0);
+        for (const ws of probes.slice(0, 9))
+            ws.deliver({ type: 'session.updated', session: {} });
+        await vi.advanceTimersByTimeAsync(1_001);
+        const retries = FakeWebSocket.instances.slice(22);
+        expect(retries).toHaveLength(2);
+        for (const ws of retries)
+            ws.deliver({ type: 'session.created', session: {} });
+        await vi.advanceTimersByTimeAsync(0);
+        for (const ws of retries)
+            ws.deliver({ type: 'session.updated', session: {} });
+        await vi.advanceTimersByTimeAsync(0);
+        expect(active.every((c) => c.state === 'connected')).toBe(true);
+        expect(originals.every((ws) => ws.readyState === 3)).toBe(true);
+        expect(FakeWebSocket.instances).toHaveLength(24);
+    });
+
+    it('bounds a stalled probe by the elapsed budget while preserving the original', async () => {
+        const c = await connected();
+        fakeTime();
+        const original = socket();
+        original.deliver({ type: 'puter.reconnect', reason: 'restart' });
+        await vi.advanceTimersByTimeAsync(31_000);
+        expect(c.state).toBe('connected');
+        expect(original.readyState).toBe(1);
+        expect(
+            FakeWebSocket.instances.slice(1).every((ws) => ws.readyState === 3),
+        ).toBe(true);
+        const count = FakeWebSocket.instances.length;
+        await vi.advanceTimersByTimeAsync(60_000);
+        expect(FakeWebSocket.instances).toHaveLength(count);
+    });
+
+    it('keeps busy originals and reserves capacity for dropped connections', async () => {
+        vi.useFakeTimers();
+        const puter = owner();
+        const originals = [];
+        for (let i = 0; i < 11; i++) {
+            await connected({}, puter);
+            const ws = socket();
+            originals.push(ws);
+            ws.deliver({ type: 'response.created', response: { id: `r${i}` } });
+            ws.deliver({ type: 'puter.reconnect', reason: 'restart' });
+        }
+        for (let step = 0; step < 35; step++) {
+            await vi.advanceTimersByTimeAsync(1_000);
+            for (const probe of FakeWebSocket.instances.filter(
+                (ws) => !originals.includes(ws) && ws.readyState < 2,
+            )) {
+                probe.deliver({
+                    type: 'error',
+                    error: { code: 'rate_limit_exceeded' },
+                });
+            }
+        }
+        const probes = FakeWebSocket.instances.length - originals.length;
+        expect(probes).toBeLessThanOrEqual(20);
+        expect(originals.every((ws) => ws.readyState === 1)).toBe(true);
+        for (const ws of originals) ws.close(1012, 'restart');
+        await vi.advanceTimersByTimeAsync(2_000);
+        const recoveries = FakeWebSocket.instances.slice(11 + probes);
+        expect(recoveries).toHaveLength(11);
+        expect(
+            recoveries.every(
+                (ws) => !new URL(ws.url).searchParams.has('purpose'),
+            ),
+        ).toBe(true);
+        for (const ws of recoveries)
+            ws.deliver({ type: 'session.created', session: {} });
+        await Promise.resolve();
+        for (const ws of recoveries)
+            ws.deliver({ type: 'session.updated', session: {} });
+        await vi.advanceTimersByTimeAsync(0);
+        expect(FakeWebSocket.instances.length).toBeLessThanOrEqual(60);
+    });
+});
+
+describe('normal close policy', () => {
+    it('keeps a normal initial provider close terminal', async () => {
+        vi.useFakeTimers();
+        const c = make();
+        const result = expect(c.connect()).rejects.toMatchObject({
+            code: 'session_closed',
+        });
+        socket().close(1000, 'done');
+        await result;
+        await vi.advanceTimersByTimeAsync(60_000);
+        expect(FakeWebSocket.instances).toHaveLength(1);
+        expect(c.state).toBe('closed');
+    });
+});
+
 describe('conversation preparation', () => {
     it.each([
         null,
@@ -160,7 +366,7 @@ describe('Conversation lifecycle', () => {
         // Longer than the server's own 15-second setup budget.
         await vi.advanceTimersByTimeAsync(15_000);
         expect(c.state).toBe('connecting');
-        await vi.advanceTimersByTimeAsync(5_000);
+        await vi.advanceTimersByTimeAsync(300_000);
         await result;
         expect(c.state).toBe('closed');
         expect(vi.getTimerCount()).toBe(0);
@@ -437,6 +643,46 @@ describe('conversation helpers and limits', () => {
             expect.objectContaining({ code: 'queue_full' }),
         );
     });
+    it('keeps the conversation through server events larger than an upload', async () => {
+        const c = await connected();
+        const updates = [];
+        const items = [];
+        c.on('session.updated', (event) => updates.push(event));
+        c.on('*', (event) => {
+            if (event.type === 'conversation.item.done') items.push(event);
+        });
+        const instructions = 'x'.repeat(1024 * 1024);
+        socket().deliver({
+            type: 'session.updated',
+            session: { instructions },
+        });
+        socket().deliver({
+            type: 'conversation.item.done',
+            item: {
+                id: 'item_audio',
+                type: 'message',
+                role: 'assistant',
+                status: 'completed',
+                content: [
+                    {
+                        type: 'output_audio',
+                        audio: 'A'.repeat(3 * 1024 * 1024),
+                        transcript: 'Hello there',
+                    },
+                ],
+            },
+        });
+        expect(updates).toHaveLength(1);
+        expect(updates[0].session.instructions).toBe(instructions);
+        expect(items).toHaveLength(1);
+        expect(c.state).toBe('connected');
+        expect(() => c.sendText('hi')).not.toThrow();
+        // What the app sends keeps its own 64 KiB cap.
+        expect(() => c.send({ type: 'x', pad: 'x'.repeat(65536) })).toThrow(
+            expect.objectContaining({ code: 'input_too_large' }),
+        );
+    });
+
     it('rejects only the operation an error names', async () => {
         const c = await connected({ turnDetection: false });
         const update = c.configure({ instructions: 'changed' });
@@ -1249,6 +1495,23 @@ describe('restart notice', () => {
         expect(c.state).toBe('connected');
     });
 
+    it('stops opening replacements after one hits the size limit', async () => {
+        const c = await connected();
+        fakeTime();
+        const first = socket();
+        first.deliver(notice);
+        await vi.advanceTimersByTimeAsync(SPREAD);
+        socket().deliver({
+            type: 'session.created',
+            session: { instructions: 'x'.repeat(4 * 1024 * 1024) },
+        });
+        const sockets = FakeWebSocket.instances.length;
+        await vi.advanceTimersByTimeAsync(60_000);
+        expect(FakeWebSocket.instances).toHaveLength(sockets);
+        expect(c.state).toBe('connected');
+        expect(first.readyState).toBe(1);
+    });
+
     it('drops a held replacement that gets its own notice or an error', async () => {
         const c = await connected();
         fakeTime();
@@ -1441,6 +1704,73 @@ describe('restart notice', () => {
 });
 
 describe('context replay after a reconnect', () => {
+    it.each(['x'.repeat(49 * 1024), '😀'.repeat(13 * 1024)])(
+        'reports omitted context as trimming, not an error, and remains usable',
+        async (text) => {
+            const c = await connected();
+            fakeTime();
+            const log = track(c);
+            socket().deliver(userText('old', 'tiny'));
+            socket().deliver(userText('large', text));
+            socket().close(1006);
+            await answerReconnect();
+            expect(replayed()).toEqual([]);
+            expect(log.errors()).toEqual([]);
+            expect(
+                log.events.filter((e) => e.type === 'context_trimmed'),
+            ).toEqual([{ type: 'context_trimmed', omittedItems: 2 }]);
+            expect(c.state).toBe('connected');
+            expect(() => c.sendText('continue')).not.toThrow();
+        },
+    );
+
+    it('reports trimming before ready on each reconnect of a long conversation', async () => {
+        const c = await connected();
+        fakeTime();
+        const log = track(c);
+        for (let i = 1; i <= 50; i++)
+            socket().deliver(userText(`u${i}`, `m${i}`));
+        socket().close(1006);
+        await answerReconnect();
+        socket().close(1006);
+        await answerReconnect();
+        const types = log.types();
+        const trimmed = log.events.filter((e) => e.type === 'context_trimmed');
+        expect(trimmed).toHaveLength(2);
+        expect(trimmed[0]).toEqual({
+            type: 'context_trimmed',
+            omittedItems: 10,
+        });
+        expect(types.indexOf('context_trimmed')).toBeLessThan(
+            types.indexOf('ready'),
+        );
+        expect(log.errors()).toEqual([]);
+    });
+
+    it('keeps trimming and a provider refusal of the restored items distinct', async () => {
+        const c = await connected();
+        fakeTime();
+        const log = track(c);
+        for (let i = 1; i <= 41; i++)
+            socket().deliver(userText(`u${i}`, `m${i}`));
+        socket().close(1006);
+        await answerReconnect();
+        const [id] = socket()
+            .sent.filter((event) => event.type === 'conversation.item.create')
+            .map((event) => event.event_id);
+        socket().deliver({
+            type: 'error',
+            error: { code: 'invalid_value', message: 'Nope', event_id: id },
+        });
+        expect(log.events.filter((e) => e.type === 'context_trimmed')).toEqual([
+            { type: 'context_trimmed', omittedItems: 1 },
+        ]);
+        expect(log.errors()).toMatchObject([
+            { code: 'context_restore_failed' },
+        ]);
+        expect(c.state).toBe('connected');
+    });
+
     it('restores finished items in order, before ready, after a dropped connection', async () => {
         const c = await connected();
         fakeTime();
@@ -1908,6 +2238,98 @@ describe('reconnect retries', () => {
         expect(c.state).toBe('connected');
     });
 
+    it('reconnects after the server sheds load with 1013, keeping listeners', async () => {
+        const c = await connected();
+        fakeTime();
+        const text = [];
+        c.on('text', (event) => text.push(event.delta));
+        const closed = vi.fn();
+        c.on('close', closed);
+        socket().deliver({
+            type: 'error',
+            error: {
+                code: 'rate_limit_exceeded',
+                message: 'Too many pending usage events',
+            },
+        });
+        socket().close(1013, 'rate_limit_exceeded');
+        expect(c.state).toBe('connecting');
+        await answerReconnect();
+        expect(c.state).toBe('connected');
+        socket().deliver({
+            type: 'response.output_text.delta',
+            response_id: 'resp_1',
+            delta: 'Back',
+        });
+        expect(text).toEqual(['Back']);
+        expect(closed).not.toHaveBeenCalled();
+    });
+
+    it('retries a reconnect whose credential lookup failed on the server', async () => {
+        const c = await connected();
+        fakeTime();
+        const events = track(c);
+        socket().close(1006);
+        await vi.advanceTimersByTimeAsync(500);
+        socket().deliver({
+            type: 'error',
+            error: {
+                code: 'internal_error',
+                message: 'Could not verify credentials',
+            },
+        });
+        socket().close(1011, 'internal_error');
+        await vi.advanceTimersByTimeAsync(0);
+        expect(c.state).toBe('connecting');
+        const attempts = FakeWebSocket.instances.length;
+        await answerReconnect(1_000);
+        expect(FakeWebSocket.instances.length).toBe(attempts + 1);
+        expect(c.state).toBe('connected');
+        expect(events.types()).toContain('ready');
+    });
+
+    it('ends on an invalid credential during a reconnect', async () => {
+        const c = await connected();
+        fakeTime();
+        const closed = vi.fn();
+        c.on('close', closed);
+        socket().close(1006);
+        await vi.advanceTimersByTimeAsync(500);
+        const attempts = FakeWebSocket.instances.length;
+        socket().deliver({
+            type: 'error',
+            error: {
+                code: 'invalid_api_key',
+                message: 'Authentication failed',
+            },
+        });
+        socket().close(1008, 'invalid_api_key');
+        await vi.advanceTimersByTimeAsync(10_000);
+        expect(c.state).toBe('closed');
+        expect(closed).toHaveBeenCalledOnce();
+        expect(FakeWebSocket.instances.length).toBe(attempts);
+    });
+
+    it('ends on an event over the size limit during a reconnect, without more attempts', async () => {
+        const c = await connected();
+        fakeTime();
+        const closed = vi.fn();
+        c.on('close', closed);
+        socket().close(1006);
+        await vi.advanceTimersByTimeAsync(500);
+        const attempts = FakeWebSocket.instances.length;
+        socket().deliver({
+            type: 'session.created',
+            session: { instructions: 'x'.repeat(4 * 1024 * 1024) },
+        });
+        await vi.advanceTimersByTimeAsync(60_000);
+        expect(c.state).toBe('closed');
+        expect(closed).toHaveBeenCalledExactlyOnceWith(
+            expect.objectContaining({ type: 'close', code: 4009 }),
+        );
+        expect(FakeWebSocket.instances.length).toBe(attempts);
+    });
+
     describe('while the browser is offline', () => {
         let target;
         beforeEach(() => {
@@ -1977,3 +2399,104 @@ describe('reconnect retries', () => {
         });
     });
 });
+
+describe('microphone through a reconnect', () => {
+    const worklets = [];
+    const audioTrack = { enabled: true, readyState: 'live', stop: vi.fn() };
+    const getUserMedia = vi.fn(async () => ({
+        getTracks: () => [audioTrack],
+        getAudioTracks: () => [audioTrack],
+    }));
+    beforeEach(() => {
+        worklets.length = 0;
+        audioTrack.stop.mockClear();
+        getUserMedia.mockClear();
+        vi.stubGlobal('window', {});
+        vi.stubGlobal(
+            'AudioContext',
+            class {
+                state = 'running';
+                destination = {};
+                audioWorklet = { addModule: async () => {} };
+                resume = async () => {};
+                close = vi.fn(async () => {});
+                createMediaStreamSource() {
+                    return { connect() {}, disconnect() {} };
+                }
+            },
+        );
+        vi.stubGlobal(
+            'AudioWorkletNode',
+            class {
+                port = {
+                    onmessage: null,
+                    postMessage: vi.fn(),
+                    close: vi.fn(),
+                };
+                connect() {}
+                disconnect() {}
+                constructor() {
+                    worklets.push(this);
+                }
+            },
+        );
+        vi.stubGlobal('navigator', { mediaDevices: { getUserMedia } });
+        vi.spyOn(URL, 'createObjectURL').mockReturnValue('blob:test');
+        vi.spyOn(URL, 'revokeObjectURL').mockImplementation(() => {});
+    });
+    const appends = (s) =>
+        s.sent.filter((event) => event.type === 'input_audio_buffer.append');
+
+    it.each([1012, 1006])(
+        'keeps capturing when the socket closes (%i) before the conversation notices',
+        async (code) => {
+            const c = await connected();
+            await c.microphone.start();
+            fakeTime();
+            const events = track(c);
+            const port = worklets[0].port;
+            const first = socket();
+            port.onmessage({ data: { pcm: new Int16Array(480) } });
+            expect(appends(first)).toHaveLength(1);
+
+            // Closing, but no close event yet: the conversation still reads
+            // as connected.
+            first.readyState = 2;
+            port.onmessage({ data: { pcm: new Int16Array(480).fill(7) } });
+            expect(port.postMessage).toHaveBeenCalledTimes(2);
+            expect(audioTrack.stop).not.toHaveBeenCalled();
+            expect(port.close).not.toHaveBeenCalled();
+            expect(events.errors()).toEqual([]);
+
+            first.readyState = 1;
+            first.close(code);
+            port.onmessage({ data: { pcm: new Int16Array(480) } });
+            await answerReconnect();
+            expect(c.state).toBe('connected');
+            const replacement = socket();
+            expect(replacement).not.toBe(first);
+            expect(appends(replacement)).toHaveLength(0);
+
+            port.onmessage({ data: { pcm: new Int16Array(480) } });
+            expect(appends(replacement)).toHaveLength(1);
+            expect(getUserMedia).toHaveBeenCalledOnce();
+            expect(worklets).toHaveLength(1);
+            expect(events.errors()).toEqual([]);
+
+            c.close();
+            expect(audioTrack.stop).toHaveBeenCalledOnce();
+            expect(port.close).toHaveBeenCalledOnce();
+        },
+    );
+
+    it('releases capture once on a final close', async () => {
+        const c = await connected();
+        await c.microphone.start();
+        socket().close(1008, 'invalid_api_key');
+        expect(c.state).toBe('closed');
+        expect(audioTrack.stop).toHaveBeenCalledOnce();
+        expect(worklets[0].port.close).toHaveBeenCalledOnce();
+        c.close();
+        expect(audioTrack.stop).toHaveBeenCalledOnce();
+    });
+});

src/puter-js/src/modules/ai/convoHistory.js

@@ -238,7 +238,7 @@ export class ConvoHistory {
      *
      * @param {number} maxItems
      * @param {number} maxBytes
-     * @returns {ReplayEntry[]}
+     * @returns {{ entries: ReplayEntry[]; omittedItems: number }}
      */
     replay(maxItems, maxBytes) {
         /** @type {ReplayEntry[]} */
@@ -264,10 +264,17 @@ export class ConvoHistory {
                 .filter(({ item }) => item.type === 'function_call')
                 .map(({ item }) => item.call_id),
         );
-        return entries.filter(
+        const filtered = entries.filter(
             ({ item }) =>
                 item.type !== 'function_call_output' || calls.has(item.call_id),
         );
+        const restorable = this.#records.filter((record) =>
+            this.#replayItem(record),
+        ).length;
+        return {
+            entries: filtered,
+            omittedItems: restorable - filtered.length,
+        };
     }
 
     /**

src/puter-js/src/modules/ai/convoHistory.test.js

@@ -6,7 +6,9 @@ const user = (id, content) => ({
     item: { id, type: 'message', role: 'user', status: 'completed', content },
 });
 const texts = (history) =>
-    history.replay(40, 48 * 1024).map(({ item }) => item.content[0].text);
+    history
+        .replay(40, 48 * 1024)
+        .entries.map(({ item }) => item.content[0].text);
 
 describe('ConvoHistory', () => {
     it('cuts text without word breaks at the played share', () => {
@@ -60,7 +62,7 @@ describe('ConvoHistory', () => {
             history.observe(
                 user(`u${i}`, [{ type: 'input_text', text: `${i}` }]),
             );
-        expect(history.replay(100, Infinity)).toHaveLength(80);
+        expect(history.replay(100, Infinity).entries).toHaveLength(80);
         expect(texts(history).at(-1)).toBe('99');
     });
 
@@ -74,6 +76,25 @@ describe('ConvoHistory', () => {
         expect(texts(history)).toEqual(['new']);
     });
 
+    it.each(['x'.repeat(49 * 1024), '😀'.repeat(13 * 1024)])(
+        'reports an oversized newest item without truncating it',
+        (text) => {
+            const history = new ConvoHistory(() => false);
+            history.observe(
+                user('old', [{ type: 'input_text', text: 'tiny' }]),
+            );
+            history.observe(user('large', [{ type: 'input_text', text }]));
+            expect(history.replay(40, 48 * 1024)).toEqual({
+                entries: [],
+                omittedItems: 2,
+            });
+            expect(
+                history.replay(40, Infinity).entries.at(-1).item.content[0]
+                    .text,
+            ).toBe(text);
+        },
+    );
+
     it('waits on every unanswered call since the last user message', () => {
         const history = new ConvoHistory(() => false);
         const call = (id, status = 'completed') =>
@@ -114,7 +135,7 @@ describe('ConvoHistory', () => {
     it('reports the new session copies of replayed items until they are done', () => {
         const history = new ConvoHistory(() => false);
         history.observe(user('old', [{ type: 'input_text', text: 'hi' }]));
-        history.replayed(history.replay(40, 48 * 1024));
+        history.replayed(history.replay(40, 48 * 1024).entries);
         const copy = user('new', [{ type: 'input_text', text: 'hi' }]);
         expect(history.observe(copy)).toBe(true);
         expect(

src/puter-js/src/modules/ai/convoMedia.js

@@ -7,6 +7,12 @@ const SAMPLE_RATE = 24000;
 const MEDIA_TIMEOUT_MS = 10_000;
 // Replies arrive faster than they play; this bounds what may be scheduled.
 const MAX_SCHEDULED_SECONDS = 300;
+// Transport refusals that cost one microphone chunk, not the capture.
+const DROPPED_CHUNK_ERRORS = new Set([
+    'queue_full',
+    'session_closed',
+    'session_not_ready',
+]);
 
 /**
  * @template T
@@ -232,8 +238,10 @@ export class ConvoMicrophone {
             try {
                 this.#convo.appendAudio(data.pcm);
             } catch (error) {
-                // A congested socket drops audio instead of ending capture.
-                if (error?.code === 'queue_full') return;
+                // A congested socket, or one closing before the conversation
+                // knows it, drops the chunk instead of ending capture: a
+                // reconnect resumes it and a final close stops it.
+                if (DROPPED_CHUNK_ERRORS.has(error?.code)) return;
                 this.stop();
                 this.#convo.reportMediaError(error);
             }

src/puter-js/src/modules/ai/convoMedia.test.js

@@ -161,36 +161,101 @@ it('reports browser playback failures with SDK error codes', async () => {
         message: 'Could not start playback',
     });
 });
-it('drops chunks under backpressure or while reconnecting, and stops on other errors', async () => {
-    const c = makeConvo();
+/** A started microphone over fake browser media. */
+const startedMic = async (c = makeConvo()) => {
     const audioTrack = track();
-    vi.stubGlobal('navigator', {
-        mediaDevices: {
-            getUserMedia: async () => ({ getTracks: () => [audioTrack] }),
-        },
-    });
+    const getUserMedia = vi.fn(async () => ({
+        getTracks: () => [audioTrack],
+        getAudioTracks: () => [audioTrack],
+    }));
+    vi.stubGlobal('navigator', { mediaDevices: { getUserMedia } });
     const mic = new ConvoMicrophone(c);
     helpers.push(mic);
     await mic.start();
-    const port = FakeWorklet.instances[0].port;
-    const pcm = new Int16Array(480);
-    c.appendAudio.mockImplementationOnce(() => {
-        throw { code: 'queue_full', message: 'full' };
-    });
-    port.onmessage({ data: { pcm } });
+    const port = FakeWorklet.instances.at(-1).port;
+    const context = FakeContext.instances.at(-1);
+    return { c, mic, port, context, audioTrack, getUserMedia };
+};
+const pcm = new Int16Array(480);
+
+it('drops a chunk the transport refuses and keeps capturing', async () => {
+    const { c, port, context, audioTrack } = await startedMic();
+    for (const code of ['queue_full', 'session_closed', 'session_not_ready']) {
+        c.appendAudio.mockImplementationOnce(() => {
+            throw { code, message: code };
+        });
+        port.onmessage({ data: { pcm } });
+    }
+    expect(port.postMessage).toHaveBeenCalledTimes(3);
     expect(audioTrack.stop).not.toHaveBeenCalled();
+    expect(port.close).not.toHaveBeenCalled();
+    expect(context.close).not.toHaveBeenCalled();
+    expect(c.reportMediaError).not.toHaveBeenCalled();
+
+    // Later chunks go out as usual.
+    port.onmessage({ data: { pcm } });
+    expect(c.appendAudio).toHaveBeenCalledTimes(4);
+    expect(c.appendAudio).toHaveBeenLastCalledWith(pcm);
+});
+
+it('drops chunks while reconnecting or muted, without sending them later', async () => {
+    const { c, mic, port, audioTrack } = await startedMic();
     c.state = 'connecting';
     port.onmessage({ data: { pcm } });
-    expect(c.appendAudio).toHaveBeenCalledOnce();
-    expect(port.postMessage).toHaveBeenCalledTimes(2);
+    mic.mute();
     c.state = 'connected';
+    port.onmessage({ data: { pcm } });
+    expect(c.appendAudio).not.toHaveBeenCalled();
+    expect(port.postMessage).toHaveBeenCalledTimes(2);
+    mic.unmute();
+    port.onmessage({ data: { pcm } });
+    expect(c.appendAudio).toHaveBeenCalledOnce();
+    expect(audioTrack.stop).not.toHaveBeenCalled();
+});
+
+it('ignores callbacks from a stopped capture, including one stopped while reconnecting', async () => {
+    const { c, mic, port, audioTrack } = await startedMic();
+    const onmessage = port.onmessage;
+    c.state = 'connecting';
+    mic.stop();
+    c.state = 'connected';
+    onmessage({ data: { pcm } });
+    expect(c.appendAudio).not.toHaveBeenCalled();
+    expect(port.postMessage).not.toHaveBeenCalled();
+    expect(audioTrack.stop).toHaveBeenCalledOnce();
+    expect(c.reportMediaError).not.toHaveBeenCalled();
+});
+
+it('releases capture once on a genuine error, and ignores chunks after a final close', async () => {
+    const { c, mic, port, context, audioTrack } = await startedMic();
     c.appendAudio.mockImplementationOnce(() => {
-        throw { code: 'session_closed', message: 'closed' };
+        throw { code: 'invalid_argument', message: 'bad chunk' };
     });
     port.onmessage({ data: { pcm } });
-    expect(audioTrack.stop).toHaveBeenCalled();
-    expect(c.reportMediaError).toHaveBeenCalledWith(
-        expect.objectContaining({ code: 'session_closed' }),
+    mic.stop();
+    expect(audioTrack.stop).toHaveBeenCalledOnce();
+    expect(port.close).toHaveBeenCalledOnce();
+    expect(context.close).toHaveBeenCalledOnce();
+    expect(c.reportMediaError).toHaveBeenCalledExactlyOnceWith(
+        expect.objectContaining({ code: 'invalid_argument' }),
+    );
+
+    const next = await startedMic();
+    const onmessage = next.port.onmessage;
+    next.c.state = 'closed';
+    onmessage({ data: { pcm } });
+    expect(next.c.appendAudio).not.toHaveBeenCalled();
+    expect(next.c.reportMediaError).not.toHaveBeenCalled();
+});
+
+it('releases capture once when the processor fails', async () => {
+    const { c, port, context, audioTrack } = await startedMic();
+    FakeWorklet.instances.at(-1).onprocessorerror();
+    expect(audioTrack.stop).toHaveBeenCalledOnce();
+    expect(port.close).toHaveBeenCalledOnce();
+    expect(context.close).toHaveBeenCalledOnce();
+    expect(c.reportMediaError).toHaveBeenCalledExactlyOnceWith(
+        expect.objectContaining({ code: 'media_error' }),
     );
 });
 it('captures at the device rate', async () => {

src/puter-js/src/modules/ai/convoTransport.js

@@ -4,10 +4,33 @@ import { RealtimeEvents } from './realtimeEvents.js';
 
 const REALTIME_PATH = '/puterai/openai/v1/realtime';
 const encoder = new TextEncoder();
+// The relay's cap on provider messages, which can carry whole items. What the
+// SDK sends is capped separately, and much lower.
+const MAX_SERVER_MESSAGE_BYTES = 4 * 1024 * 1024;
+/**
+ * Close code for a server event over the limit; browsers only accept 1000 and
+ * 3000-4999 from the client.
+ *
+ * @internal
+ */
+export const CLOSE_MESSAGE_TOO_LARGE = 4009;
+
+/**
+ * Whether `data` encodes to more than `limit` UTF-8 bytes. A UTF-16 code unit
+ * encodes to at most three bytes, so only a long string is encoded to check.
+ *
+ * @param {string} data
+ * @param {number} limit
+ * @returns {boolean}
+ */
+const exceedsBytes = (data, limit) =>
+    data.length > limit ||
+    (data.length * 3 > limit && encoder.encode(data).byteLength > limit);
 
 /**
  * One live realtime session. Events in both directions are OpenAI Realtime API
  * events, unchanged.
+ *
  * @internal
  */
 export class RealtimeSession extends RealtimeEvents {
@@ -23,12 +46,8 @@ export class RealtimeSession extends RealtimeEvents {
             try {
                 const data =
                     typeof msg.data === 'string' ? msg.data : String(msg.data);
-                if (
-                    data.length > 65536 ||
-                    encoder.encode(data).byteLength > 65536
-                ) {
-                    // Browsers only accept 1000 and 3000-4999 here.
-                    socket.close(4009, 'message too large');
+                if (exceedsBytes(data, MAX_SERVER_MESSAGE_BYTES)) {
+                    socket.close(CLOSE_MESSAGE_TOO_LARGE, 'message too large');
                     return;
                 }
                 event = JSON.parse(data);
@@ -60,13 +79,15 @@ export class RealtimeSession extends RealtimeEvents {
 /**
  * @param {import('../../index.js').Puter} puter
  * @param {string} [model]
+ * @param {'handover'} [purpose]
  * @returns {WebSocket}
  * @internal
  */
-export function createRealtimeSocket(puter, model) {
+export function createRealtimeSocket(puter, model, purpose) {
     const url = new URL(REALTIME_PATH, puter.APIOrigin);
     url.protocol = url.protocol === 'https:' ? 'wss:' : 'ws:';
     if (model) url.searchParams.set('model', model);
+    if (purpose) url.searchParams.set('purpose', purpose);
     return new WebSocket(url.toString(), [
         'realtime',
         `openai-insecure-api-key.${puter.authToken}`,

src/puter-js/src/modules/ai/convoTransport.test.js

@@ -13,11 +13,33 @@ const fakeSocket = () => {
         close: vi.fn(),
         /** @param {object} event */
         deliver (event) {
-            target.dispatchEvent(new MessageEvent('message', { data: JSON.stringify(event) }));
+            this.deliverRaw(JSON.stringify(event));
+        },
+        /** @param {string} data */
+        deliverRaw (data) {
+            target.dispatchEvent(new MessageEvent('message', { data }));
         },
     });
 };
 
+const LIMIT = 4 * 1024 * 1024;
+/** A serialized event of exactly `bytes` UTF-8 bytes, padded with `fill`. */
+const eventOfBytes = (bytes, fill = 'x') => {
+    const shell = JSON.stringify({ type: 'session.updated', pad: '' });
+    const fillBytes = new TextEncoder().encode(fill).byteLength;
+    const pad = fill.repeat(Math.floor((bytes - shell.length) / fillBytes));
+    const json = JSON.stringify({ type: 'session.updated', pad });
+    const short = bytes - new TextEncoder().encode(json).byteLength;
+    return JSON.stringify({ type: 'session.updated', pad: pad + 'x'.repeat(short) });
+};
+const listen = (session) => {
+    const typed = vi.fn();
+    const all = vi.fn();
+    session.on('session.updated', typed);
+    session.on('*', all);
+    return { typed, all };
+};
+
 describe('RealtimeSession', () => {
     it('dispatches server events by type and to "*"', () => {
         const socket = fakeSocket();
@@ -44,6 +66,64 @@ describe('RealtimeSession', () => {
         expect(handler).not.toHaveBeenCalled();
     });
 
+    it('dispatches a valid event larger than an upload once and stays open', () => {
+        const socket = fakeSocket();
+        const { typed, all } = listen(new RealtimeSession(/** @type {any} */ (socket)));
+        const data = eventOfBytes(256 * 1024);
+        socket.deliverRaw(data);
+        expect(typed).toHaveBeenCalledExactlyOnceWith(JSON.parse(data));
+        expect(all).toHaveBeenCalledOnce();
+        expect(socket.close).not.toHaveBeenCalled();
+    });
+
+    it('accepts an event of exactly 4 MiB and refuses one byte more with 4009', () => {
+        const socket = fakeSocket();
+        const { typed } = listen(new RealtimeSession(/** @type {any} */ (socket)));
+        const exact = eventOfBytes(LIMIT);
+        expect(new TextEncoder().encode(exact).byteLength).toBe(LIMIT);
+        socket.deliverRaw(exact);
+        expect(typed).toHaveBeenCalledOnce();
+        expect(socket.close).not.toHaveBeenCalled();
+
+        socket.deliverRaw(eventOfBytes(LIMIT + 1));
+        expect(typed).toHaveBeenCalledOnce();
+        expect(socket.close).toHaveBeenCalledExactlyOnceWith(4009, 'message too large');
+    });
+
+    it('accepts a multibyte event of exactly 4 MiB', () => {
+        const socket = fakeSocket();
+        const { typed } = listen(new RealtimeSession(/** @type {any} */ (socket)));
+        const data = eventOfBytes(LIMIT, 'é');
+        expect(new TextEncoder().encode(data).byteLength).toBe(LIMIT);
+        expect(data.length * 3).toBeGreaterThan(LIMIT);
+        socket.deliverRaw(data);
+        expect(typed).toHaveBeenCalledOnce();
+        expect(socket.close).not.toHaveBeenCalled();
+    });
+
+    it('counts encoded bytes, not characters', () => {
+        const socket = fakeSocket();
+        const { typed } = listen(new RealtimeSession(/** @type {any} */ (socket)));
+        // Two bytes per character: under the limit in characters, over it in bytes.
+        const data = eventOfBytes(LIMIT + 2, 'é');
+        expect(data.length).toBeLessThan(LIMIT);
+        socket.deliverRaw(data);
+        expect(typed).not.toHaveBeenCalled();
+        expect(socket.close).toHaveBeenCalledExactlyOnceWith(4009, 'message too large');
+    });
+
+    it('ignores malformed JSON and events without a usable type', () => {
+        const socket = fakeSocket();
+        const { all } = listen(new RealtimeSession(/** @type {any} */ (socket)));
+        socket.deliverRaw('{"type":');
+        socket.deliverRaw('[{"type":"session.updated"}]');
+        socket.deliver({ type: '' });
+        socket.deliver({ type: 'x'.repeat(129) });
+        socket.deliver({ type: 42 });
+        expect(all).not.toHaveBeenCalled();
+        expect(socket.close).not.toHaveBeenCalled();
+    });
+
     it('emits close with code and reason', () => {
         const socket = fakeSocket();
         const session = new RealtimeSession(/** @type {any} */ (socket));

src/puter-js/src/modules/ai/types.js

@@ -115,6 +115,14 @@
  * @property {boolean} [streamToolInput] Streaming only: emit incremental `tool_use_start` /
  * `tool_input_delta` chunks as a tool call's arguments are generated, instead of a single `tool_use`
  * chunk once the call completes.
+ * @property {string} [prompt_cache_key] OpenAI models: which prompt cache the request reads from and
+ * writes to. Defaults to one cache per app and user.
+ * @property {'in_memory' | '24h'} [prompt_cache_retention] OpenAI models before GPT-5.6: how long a
+ * cache entry may live. `'24h'` is the default and the only value GPT-5.5 and later accept.
+ * @property {{ mode?: 'implicit' | 'explicit', ttl?: '30m' | '12h' }} [prompt_cache_options] OpenAI
+ * GPT-5.6 and later: `ttl` is the minimum lifetime of every cache entry the request writes. A `'12h'`
+ * entry costs twice as much to write as the default `'30m'` one and is served through the Responses
+ * API. `mode: 'explicit'` only writes at the `prompt_cache_breakpoint` markers in your messages.
  */
 
 /**
@@ -132,14 +140,16 @@
  * @property {number} inputTokens
  * @property {number} outputTokens
  * @property {number} [cacheReadTokens]
- * @property {number} [cacheWrite5mTokens]
- * @property {number} [cacheWrite1hTokens]
+ * @property {number} [cacheWrite5mTokens] Tokens written to the cache with a 5 minute lifetime (Claude, Moonshot).
+ * @property {number} [cacheWrite30mTokens] Tokens written with a 30 minute lifetime (OpenAI's default).
+ * @property {number} [cacheWrite1hTokens] Tokens written with a 1 hour lifetime (Claude, Moonshot).
+ * @property {number} [cacheWrite12hTokens] Tokens written with a 12 hour lifetime (OpenAI, `prompt_cache_options.ttl: '12h'`).
  * @property {number} [reasoningTokens]
  * @property {number} [webSearchRequests]
  * @property {number} [webFetchRequests]
  * @property {'fast' | 'standard'} [speed]
  * @property {string} [serviceTier]
- * @property {Array<{ type: string, model?: string, inputTokens: number, outputTokens: number, cacheReadTokens?: number, cacheWrite5mTokens?: number, cacheWrite1hTokens?: number }>} [iterations]
+ * @property {Array<{ type: string, model?: string, inputTokens: number, outputTokens: number, cacheReadTokens?: number, cacheWrite5mTokens?: number, cacheWrite30mTokens?: number, cacheWrite1hTokens?: number, cacheWrite12hTokens?: number }>} [iterations]
  * Per-pass breakdown when the upstream ran several passes (compaction, an advisor sub-call).
  */
 
@@ -634,4 +644,4 @@ export {};
  * top level.
  * @typedef {{ type: 'error'; error: { code?: string; message?: string } & Record<string, unknown>; code?: string; message?: string }} ConvoErrorEvent */
 /** Native provider events retain their provider-owned fields.
- * @typedef {Record<string, RealtimeServerEvent> & { text: ConvoTextEvent; audio: ConvoAudioEvent; transcript: ConvoTranscriptEvent; interrupted: ConvoInterruptedEvent; 'turn.done': ConvoTurnDoneEvent; error: ConvoErrorEvent; ready: { type: 'ready'; model: string; provider: 'openai'; reconnected?: boolean }; reconnecting: { type: 'reconnecting'; code: number; reason: string }; close: { type: 'close'; code: number; reason: string } }} ConvoEventMap */
+ * @typedef {Record<string, RealtimeServerEvent> & { text: ConvoTextEvent; audio: ConvoAudioEvent; transcript: ConvoTranscriptEvent; interrupted: ConvoInterruptedEvent; 'turn.done': ConvoTurnDoneEvent; error: ConvoErrorEvent; ready: { type: 'ready'; model: string; provider: 'openai'; reconnected?: boolean }; reconnecting: { type: 'reconnecting'; code: number; reason: string }; context_trimmed: { type: 'context_trimmed'; omittedItems: number }; close: { type: 'close'; code: number; reason: string } }} ConvoEventMap */

src/puter-js/tests/api/realtime/convo.test.ts

@@ -33,6 +33,7 @@ describe('convo built SDK and browser media', () => {
         received: { type: string; item?: unknown }[];
     }[] = [];
     let ids = 0;
+    let upstreamRefusals = 0;
     beforeAll(async () => {
         upstream = new WebSocketServer({ port: 0 });
         upstream.on('connection', (socket) => {
@@ -41,6 +42,11 @@ describe('convo built SDK and browser media', () => {
                 received: [] as { type: string; item?: unknown }[],
             };
             connections.push(connection);
+            if (upstreamRefusals > 0) {
+                upstreamRefusals--;
+                socket.close(1012, 'restart');
+                return;
+            }
             socket.send(
                 JSON.stringify({ type: 'session.created', session: {} }),
             );
@@ -123,6 +129,38 @@ describe('convo built SDK and browser media', () => {
                             },
                         }),
                     );
+                // Provider events far larger than anything a client sends.
+                if (event.type === 'test.large') {
+                    send({
+                        type: 'session.updated',
+                        session: { instructions: 'x'.repeat(1536 * 1024) },
+                    });
+                    const item = {
+                        id: `item_${++ids}`,
+                        object: 'realtime.item',
+                        type: 'message',
+                        role: 'assistant',
+                    };
+                    send({
+                        type: 'conversation.item.added',
+                        item: { ...item, status: 'in_progress', content: [] },
+                    });
+                    const done = {
+                        ...item,
+                        status: 'completed',
+                        content: [
+                            {
+                                type: 'output_audio',
+                                audio: Buffer.alloc(1536 * 1024).toString(
+                                    'base64',
+                                ),
+                                transcript: 'Hello there',
+                            },
+                        ],
+                    };
+                    send({ type: 'conversation.item.done', item: done });
+                    send({ type: 'conversation.item.retrieved', item: done });
+                }
                 if (event.type === 'conversation.item.truncate')
                     socket.send(
                         JSON.stringify({
@@ -179,6 +217,22 @@ describe('convo built SDK and browser media', () => {
         await new Promise<void>((resolve) => upstream?.close(() => resolve()));
     }, 60_000);
 
+    it('resolves the original built SDK connect after an initial provider restart', async () => {
+        upstreamRefusals = 1;
+        const before = connections.length;
+        const conversation = await puter.ai.convo({ output: ['text'] });
+        try {
+            const ready = conversation.connect();
+            expect(conversation.connect()).toBe(ready);
+            await ready;
+            expect(conversation.state).toBe('connected');
+            expect(connections.length - before).toBe(2);
+        } finally {
+            upstreamRefusals = 0;
+            conversation.close();
+        }
+    });
+
     it('prepares, configures, sends, interrupts and truncates using the built SDK', async () => {
         const conversation = await puter.ai.convo({
             output: ['text'],
@@ -422,6 +476,93 @@ describe('convo built SDK and browser media', () => {
         }
     });
 
+    it('reconnects through a credential lookup that fails once', async () => {
+        const dropping = loadNodePuter(
+            { ...manifest, apiOrigin: proxyOrigin },
+            env.users.user.token,
+        );
+        const conversation = await dropping.ai.convo({ output: ['text'] });
+        const log = watch(conversation);
+        const auth = vi.spyOn(env.server.services.auth, 'authenticate');
+        const warn = vi.spyOn(console, 'warn');
+        try {
+            await conversation.connect();
+            // Every lookup fails, the SDK's own socket.io connection included,
+            // until the relay has refused a reconnect attempt on one.
+            auth.mockRejectedValue(new Error('auth store unavailable'));
+            for (const socket of proxied) socket.destroy();
+            await vi.waitFor(
+                () =>
+                    expect(warn).toHaveBeenCalledWith(
+                        '[realtime] credential lookup failed',
+                        expect.objectContaining({
+                            message: 'auth store unavailable',
+                        }),
+                    ),
+                { timeout: 10_000 },
+            );
+            auth.mockRestore();
+            await log.until(() =>
+                log.events.some(
+                    (event) => event.type === 'ready' && event.reconnected,
+                ),
+            );
+            expect(log.count('reconnecting')).toBe(1);
+            conversation.sendText('Still there?');
+            await log.until(() => log.count('turn.done') === 1);
+            expect(log.count('close')).toBe(0);
+        } finally {
+            auth.mockRestore();
+            warn.mockRestore();
+            conversation.close();
+            closeNodePuter(dropping);
+        }
+    });
+
+    it('delivers provider events larger than an upload and restores them after a drop', async () => {
+        const dropping = loadNodePuter(
+            { ...manifest, apiOrigin: proxyOrigin },
+            env.users.user.token,
+        );
+        const conversation = await dropping.ai.convo({ output: ['text'] });
+        const log = watch(conversation);
+        try {
+            await conversation.connect();
+            conversation.send({ type: 'test.large' });
+            await log.until(
+                () => log.count('conversation.item.retrieved') === 1,
+            );
+            expect(log.count('conversation.item.done')).toBe(1);
+            const update = log.events.find(
+                (event) =>
+                    event.type === 'session.updated' &&
+                    typeof event.session?.instructions === 'string' &&
+                    event.session.instructions.length === 1536 * 1024,
+            );
+            expect(update).toBeDefined();
+            expect(conversation.state).toBe('connected');
+
+            for (const socket of proxied) socket.destroy();
+            await log.until(() =>
+                log.events.some(
+                    (event) => event.type === 'ready' && event.reconnected,
+                ),
+            );
+            await vi.waitFor(() =>
+                expect(restored(connections.at(-1)!)).toContainEqual({
+                    type: 'message',
+                    role: 'assistant',
+                    content: [{ type: 'output_text', text: 'Hello there' }],
+                }),
+            );
+            expect(log.count('reconnecting')).toBe(1);
+            expect(log.count('close')).toBe(0);
+        } finally {
+            conversation.close();
+            closeNodePuter(dropping);
+        }
+    });
+
     it('moves to a new session when a restart is announced, restoring context', async () => {
         const conversation = await puter.ai.convo({ output: ['text'] });
         const log = watch(conversation);
@@ -494,6 +635,165 @@ describe('convo built SDK and browser media', () => {
         }
     });
 
+    it('keeps real microphone capture through a socket that closes before the conversation notices', async () => {
+        browser ??= await chromium.launch({
+            args: [
+                '--use-fake-ui-for-media-stream',
+                '--use-fake-device-for-media-stream',
+                '--autoplay-policy=no-user-gesture-required',
+                '--disable-features=LocalNetworkAccessChecks,PrivateNetworkAccessChecks,BlockInsecurePrivateNetworkRequests',
+            ],
+        });
+        const page = await browser.newPage();
+        try {
+            await page.route('**/__convo_mic_test__', (route) =>
+                route.fulfill({
+                    contentType: 'text/html',
+                    body: '<!doctype html><title>Microphone reconnect test</title>',
+                }),
+            );
+            await page.goto(`${env.apiOrigin}/__convo_mic_test__`);
+            // Through the proxy, so the test can drop the connection.
+            await page.evaluate(
+                ({ origin, apiOrigin }) => {
+                    Object.assign(globalThis, {
+                        PUTER_ORIGIN: origin,
+                        PUTER_API_ORIGIN: apiOrigin,
+                    });
+                },
+                { origin: env.origin, apiOrigin: proxyOrigin },
+            );
+            await page.addScriptTag({
+                content: readFileSync(
+                    new URL('../../../dist/puter.js', import.meta.url),
+                    'utf8',
+                ),
+            });
+            await page.evaluate(async (token) => {
+                const g = globalThis as typeof globalThis & {
+                    puter: PuterSDK;
+                    test: Record<string, unknown>;
+                };
+                g.puter.setAuthToken(token);
+                const sockets: WebSocket[] = [];
+                // `globalThis`: this file's own `WebSocket` is the `ws` import.
+                const Native = globalThis.WebSocket;
+                g.WebSocket = class extends Native {
+                    constructor(...args: ConstructorParameters<typeof Native>) {
+                        super(...args);
+                        sockets.push(this);
+                    }
+                };
+                const tracks: MediaStreamTrack[] = [];
+                let mediaCalls = 0;
+                const capture = navigator.mediaDevices.getUserMedia.bind(
+                    navigator.mediaDevices,
+                );
+                navigator.mediaDevices.getUserMedia = async (constraints) => {
+                    mediaCalls++;
+                    const stream = await capture(constraints);
+                    tracks.push(...stream.getTracks());
+                    return stream;
+                };
+                const c = await g.puter.ai.convo({ output: ['text'] });
+                const events: string[] = [];
+                c.on('*', (event) => events.push(event.type));
+                await c.connect();
+                await c.microphone.start();
+                g.test = {
+                    c,
+                    events,
+                    tracks,
+                    sockets,
+                    mediaCalls: () => mediaCalls,
+                };
+            }, env.users.user.token);
+            const before = connections.at(-1)!;
+            const appendsTo = (connection: (typeof connections)[number]) =>
+                connection.received.filter(
+                    (event) => event.type === 'input_audio_buffer.append',
+                ).length;
+            await vi.waitFor(() =>
+                expect(appendsTo(before)).toBeGreaterThan(0),
+            );
+
+            // The socket reads as closing while the conversation still reads
+            // connected, until the connection drops below. Chunks that arrive
+            // meanwhile are refused by the transport.
+            const gap = await page.evaluate(async () => {
+                const t = (globalThis as unknown as { test: any }).test;
+                const socket = t.sockets.at(-1) as WebSocket;
+                Object.defineProperty(socket, 'readyState', {
+                    configurable: true,
+                    get: () => 2,
+                });
+                let refused = 0;
+                const appendAudio = t.c.appendAudio.bind(t.c);
+                t.c.appendAudio = (pcm: Int16Array) => {
+                    try {
+                        appendAudio(pcm);
+                    } catch (error) {
+                        refused++;
+                        throw error;
+                    }
+                };
+                await new Promise((resolve) => setTimeout(resolve, 300));
+                return {
+                    refused,
+                    state: t.c.state,
+                    live: t.tracks.every(
+                        (track: MediaStreamTrack) =>
+                            track.readyState === 'live',
+                    ),
+                    events: t.events,
+                };
+            });
+            expect(gap.refused).toBeGreaterThan(0);
+            expect(gap.state).toBe('connected');
+            expect(gap.live).toBe(true);
+            expect(gap.events).not.toContain('error');
+
+            for (const socket of proxied) socket.destroy();
+            await vi.waitFor(
+                () => {
+                    const replacement = connections.at(-1)!;
+                    expect(replacement).not.toBe(before);
+                    expect(appendsTo(replacement)).toBeGreaterThan(0);
+                },
+                { timeout: 15_000 },
+            );
+            const after = await page.evaluate(() => {
+                const t = (globalThis as unknown as { test: any }).test;
+                const live = t.tracks.every(
+                    (track: MediaStreamTrack) => track.readyState === 'live',
+                );
+                const state = t.c.state;
+                t.c.close();
+                return {
+                    live,
+                    state,
+                    mediaCalls: t.mediaCalls(),
+                    ended: t.tracks.every(
+                        (track: MediaStreamTrack) =>
+                            track.readyState === 'ended',
+                    ),
+                    reconnected: t.events.includes('reconnecting'),
+                    errors: t.events.filter((type: string) => type === 'error'),
+                };
+            });
+            expect(after).toEqual({
+                live: true,
+                state: 'connected',
+                mediaCalls: 1,
+                ended: true,
+                reconnected: true,
+                errors: [],
+            });
+        } finally {
+            await page.close();
+        }
+    }, 45_000);
+
     // Last: the relay refuses new sessions from here on.
     it('keeps the session working while a draining server refuses its replacement', async () => {
         const draining = loadNodePuter(

src/puter-js/tests/api/suites/ai.suite.ts

@@ -1789,6 +1789,21 @@ export default suite('ai', {
         }
     },
 
+    'convo rejects interruption readiness through its Promise': async (t) => {
+        const conversation = await t.puter.ai.convo({ output: ['text'] });
+        try {
+            const prepared = conversation.interrupt();
+            t.assert.equal(typeof prepared.then, 'function');
+            await t.assert.rejects(() => prepared);
+            conversation.close();
+            const closed = conversation.interrupt();
+            t.assert.equal(typeof closed.then, 'function');
+            await t.assert.rejects(() => closed);
+        } finally {
+            conversation.close();
+        }
+    },
+
     'convo is the realtime SDK entry point': async (t) => {
         t.assert.equal('assistant' in t.puter.ai, false);
         t.assert.equal('conversation' in t.puter.ai, false);