Test native app hosts with apps still served natively

editor, markus and pdf moved to standard host routing, but the host
redirect and embed framing tests still used editor as their native app,
so they failed. They now use about, and a test checks that editor,
markus and pdf are passed through even with a folder under the native
apps root.

.github/workflows/notify-dev.yaml

@@ -0,0 +1,48 @@
+name: Notify HeyPuter (dev)
+
+on:
+  workflow_dispatch:
+    inputs:
+      puter_ref:
+        description: "puter branch, tag or SHA"
+        type: string
+        default: "main"
+
+permissions:
+  contents: read
+
+jobs:
+  authorize:
+    if: github.repository == 'HeyPuter/puter'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Require maintain or admin
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          ACTOR: ${{ github.triggering_actor }}
+        run: |
+          ROLE=$(gh api "repos/$GITHUB_REPOSITORY/collaborators/$ACTOR/permission" --jq .role_name)
+          if [ "$ROLE" != "maintain" ] && [ "$ROLE" != "admin" ]; then
+            echo "::error::$ACTOR has role '$ROLE'; maintain or admin required"
+            exit 1
+          fi
+
+  notify:
+    needs: authorize
+    runs-on: ubuntu-latest
+    # Holds HEYPUTER_DISPATCH_TOKEN; limited to main so branch copies of this file can't read it.
+    environment: heyputer-dispatch
+    steps:
+      - name: Trigger heyputer dev deploy
+        env:
+          PUTER_REF: ${{ inputs.puter_ref }}
+          TOKEN: ${{ secrets.HEYPUTER_DISPATCH_TOKEN }}
+        run: |
+          jq -nc --arg ref "$PUTER_REF" \
+            '{event_type: "puter-dev-requested", client_payload: {puter_ref: $ref}}' |
+          curl -fsS -X POST \
+            -H "Authorization: token $TOKEN" \
+            -H "Accept: application/vnd.github.v3+json" \
+            https://api.github.com/repos/HeyPuter/heyputer/dispatches \
+            -d @-
+          echo "Requested \`$PUTER_REF\`" >> "$GITHUB_STEP_SUMMARY"

.github/workflows/notify-prod.yaml

@@ -8,6 +8,7 @@ on:
 jobs:
   notify:
     runs-on: ubuntu-latest
+    environment: heyputer-dispatch
     steps:
       - name: Trigger heyputer build
         run: |
@@ -15,4 +16,4 @@ jobs:
             -H "Authorization: token ${{ secrets.HEYPUTER_DISPATCH_TOKEN }}" \
             -H "Accept: application/vnd.github.v3+json" \
             https://api.github.com/repos/HeyPuter/heyputer/dispatches \
-            -d '{"event_type":"puter-main-updated","client_payload":{"puter_ref":"main"}}'
+            -d '{"event_type":"puter-main-updated","client_payload":{"puter_ref":"main"}}'

.github/workflows/puterjs-tests.yaml

@@ -176,7 +176,10 @@ jobs:
       - name: Checkout repository
         uses: actions/checkout@v7
 
+      # Missing when the PR leg failed; `coverage (pr)` already reports that.
       - name: Download PR coverage
+        id: pr-coverage
+        continue-on-error: true
         uses: actions/download-artifact@v8
         with:
           name: puterjs-coverage-pr
@@ -186,6 +189,7 @@ jobs:
       # base run) — then report without the comparison column.
       - name: Download base coverage
         id: base-coverage
+        if: steps.pr-coverage.outcome == 'success'
         continue-on-error: true
         uses: actions/download-artifact@v8
         with:
@@ -193,7 +197,7 @@ jobs:
           path: coverage-base
 
       - name: Report coverage on PR
-        if: steps.base-coverage.outcome == 'success'
+        if: steps.pr-coverage.outcome == 'success' && steps.base-coverage.outcome == 'success'
         uses: davelosert/vitest-coverage-report-action@v2
         with:
           name: puter.js SDK
@@ -202,7 +206,7 @@ jobs:
           json-summary-compare-path: coverage-base/coverage-summary.json
 
       - name: Report coverage on PR (no base comparison)
-        if: steps.base-coverage.outcome != 'success'
+        if: steps.pr-coverage.outcome == 'success' && steps.base-coverage.outcome != 'success'
         uses: davelosert/vitest-coverage-report-action@v2
         with:
           name: puter.js SDK

AGENTS.md

@@ -159,13 +159,42 @@ The reference has two kinds of page:
 
 An overview page answers "what is this API and is it what I need?", and a function page answers "how exactly does this call behave?". A change to one function usually only touches that function's page, so a new `kv.list()` option goes in `KV/list.md` without a matching update to `KV.md`. Don't copy a function's options, limits, or edge cases onto the overview page for completeness. Where a detail goes is a judgment call, not a hard rule: update the overview when a change affects how someone would describe the API as a whole.
 
-When you add a page, add it to [src/docs/src/sidebar.js](src/docs/src/sidebar.js) under its area, or it won't show up in the navigation. When you add a runnable example, add its HTML to `src/docs/src/playground/examples/<slug>.html`, register the slug in [src/docs/src/examples.js](src/docs/src/examples.js), and link the code block to it by putting the slug after the language with a semicolon (` ```html;kv-set `).
+When you add a page, add it to [src/docs/src/sidebar.js](src/docs/src/sidebar.js) under its area, or it won't show up in the navigation.
+
+**Sidebar order.** Order the API areas in the sidebar by how often developers use them, most common first. Overview stays first and Objects stays last. Inside an area, order the pages by use too, and keep pages that make up one feature next to each other, such as `share()`, `unshare()`, `listShared()`, and `listSharedByMe()`. A group goes where its most-used page would go. A helper that only supports another function, such as `listModels()` for `chat()`, goes by its own use. Put create, list, get, update, and delete in that order, and constants such as `MAX_KEY_SIZE` last. The function list on the area's overview page uses the sidebar's order. When you add a runnable example, add its HTML to `src/docs/src/playground/examples/<slug>.html`, register the slug in [src/docs/src/examples.js](src/docs/src/examples.js), and link the code block to it by putting the slug after the language with a semicolon (` ```html;kv-set `).
+
+### Function page layout
+
+A function page opens with one sentence that says what the function does, in its own paragraph, such as "Given a prompt, generate an image using AI." Put any more detail in the paragraphs after it.
+
+After the intro, a function page has these `##` sections, in this order:
+
+1. Syntax
+2. Parameters
+3. Return value
+4. Errors, if the function has any
+5. Sections for specific topics, if the page needs them, with `## Model-specific features` last
+6. Examples
+
+[chat.md](src/docs/src/AI/chat.md) follows this layout.
+
+- **Options as a table.** Document an options object as a table with Option, Type, and Description columns. Give each option its own row, even when two options go together, such as `width` and `height`. Order the rows by how often developers use them, most common first, without group rows. In chat.md that's the core options, then reasoning, tools, response handling, request control, and output.
+- **Common options in the table, model-specific behavior in its own section.** A page whose function works with many models or providers, such as [chat.md](src/docs/src/AI/chat.md) and [txt2img.md](src/docs/src/AI/txt2img.md), splits its options this way:
+  - **The options table** under Parameters lists the options that work with every model, and describes each one the way it works for every model.
+  - **`## Model-specific features`**, the last section before Examples, covers everything else. It has a `###` for each model family or provider, named after it, such as "OpenAI models" or "Cloudflare models". Under it go the options only some models accept, and the common options a model handles differently, such as a narrower range, other allowed values, or an option it ignores.
+  - **Write there only what's different.** A `###` lists an option only when that model or provider adds it or handles it differently. An option that works the same everywhere stays out, even if the provider supports it, and a model or provider with nothing different gets no `###`.
+  - **Model-specific features is the only place for model-specific details.** Every limit, format, allowed value, default, price, or quirk that applies to some models goes there, in that model's or provider's `###`, and nowhere else. The options table and topic sections (such as Image inputs or Video input) describe what's true for every model and link to Model-specific features for the rest. Don't add a table or sentence there that compares providers or repeats a model's limits. Each copy is another source of truth to keep in sync, and copies drift when a model changes.
+  - **Link the two.** Directly under the options table, put `Some models accept additional options or handle these options differently. See [Model-specific features](#model-specific-features).` A row whose option behaves differently on some models can also end with `See [Model-specific features](#model-specific-features).`
+- **A long topic gets its own `##` section.** When explaining an option or feature takes more than a sentence or two, such as function calling or output dimensions, give it a section between Errors and Examples and link to it from the options table. This keeps the reference sections short.
+- **Usage patterns are examples.** A way of using the API, such as stopping a stream, goes in a runnable example that the relevant section links to ("See the [stop a stream example](/playground/ai-chat-stop-stream/)."), not in a section of its own.
+- **Each example has a `###` heading** under `## Examples`, so every example shows in the table of contents.
 
 ### Writing docs
 
 These apply to reference pages and recipes alike.
 
 - **Document the developer-facing side only.** The reader is building on top of puter.js, so cover what affects their code: signatures, defaults, return shapes, errors, limits, and behavior they can observe. Leave out internal workings (which service handles the call, storage layout, caching, retries) unless they change what the developer has to do. [rate-limits-and-quotas.md](src/docs/src/rate-limits-and-quotas.md) is the exception: it publishes every limit, including timeouts and caps that come from how the backend works.
+- **Document Puter as it runs on puter.com.** The docs are for developers building on production Puter. Leave out behavior that only happens on a self-hosted or differently configured server, such as a provider that isn't set up there.
 - **Describe the current state.** Docs aren't a changelog. Write how the API behaves now, without "now", "no longer", "existing code is unaffected", or other wording that compares it to an older version.
 - **Verify before you document.** Run the calls you describe against a running Puter instead of inferring behavior from the source.
 - **Write plainly.** Use the literal words a developer would say out loud, with contractions and everyday words. No idioms or figurative verbs ("walk away from something shared with you" → "remove your own access", "nothing to page through" → "without pagination"). No formal register ("present only while more pages remain" → "includes a `cursor` if there are more pages to load"). Prefer dev terms such as atomic, concurrent, and insertion order.
@@ -173,6 +202,7 @@ These apply to reference pages and recipes alike.
 - **Describe behavior directly.** No quoted inner-voice phrases. Write "`isNew` is `true` when the person did not have access before", not "this tells 'I just gave this to someone' from 'they already had it'".
 - **Keep references easy to follow.** Name what a list or code block belongs to in the sentence directly above it. Name a thing once and keep that name. Introduce an actor as "a user" before giving them a role: "A user can create a team. The user who creates the team becomes its owner."
 - **Sentence mechanics.** Never start a sentence with inline code: write "To store data, use the [`set()`](/KV/set/) method." Link every inline mention of an API to its page, every time. No em dashes, and no colons or semicolons mid-sentence; a colon that introduces a code block is fine.
+- **No `##` or `###` headings inside tabs.** The table of contents lists every `##` and `###` heading on the page, including the ones in a hidden tab (an `example-content` block switched by the `example-group` pills), so its links lead to content the reader can't see. Put the heading above the tabs, or use `####` inside a tab, which the table of contents skips.
 - **Show the correct way.** No "don't" and no wrong-way-first examples, in recipes and playground examples alike. Mention a wrong approach only when developers already hit it in practice, and state how it fails as a fact: "`add()` reads a plain object as a path map, so the call rejects with …".
 
 ### Recipes

doc/embedding-app-browser.md

@@ -0,0 +1,147 @@
+# Embedded app browser
+
+`GET /embed/apps` on the deployment's main GUI origin renders the same app browser
+as the dashboard's Apps tab, without the desktop or dashboard navigation.
+
+It supports search, paging, saved folders, and saved ordering. It uses the same
+installed-app and recommendation data as the dashboard, including the user's
+removed recommendations. Editing, adding, reordering, renaming, and uninstalling
+are disabled. Selecting an app opens it in a new browser tab at its own URL, the
+same way the dashboard does, and the host page stays open. The app's token isn't
+put in the URL: the app's SDK asks the embed for it once the tab loads, so the
+embed must still be open then. If the iframe is removed first, the app falls back
+to its normal sign-in. Apps that need the desktop (built-in and godmode apps,
+private apps the user can't open, or a failed token request) open `/app/<name>`
+on the GUI origin, cut off from the embed. Website shortcuts open their external
+destination with no opener.
+The embed follows the OS's light or dark setting. A host with a fixed theme adds
+`theme=dark` or `theme=light` to the fragment (`#user=<uuid>&theme=dark`), since
+Chromium doesn't pass an iframe's `color-scheme` on to the page inside it.
+Apps opened from the embed carry `utm_source=puter.com&utm_medium=referral&utm_campaign=app_browser_embed`;
+the desktop and dashboard send `utm_campaign=desktop` and `utm_campaign=dashboard`.
+
+## Session and framing
+
+The embed shows the GUI session only to the user the host page is signed in as.
+The host names that user's `uuid` (from `puter.auth.getUser()`) in the iframe
+URL's fragment, as `/embed/apps#user=<uuid>`. The embed reads the session, asks
+`/whoami` which user it belongs to, and shows the signed-out view unless the two
+match. So a host that names no user, a malformed one, or a user other than the
+session's, gets the signed-out view, and so does a session the API refuses. A
+failed `/whoami` check shows the error state. The fragment never reaches the
+server and can only narrow what the embed shows: naming the session's own user
+gives the same view as a direct visit to the GUI. Changing the fragment of a
+loaded embed reloads it.
+
+The embed reads the existing GUI session from local storage on its own origin.
+If that storage holds no session, the embed gets the session from the GUI origin's session cookie through
+`/get-gui-token`. This matters in Safari, which gives a framed origin separate
+local storage under each top-level origin, so even a sibling subdomain's iframe
+can't see the GUI's stored token. The session cookie is still sent, because the
+host is on the same site. The embed doesn't write that token back to storage. It
+does not create accounts, show a login dialog, or accept a token from its parent.
+Being signed in on a subdomain alone does not create a session on the main GUI
+origin.
+
+Without a session it can show, the embed shows the recommended apps (`RecommendedAppsService`)
+that the server put in the page, and nothing else: no installed apps, folders, or
+saved order, and no puter.js. Selecting one opens it at the same URL a signed-in
+launch uses, with no opener and no token on offer, so the app signs in on its own.
+Apps that need the desktop open `/app/<name>`. If the page carries no recommended
+apps, or a load fails, the embed displays an unavailable/error state.
+
+The route's `Content-Security-Policy: frame-ancestors` allows the GUI origin and
+the embedding page's origin when it is exactly one label under `config.domain`
+with the scheme and port from `config.origin`. Subdomains the server answers
+itself (`api`, `dav`, `js`, `www`, the native-app hosts, and the host of
+`api_base_url`) and the user-content hosting domains (`static_hosting_domain`,
+`private_app_hosting_domain`, and their `_alt` variants) are refused. For
+example, `https://puter.com` permits `https://spreadsheet.puter.com` but not
+`https://api.puter.com`, and `http://puter.localhost:4100` permits
+`http://spreadsheet.puter.localhost:4100` but not
+`http://someone.site.puter.localhost:4100`. The embedding page is read from the
+iframe request's referrer, so the host must not suppress it (the browser default
+`strict-origin-when-cross-origin` is enough). All ancestors in a nested iframe
+chain must be allowed. Other GUI routes retain `X-Frame-Options: SAMEORIGIN`.
+
+The embed accepts no query parameters. Requests with a query string redirect to
+the same embed path so SDK bootstrap parameters cannot override the session or API
+origin. The host needs to allow the GUI origin in its own `frame-src` CSP if it
+sets one. If sandboxing the iframe, allow scripts, same-origin storage, popups,
+and popups to escape the sandbox.
+
+## Host integration
+
+A first-party app that signs in with puter.js can place `<puter-user-menu>` from
+the SDK in its header instead (see `src/puter-js/src/ui/components.md`). It opens
+this embed with the signed-in user named and closes it when the app's sign-in
+changes. The rest of this section is for a host that builds the iframe itself.
+
+The iframe can be shown whether or not the user is signed in. Create it when
+“More apps” is opened, naming the signed-in user in its fragment, and remove it
+on close so reopening loads current apps and preferences. Remove it when the
+host's own sign-in changes too, such as on sign-out, so an open embed doesn't
+keep the previous user. The host owns the modal and close control;
+there is no parent messaging API and no app list or credential is sent to it.
+The app browser fills its iframe and responds to its size. It shows a spinner until its apps load.
+
+This example assumes `puterOrigin` comes from the host app's deployment
+settings. Translate the button and frame labels using the host app's
+localization system.
+
+```html
+<button id="more-apps" type="button">More apps</button>
+<dialog id="apps-dialog" aria-label="More apps">
+  <button id="close-apps" type="button">Close</button>
+  <div id="apps-frame"></div>
+</dialog>
+<style>
+  #apps-dialog { padding: 12px; width: min(900px, 90vw); }
+  #apps-frame iframe { width: 100%; height: min(650px, 75vh); border: 0; }
+</style>
+<script type="module">
+  const puterOrigin = 'https://puter.com'; // Use this deployment's configured origin.
+  const dialog = document.querySelector('#apps-dialog');
+  const container = document.querySelector('#apps-frame');
+  const trigger = document.querySelector('#more-apps');
+
+  trigger.addEventListener('click', async () => {
+    const url = new URL('/embed/apps', puterOrigin);
+    // Signed out, the embed shows the recommended apps.
+    const user = puter.auth.isSignedIn() ? await puter.auth.getUser().catch(() => null) : null;
+    if (user) url.hash = `user=${encodeURIComponent(user.uuid)}`;
+    const frame = document.createElement('iframe');
+    frame.title = 'Your apps';
+    frame.src = url.href;
+    container.replaceChildren(frame);
+    dialog.showModal();
+  });
+  document.querySelector('#close-apps').addEventListener('click', () => dialog.close());
+  dialog.addEventListener('close', () => {
+    container.replaceChildren();
+    trigger.focus();
+  });
+</script>
+```
+
+## Implementation and checks
+
+`createAppBrowser` in `src/gui/src/UI/Dashboard/AppBrowser.js` owns the shared UI
+and data behavior; its `guestApps` option is the signed-out list. `TabApps.js`
+injects desktop actions. `appsEmbed.js` supplies new-tab launching through
+`launchAppInTab` (signed in) and `guestAppLaunchUrl` (signed out) in
+`src/gui/src/helpers/appTabLaunch.js`, which build the same app URL as
+`launch_app`, and loads only the embed entry, its SDK, and shared styles. `embedHostUser` in
+`src/gui/src/helpers/embedHostUser.js` reads the host's user from the fragment, and
+`embedHostTheme.js` beside it applies the host's theme.
+The normal GUI webpack build emits `bundle.min.js` and `apps-embed.min.js`.
+The `/embed/apps` route puts the recommended list in the page's config as
+`guestApps`. No puter.js API or app-list endpoint changes are needed.
+
+Run the GUI component/browser tests (with the SDK bundle built and Playwright
+Chromium installed), and the backend route tests:
+
+```sh
+npx vitest run --config src/gui/vitest.config.js src/gui/src/UI/Dashboard/AppBrowser
+npx vitest run --config src/backend/vitest.config.ts src/backend/server.test.ts
+```

doc/pagination.md

@@ -63,6 +63,9 @@ store:
   sealed cursor: the last `id` it returned, and the last `(replaced_at, id)`
   among rows up to that id. Each is its own indexed read, merged into one
   page, so a row replaced after a client read it comes back from that cursor.
+  `from=end` with no cursor answers an empty page whose cursor holds the
+  slice's newest `id` and the slice's latest `(replaced_at, id)` as the
+  replacement mark.
 
 Cursors that carry a sort also pin it: a request that passes a cursor plus a
 conflicting sort is rejected with 400.

doc/push-client.md

@@ -1,6 +1,6 @@
 # Browser push client
 
-Puter's desktop shows pushes through `/sw.js`. Core registers it, and shows Settings → Notifications, only when the `pushEnabled` gui param is `true`; core never sets it. A backend extension that delivers pushes sets it with `services.homepage.setGuiParam('pushEnabled', true)` and can load its own code into the worker with `services.homepage.registerServiceWorkerScript(path)`.
+Puter's desktop shows pushes through `/sw.js`. Core shows Settings → Notifications only when the `pushEnabled` gui param is `true`; core never sets it. The worker is registered only when push is turned on in the browser, and a load removes one left without a subscription. A backend extension that delivers pushes sets it with `services.homepage.setGuiParam('pushEnabled', true)` and can load its own code into the worker with `services.homepage.registerServiceWorkerScript(path)`.
 
 Core subscribes the browser to a push service only when the server also publishes `pushWebPushKey` (see [Built-in Web Push client](#built-in-web-push-client)), and it has no `/push/*` routes of its own. The device, app, preference and subscription endpoints below come from that extension. On a deployment without one, such as most self-hosted servers, they answer core's plain 404 (`code: 'not_found'`), which `puter.notifications` reports as `push_unavailable` and the Notifications tab shows as unavailable. A device the extension can't find is `device_not_found`.
 
@@ -22,12 +22,13 @@ When the browser replaces the subscription (`pushsubscriptionchange`), `sw.js` p
 
 Before a notification is pushed, the server asks the open clients whether they received it live. It sends `notif.receipt` with `{ uid }` on the user's sockets for the app that sent it, or on the desktop's sockets for Puter's own notifications. The SDK remembers the uids its page received through `onNotification()`, `onPush()` or the desktop's feed, and answers once its page has that notification, or with `{ received: false }` when it never gets it. The server waits up to 5 seconds (`notificationAckTimeoutMs`).
 
-An answer carries `visibilityState`, `focused` and `showsOwn`, the last being whether the page shows the notification itself. A website page shows it itself when it is hidden or unfocused, has an `onPush()` handler and notification permission, and no other tab of the same site is focused. Inside the desktop, the desktop shows it, and an app's `onPush()` result is never shown as a browser notification.
+An answer carries `visibilityState` and `focused` as they were when the page received the notification. Pages never show a browser notification themselves; pushes do.
 
-- An answer from a page that is visible and focused, or that shows the notification itself, stops the push.
-- Otherwise the notification is pushed. A website's pushes go only to the browsers that subscribed through its own worker, never to Puter's `/sw.js`. An app inside the desktop pushes through `/sw.js`, which shows the app's name and icon.
-- A hidden desktop tab shows no banner, so answers only from hidden desktop tabs don't stop a push of Puter's own notifications.
-- A client that can't answer, such as an older puter.js, holds the push back while it is connected.
+- An answer from a page that was visible and focused stops the push (`handled` on `notif.delivery.settled`). An older client that doesn't send `focused` counts while visible.
+- Otherwise the notification is pushed, to every browser the user subscribed. A website's pushes go only to the browsers that subscribed through its own worker, never to Puter's `/sw.js`. An app inside the desktop pushes through `/sw.js`, which shows the app's name and icon.
+- A client that can't answer, such as an older puter.js, doesn't hold the push back.
+
+The ask reaches only the sockets in the asking region. So that other regions hear about a page too, a page that receives a notification live while visible and focused also sends `notif.handled` with `{ uid }` on the socket it came on. Core relays it as the node-local `notif.handled` event with the socket's user and app, at most 60 a minute per user; an extension that delivers pushes decides what to do with it.
 
 ## Registering
 

src/backend/clients/database/DatabaseClient.test.ts

@@ -318,3 +318,13 @@ describe('AbstractDatabaseClient — SQL generation', () => {
         );
     });
 });
+
+
+it('builds an insert for batchWrite and shares it with insert', async () => {
+    const client = new FixtureDatabaseClient([]);
+    const entry = client.insertEntry('widget', { name: "reader's", enabled: true });
+    expect(entry.values).toEqual(["reader's", true]);
+    expect(entry.statement).toContain('VALUES (?, ?)');
+    await client.insert('widget', { name: "reader's", enabled: true });
+    expect(client.writes).toEqual([{ query: entry.statement, params: entry.values }]);
+});

src/backend/clients/database/DatabaseClient.ts

@@ -110,14 +110,23 @@ export class AbstractDatabaseClient extends PuterClient {
         tableName: string,
         data: Record<string, unknown>,
     ): Promise<WriteResult> {
+        const entry = this.insertEntry(tableName, data);
+        return this.write(
+            entry.statement + this.returningIdClause(),
+            entry.values,
+        );
+    }
+
+    /** An insert that can join other writes in a transaction. */
+    insertEntry(tableName: string, data: Record<string, unknown>): BatchEntry {
         const cols = Object.keys(data);
-        const values = Object.values(data);
-        const sql =
-            `INSERT INTO ${this.quoteIdentifier(tableName)} ` +
-            `(${cols.map((c) => this.quoteIdentifier(c)).join(', ')}) ` +
-            `VALUES (${cols.map(() => '?').join(', ')})` +
-            this.returningIdClause();
-        return this.write(sql, values);
+        return {
+            statement:
+                `INSERT INTO ${this.quoteIdentifier(tableName)} ` +
+                `(${cols.map((c) => this.quoteIdentifier(c)).join(', ')}) ` +
+                `VALUES (${cols.map(() => '?').join(', ')})`,
+            values: Object.values(data),
+        };
     }
 
     /** Whether `read()` goes to a separate replica rather than the primary. */

src/backend/clients/database/SqliteDatabaseClient.test.ts

@@ -27,7 +27,7 @@ import { DatabaseClientFactory } from './index.js';
 import { SqliteDatabaseClient } from './SqliteDatabaseClient.js';
 
 /** Highest schema version the migration table can reach. */
-const CURRENT_SCHEMA_VERSION = 96;
+const CURRENT_SCHEMA_VERSION = 98;
 
 /**
  * These suites migrate real files on disk. Idle they finish in well under a
@@ -735,6 +735,74 @@ describe('SqliteDatabaseClient — boot and migrations', { timeout: DISK_MIGRATI
         expect(columns.map((c) => String(c.name))).toEqual(['send_key']);
     });
 
+    it('creates event_user_handlers with its unique and holder indexes', async () => {
+        const columns = await client.read(
+            'PRAGMA table_info(`event_user_handlers`)',
+        );
+        expect(columns.map((c) => String(c.name))).toEqual([
+            'id',
+            'app_uid',
+            'holder_user_id',
+            'name',
+            'source',
+            'source_hash',
+            'created_at',
+            'updated_at',
+            'scope_since',
+        ]);
+        const indexes = await client.read(
+            'PRAGMA index_list(`event_user_handlers`)',
+        );
+        expect(
+            indexes.find(
+                (i) => i.name === 'idx_event_user_handlers_app_holder_name',
+            ),
+        ).toMatchObject({ unique: 1 });
+        expect(
+            indexes.find((i) => i.name === 'idx_event_user_handlers_holder_app'),
+        ).toMatchObject({ unique: 0 });
+        const columnsOf = async (index: string) =>
+            (await client.read(`PRAGMA index_info(\`${index}\`)`)).map((c) =>
+                String(c.name),
+            );
+        expect(await columnsOf('idx_event_user_handlers_app_holder_name')).toEqual(
+            ['app_uid', 'holder_user_id', 'name'],
+        );
+        expect(await columnsOf('idx_event_user_handlers_holder_app')).toEqual([
+            'holder_user_id',
+            'app_uid',
+        ]);
+    });
+
+    it('leaves event_handlers as it was', async () => {
+        const columns = await client.read('PRAGMA table_info(`event_handlers`)');
+        expect(columns.map((c) => String(c.name))).toEqual([
+            'id',
+            'app_uid',
+            'name',
+            'source',
+            'source_hash',
+            'created_at',
+            'updated_at',
+        ]);
+    });
+
+    it('adds event_subscriptions.handler_scope, app scope for existing rows', async () => {
+        const columns = await client.read(
+            'PRAGMA table_info(`event_subscriptions`)',
+        );
+        expect(columns.find((c) => c.name === 'handler_scope')).toMatchObject({
+            notnull: 1,
+            dflt_value: '0',
+        });
+        const indexes = await client.read(
+            'PRAGMA index_list(`event_subscriptions`)',
+        );
+        expect(indexes.map((i) => String(i.name))).toContain(
+            'idx_event_subscriptions_holder',
+        );
+    });
+
     it('leaves an already-migrated database untouched on a second boot', async () => {
         const dir = mkdtempSync(join(tmpdir(), 'puter-sqlite-'));
         const path = join(dir, 'nested', 'puter.sqlite');

src/backend/clients/database/SqliteDatabaseClient.ts

@@ -135,6 +135,8 @@ const AVAILABLE_MIGRATIONS: [number, string[]][] = [
     [93, ['0098_notification-groups.sql']],
     [94, ['0099_kv-share-handle-notify.sql']],
     [95, ['0100_notification-send-key.sql']],
+    [96, ['0101_user-scoped-handlers.sql']],
+    [97, ['0102_notification-scope-id-index.sql']],
 ];
 
 export class SqliteDatabaseClient extends AbstractDatabaseClient {

src/backend/clients/database/migrations/mysql/mysql_mig_55.sql

@@ -0,0 +1,66 @@
+-- Copyright (C) 2024-present Puter Technologies Inc.
+--
+-- This file is part of Puter.
+--
+-- Puter is free software: you can redistribute it and/or modify
+-- it under the terms of the GNU Affero General Public License as published
+-- by the Free Software Foundation, either version 3 of the License, or
+-- (at your option) any later version.
+--
+-- This program is distributed in the hope that it will be useful,
+-- but WITHOUT ANY WARRANTY; without even the implied warranty of
+-- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+-- GNU Affero General Public License for more details.
+--
+-- You should have received a copy of the GNU Affero General Public License
+-- along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+-- Handlers an app's user published into their own scope, kept apart from
+-- `event_handlers` so code that predates them never reads them. See
+-- sqlite/0101_user-scoped-handlers.sql for the column rationale.
+--
+-- Idempotent: `CREATE TABLE IF NOT EXISTS` with the indexes declared inline,
+-- and a guarded column add. There is no per-file applied-state tracking, so a
+-- replay has to be a no-op.
+
+CREATE TABLE IF NOT EXISTS `event_user_handlers` (
+    `id` bigint unsigned NOT NULL AUTO_INCREMENT,
+    -- Matches `apps`.`uid` exactly, charset included, so an equality against
+    -- one never falls back to a conversion.
+    `app_uid` char(40) CHARACTER SET latin1 COLLATE latin1_swedish_ci NOT NULL,
+    `holder_user_id` int unsigned NOT NULL,
+    `name` varchar(128) NOT NULL,
+    `source` mediumtext NOT NULL,
+    `source_hash` char(64) NOT NULL,
+    `created_at` bigint NOT NULL,
+    `updated_at` bigint NOT NULL,
+    -- When the scope first held a handler; kept across handler churn, so the
+    -- rent sweep sees the scope's age, not its oldest remaining handler's.
+    `scope_since` bigint NOT NULL,
+    PRIMARY KEY (`id`),
+    UNIQUE KEY `idx_event_user_handlers_app_holder_name` (`app_uid`, `holder_user_id`, `name`),
+    KEY `idx_event_user_handlers_holder_app` (`holder_user_id`, `app_uid`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
+
+-- Guarded here rather than through `_puter_add_col`, so the file also applies
+-- on its own to a database that never ran the earlier migrations.
+DROP PROCEDURE IF EXISTS _puter_add_event_subscriptions_handler_scope;
+DELIMITER //
+CREATE PROCEDURE _puter_add_event_subscriptions_handler_scope()
+BEGIN
+  IF NOT EXISTS (
+    SELECT 1 FROM INFORMATION_SCHEMA.COLUMNS
+    WHERE TABLE_SCHEMA = DATABASE()
+      AND TABLE_NAME = 'event_subscriptions'
+      AND COLUMN_NAME = 'handler_scope'
+  ) THEN
+    ALTER TABLE `event_subscriptions`
+      ADD COLUMN `handler_scope` tinyint unsigned NOT NULL DEFAULT 0,
+      ALGORITHM=INSTANT;
+  END IF;
+END//
+DELIMITER ;
+
+CALL _puter_add_event_subscriptions_handler_scope();
+
+DROP PROCEDURE IF EXISTS _puter_add_event_subscriptions_handler_scope;

src/backend/clients/database/migrations/mysql/mysql_mig_56.sql

@@ -0,0 +1,41 @@
+-- Copyright (C) 2024-present Puter Technologies Inc.
+--
+-- This file is part of Puter.
+--
+-- Puter is free software: you can redistribute it and/or modify
+-- it under the terms of the GNU Affero General Public License as published
+-- by the Free Software Foundation, either version 3 of the License, or
+-- (at your option) any later version.
+--
+-- This program is distributed in the hope that it will be useful,
+-- but WITHOUT ANY WARRANTY; without even the implied warranty of
+-- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+-- GNU Affero General Public License for more details.
+--
+-- You should have received a copy of the GNU Affero General Public License
+-- along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+-- `notification` (`user_id`, `audience`, `app_uid`, `id`). See
+-- sqlite/0102_notification-scope-id-index.sql for the rationale. No per-file
+-- applied-state tracking, so the index is added only when missing and a
+-- replay does nothing.
+
+DROP PROCEDURE IF EXISTS _puter_add_notification_scope_id_index;
+DELIMITER //
+CREATE PROCEDURE _puter_add_notification_scope_id_index()
+BEGIN
+  IF NOT EXISTS (
+    SELECT 1 FROM INFORMATION_SCHEMA.STATISTICS
+    WHERE TABLE_SCHEMA = DATABASE()
+      AND TABLE_NAME = 'notification'
+      AND INDEX_NAME = 'idx_notification_scope_id'
+  ) THEN
+    ALTER TABLE `notification` ADD INDEX `idx_notification_scope_id`
+      (`user_id`, `audience`, `app_uid`, `id`), ALGORITHM=INPLACE, LOCK=NONE;
+  END IF;
+END//
+DELIMITER ;
+
+CALL _puter_add_notification_scope_id_index();
+
+DROP PROCEDURE IF EXISTS _puter_add_notification_scope_id_index;

src/backend/clients/database/migrations/postgres/postgres_mig_44.sql

@@ -0,0 +1,39 @@
+-- Copyright (C) 2024-present Puter Technologies Inc.
+--
+-- This file is part of Puter.
+--
+-- Puter is free software: you can redistribute it and/or modify
+-- it under the terms of the GNU Affero General Public License as published
+-- by the Free Software Foundation, either version 3 of the License, or
+-- (at your option) any later version.
+--
+-- This program is distributed in the hope that it will be useful,
+-- but WITHOUT ANY WARRANTY; without even the implied warranty of
+-- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+-- GNU Affero General Public License for more details.
+--
+-- You should have received a copy of the GNU Affero General Public License
+-- along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+-- Handlers an app's user published into their own scope. See
+-- sqlite/0101_user-scoped-handlers.sql for the column rationale.
+-- Idempotent via IF NOT EXISTS.
+
+CREATE TABLE IF NOT EXISTS event_user_handlers (
+    id BIGSERIAL PRIMARY KEY,
+    app_uid VARCHAR(40) NOT NULL,
+    holder_user_id INTEGER NOT NULL,
+    name VARCHAR(128) NOT NULL,
+    source TEXT NOT NULL,
+    source_hash VARCHAR(64) NOT NULL,
+    created_at BIGINT NOT NULL,
+    updated_at BIGINT NOT NULL,
+    scope_since BIGINT NOT NULL
+);
+
+CREATE UNIQUE INDEX IF NOT EXISTS idx_event_user_handlers_app_holder_name
+    ON event_user_handlers (app_uid, holder_user_id, name);
+CREATE INDEX IF NOT EXISTS idx_event_user_handlers_holder_app
+    ON event_user_handlers (holder_user_id, app_uid);
+
+ALTER TABLE event_subscriptions ADD COLUMN IF NOT EXISTS handler_scope smallint NOT NULL DEFAULT 0;

src/backend/clients/database/migrations/postgres/postgres_mig_45.sql

@@ -0,0 +1,23 @@
+-- Copyright (C) 2024-present Puter Technologies Inc.
+--
+-- This file is part of Puter.
+--
+-- Puter is free software: you can redistribute it and/or modify
+-- it under the terms of the GNU Affero General Public License as published
+-- by the Free Software Foundation, either version 3 of the License, or
+-- (at your option) any later version.
+--
+-- This program is distributed in the hope that it will be useful,
+-- but WITHOUT ANY WARRANTY; without even the implied warranty of
+-- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+-- GNU Affero General Public License for more details.
+--
+-- You should have received a copy of the GNU Affero General Public License
+-- along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+-- notification (user_id, audience, app_uid, id). See
+-- sqlite/0102_notification-scope-id-index.sql for the rationale. Idempotent via
+-- IF NOT EXISTS.
+
+CREATE INDEX IF NOT EXISTS idx_notification_scope_id
+    ON notification (user_id, audience, app_uid, id);

src/backend/clients/database/migrations/sqlite/0101_user-scoped-handlers.sql

@@ -0,0 +1,48 @@
+-- Copyright (C) 2024-present Puter Technologies Inc.
+--
+-- This file is part of Puter.
+--
+-- Puter is free software: you can redistribute it and/or modify
+-- it under the terms of the GNU Affero General Public License as published
+-- by the Free Software Foundation, either version 3 of the License, or
+-- (at your option) any later version.
+--
+-- This program is distributed in the hope that it will be useful,
+-- but WITHOUT ANY WARRANTY; without even the implied warranty of
+-- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+-- GNU Affero General Public License for more details.
+--
+-- You should have received a copy of the GNU Affero General Public License
+-- along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+-- Handlers an app's user published into their own scope, in a table of their
+-- own so `event_handlers` stays the app owner's set. Same columns as
+-- `event_handlers` (see 0076_event-handlers.sql) plus the holder.
+--
+--   - `holder_user_id` : the user whose scope this is. A name is unique per
+--                        (app, holder), so the same name can live in the app's
+--                        set and in each holder's.
+--   - `(holder_user_id, app_uid)` : a holder's scopes, for listing and for the
+--                        rent count.
+--
+-- `event_subscriptions.handler_scope` says which table a row's `handler_name`
+-- refers to: 0 the app's set, 1 the row holder's scope.
+
+CREATE TABLE IF NOT EXISTS `event_user_handlers` (
+    "id" INTEGER PRIMARY KEY AUTOINCREMENT,
+    "app_uid" TEXT NOT NULL,
+    "holder_user_id" INTEGER NOT NULL,
+    "name" TEXT NOT NULL,
+    "source" TEXT NOT NULL,
+    "source_hash" TEXT NOT NULL,
+    "created_at" INTEGER NOT NULL,    -- unix seconds
+    "updated_at" INTEGER NOT NULL,
+    "scope_since" INTEGER NOT NULL    -- unix seconds; the scope's first handler, kept across churn
+);
+
+CREATE UNIQUE INDEX IF NOT EXISTS `idx_event_user_handlers_app_holder_name`
+    ON `event_user_handlers` (`app_uid`, `holder_user_id`, `name`);
+CREATE INDEX IF NOT EXISTS `idx_event_user_handlers_holder_app`
+    ON `event_user_handlers` (`holder_user_id`, `app_uid`);
+
+ALTER TABLE `event_subscriptions` ADD COLUMN `handler_scope` INTEGER NOT NULL DEFAULT 0;

src/backend/clients/database/migrations/sqlite/0102_notification-scope-id-index.sql

@@ -0,0 +1,22 @@
+-- Copyright (C) 2024-present Puter Technologies Inc.
+--
+-- This file is part of Puter.
+--
+-- Puter is free software: you can redistribute it and/or modify
+-- it under the terms of the GNU Affero General Public License as published
+-- by the Free Software Foundation, either version 3 of the License, or
+-- (at your option) any later version.
+--
+-- This program is distributed in the hope that it will be useful,
+-- but WITHOUT ANY WARRANTY; without even the implied warranty of
+-- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+-- GNU Affero General Public License for more details.
+--
+-- You should have received a copy of the GNU Affero General Public License
+-- along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+-- Index a mailbox slice by row id, so a fetch finds the newest row of a slice,
+-- and pages forward through one, with a seek rather than a scan of the slice.
+
+CREATE INDEX IF NOT EXISTS `idx_notification_scope_id`
+    ON `notification` (`user_id`, `audience`, `app_uid`, `id`);

src/backend/clients/event/types.ts

@@ -117,7 +117,7 @@ export type EventMap = {
         model_used: string;
         service_used: string;
         intended_service: string;
-        model_details: {
+        model_details?: {
             id: string;
             provider: string;
             input_cost_key: string;
@@ -200,6 +200,16 @@ export type EventMap = {
     };
 
     // ---- Auth / signup ----
+    /**
+     * Which signup methods are open, emitted via `emitAndWait` before every
+     * signup and whenever the GUI reads the provider list. A listener sets
+     * `oidcOnly` to refuse form and temp signups, leaving OIDC and team
+     * provisioning open; `message` is what a refused form signup is told.
+     */
+    'puter.signup.policy': {
+        oidcOnly: boolean;
+        message: string | null;
+    };
     'puter.signup.validate': {
         allow: boolean;
         email?: string;
@@ -546,6 +556,14 @@ export type EventMap = {
     'kv.share.retired': { handles: string[]; userId: number };
 
     // ---- Notifications ----
+    /** An app message was acknowledged after its state committed. */
+    'notif.acknowledged': {
+        userId: number;
+        uid: string;
+        type: string;
+        audience: string;
+        appUid: string;
+    };
     /**
      * A notification row exists. Emitted after the insert commits — nothing
      * pushes a uid before there is a row to name — and carries the scope tuple
@@ -579,6 +597,8 @@ export type EventMap = {
         value: Record<string, unknown>;
         /** An earlier notification rewritten in place. */
         updated?: true;
+        /** Replaced an earlier notification in its group. */
+        replaced?: true;
         /** Names this one send, for a receipt asked about it. */
         sendId: string;
         /** The same `sendId` may be emitted again, as a delayed send is. */
@@ -616,6 +636,18 @@ export type EventMap = {
         /** A peer region holds a socket for the user. */
         peerRegions: boolean;
         responders: NotifDeliveryResponder[];
+        /** A page here got it live while visible and focused. */
+        handled: boolean;
+    };
+    /**
+     * A page reported that it got a notification live while visible and
+     * focused. Node-local; `appUid` is the reporting socket's app, absent for
+     * the desktop.
+     */
+    'notif.handled': {
+        userId: number;
+        appUid?: string;
+        uid: string;
     };
 
     // ---- Metering ----
@@ -666,9 +698,18 @@ export type EventMap = {
     // and going away (1→0, whether by removing the last handler or by the
     // destroy route). `actor.user` is the app's owner, not the caller — a
     // developer session publishing for an app it owns is the common case, but
-    // billing follows ownership.
-    'events.worker.create': { actor: Actor; appUid: string };
-    'events.worker.destroy': { actor: Actor; appUid: string };
+    // billing follows ownership. For `scope: 'user'` the unit is one user's
+    // handlers in one app instead, and `actor.user` is that user.
+    'events.worker.create': {
+        actor: Actor;
+        appUid: string;
+        scope: 'app' | 'user';
+    };
+    'events.worker.destroy': {
+        actor: Actor;
+        appUid: string;
+        scope: 'app' | 'user';
+    };
 
     // ---- Outer / GUI broadcast ----
     'outer.cacheUpdate': {
@@ -832,6 +873,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.
@@ -1057,11 +1104,6 @@ export interface NotifDeliveryResponder {
     visibilityState: 'visible' | 'hidden' | 'unknown';
     /** The page's window has focus. Absent from older clients. */
     focused?: boolean;
-    /**
-     * The page shows its own browser notification while hidden or unfocused.
-     * Absent from older clients.
-     */
-    showsOwn?: boolean;
 }
 
 export type EventMetadata = {

src/backend/clients/events/EventsWorkerInvokerClient.test.ts

@@ -23,16 +23,20 @@
  */
 
 import type { fetch as undiciFetch } from 'undici';
-import { describe, expect, it, vi } from 'vitest';
+import { afterEach, describe, expect, it, vi } from 'vitest';
 import type { IConfig } from '../../types.js';
 import {
     DispatcherInvokeTransport,
     EVENTS_DEPLOYED_HEADER,
+    EVENTS_DEADLINE_MARGIN_MS,
     EVENTS_DISPATCH_BATCH_PATH,
     EVENTS_DISPATCH_ERROR_HEADER,
     EVENTS_DISPATCH_PATH,
     EVENTS_ERROR_HEADER,
     EVENTS_HANDLED_HEADER,
+    EVENTS_HOLDER_HEADER,
+    EVENTS_INVOKE_TIMEOUT_MS,
+    EVENTS_WORKER_LEASE_FACTOR,
     EventsWorkerInvokerClient,
     INVOKE_CONNECTIONS,
     SCHEDULE_INVOKE_CONNECTIONS,
@@ -343,6 +347,46 @@ describe('DispatcherInvokeTransport with every connection busy', () => {
         held[INVOKE_CONNECTIONS].answer();
         await expect(after).resolves.toMatchObject({ status: 200 });
     });
+
+    it('rechecks the guard once a connection frees, and drops a superseded call', async () => {
+        const { transport, held, answerAll } = await saturated();
+
+        let current = true;
+        const guard = vi.fn(async () => current);
+        const waiting = transport.send({ ...CALL, beforeSend: guard });
+        current = false;
+        held[0].answer();
+
+        await expect(waiting).resolves.toEqual({
+            status: null,
+            error: 'invocation superseded',
+        });
+        expect(guard).toHaveBeenCalledTimes(1);
+        expect(held).toHaveLength(INVOKE_CONNECTIONS);
+        await answerAll();
+    });
+
+    it('fails a call whose guard throws after the wait, and frees its slot', async () => {
+        const { transport, held, answerAll } = await saturated();
+
+        const waiting = transport.send({
+            ...CALL,
+            beforeSend: async () => {
+                throw new Error('lease store down');
+            },
+        });
+        held[0].answer();
+        await expect(waiting).rejects.toThrow('lease store down');
+        expect(held).toHaveLength(INVOKE_CONNECTIONS);
+
+        await answerAll();
+        const after = transport.send(CALL);
+        await vi.waitFor(() =>
+            expect(held).toHaveLength(INVOKE_CONNECTIONS + 1),
+        );
+        held[INVOKE_CONNECTIONS].answer();
+        await expect(after).resolves.toMatchObject({ status: 200 });
+    });
 });
 
 describe('DispatcherInvokeTransport schedule lane', () => {
@@ -767,6 +811,138 @@ describe('DispatcherInvokeTransport batches', () => {
         ]);
     });
 
+    it('leaves a call superseded while gathered out of the batch', async () => {
+        const { fetchImpl, batches, singles } = streamingFetch();
+        const transport = transportFor(fetchImpl, { batchWindowMs: 20 });
+        let current = true;
+        const sent = [
+            transport.send(CALL),
+            transport.send({ ...CALL, beforeSend: async () => current }),
+            transport.send({ ...CALL, script: 'evw-other' }),
+        ];
+        current = false;
+        await vi.waitFor(() => expect(batches).toHaveLength(1));
+        expect(batches[0].body.calls.map((call) => call.script)).toEqual([
+            'evw-test',
+            'evw-other',
+        ]);
+        await expect(sent[1]).resolves.toEqual({
+            status: null,
+            error: 'invocation superseded',
+        });
+        batches[0].answer({ i: 0, status: 200, handled: true });
+        batches[0].answer({ i: 1, status: 200, handled: true });
+        await expect(Promise.all([sent[0], sent[2]])).resolves.toEqual([
+            { status: 200, handled: true },
+            { status: 200, handled: true },
+        ]);
+        expect(singles).toHaveLength(0);
+    });
+
+    it('sends nothing when every gathered call was superseded', async () => {
+        const fetchImpl = vi.fn(
+            stubFetch(200, { [EVENTS_HANDLED_HEADER]: '1' }),
+        );
+        const transport = transportFor(fetchImpl as unknown as FetchImpl);
+        const superseded = { ...CALL, beforeSend: async () => false };
+        await expect(
+            Promise.all([
+                transport.send(superseded),
+                transport.send(superseded),
+            ]),
+        ).resolves.toEqual([
+            { status: null, error: 'invocation superseded' },
+            { status: null, error: 'invocation superseded' },
+        ]);
+        expect(fetchImpl).not.toHaveBeenCalled();
+    });
+
+    it('fails only the call whose guard throws at flush', async () => {
+        const { fetchImpl, batches, singles } = streamingFetch();
+        const transport = transportFor(fetchImpl);
+        const failing = transport.send({
+            ...CALL,
+            beforeSend: async () => {
+                throw new Error('lease store down');
+            },
+        });
+        const kept = transport.send(CALL);
+        await expect(failing).rejects.toThrow('lease store down');
+        // One call left, so it goes alone.
+        await expect(kept).resolves.toEqual({ status: 200, handled: true });
+        expect(batches).toHaveLength(0);
+        expect(singles).toHaveLength(1);
+    });
+
+    it('rechecks the guard before resending a batch call on its own', async () => {
+        const urls: string[] = [];
+        let current = true;
+        const fetchImpl = (async (url: string) => {
+            urls.push(url);
+            if (url.endsWith(EVENTS_DISPATCH_BATCH_PATH)) {
+                // Superseded while the batch was out.
+                current = false;
+                return new Response('no-such-route', {
+                    status: 404,
+                    headers: {
+                        [EVENTS_DISPATCH_ERROR_HEADER]: 'no-such-route',
+                    },
+                });
+            }
+            return new Response(null, {
+                status: 200,
+                headers: { [EVENTS_HANDLED_HEADER]: '1' },
+            });
+        }) as unknown as FetchImpl;
+        const transport = transportFor(fetchImpl);
+
+        await expect(
+            Promise.all([
+                transport.send({ ...CALL, beforeSend: async () => current }),
+                transport.send(CALL),
+            ]),
+        ).resolves.toEqual([
+            { status: null, error: 'invocation superseded' },
+            { status: 200, handled: true },
+        ]);
+        expect(urls.map((url) => new URL(url).pathname)).toEqual([
+            EVENTS_DISPATCH_BATCH_PATH,
+            EVENTS_DISPATCH_PATH,
+        ]);
+    });
+
+    it('answers a schedule run superseded in the batch as the early check does', async () => {
+        const { fetchImpl, batches } = streamingFetch();
+        const client = new EventsWorkerInvokerClient({
+            events: { invokeTimeoutMs: 5_000 },
+        } as unknown as IConfig);
+        client.setTransport(transportFor(fetchImpl, { batchWindowMs: 20 }));
+        let current = true;
+        const guard = vi.fn(async () => current);
+
+        const run = client.invoke(REQUEST, {
+            lane: 'schedule',
+            beforeSend: guard,
+        });
+        const other = client.invoke(REQUEST);
+        const another = client.invoke(REQUEST);
+        await vi.waitFor(() => expect(guard).toHaveBeenCalledTimes(1));
+        current = false;
+
+        await vi.waitFor(() => expect(batches).toHaveLength(1));
+        expect(batches[0].body.calls).toHaveLength(2);
+        await expect(run).resolves.toEqual(
+            await client.invoke(REQUEST, { beforeSend: async () => false }),
+        );
+        await expect(run).resolves.toMatchObject({
+            outcome: 'unavailable',
+            error: 'invocation superseded',
+        });
+        batches[0].answer({ i: 0, status: 200, handled: true });
+        batches[0].answer({ i: 1, status: 200, handled: true });
+        await Promise.all([other, another]);
+    });
+
     it('builds each body when the batch goes out', async () => {
         const { fetchImpl, batches } = streamingFetch();
         const transport = transportFor(fetchImpl);
@@ -823,6 +999,26 @@ describe('DispatcherInvokeTransport batches', () => {
 });
 
 describe('EventsWorkerInvokerClient invoke options', () => {
+    it('does not send a superseded invocation', async () => {
+        const client = makeClient();
+        const send = vi.fn(async () => ({ status: 200, handled: true }));
+        client.setTransport({ send });
+        const result = await client.invoke(REQUEST, { beforeSend: async () => false });
+        expect(result.outcome).toBe('unavailable');
+        expect(send).not.toHaveBeenCalled();
+    });
+
+    it('rechecks before resending after a deployment', async () => {
+        const client = makeClient();
+        let current = true;
+        const send = vi.fn(async () => ({ status: null, dispatchReason: 'missing' }));
+        client.setTransport({ send });
+        client.setMissHandler(async () => { current = false; return 'deployed'; });
+        const result = await client.invoke(REQUEST, { beforeSend: async () => current });
+        expect(result.outcome).toBe('unavailable');
+        expect(send).toHaveBeenCalledTimes(1);
+    });
+
     it('stamps the event as each attempt goes out', async () => {
         const bodies: string[] = [];
         const client = makeClient();
@@ -1302,3 +1498,217 @@ describe('outcomeForStatus', () => {
         },
     );
 });
+
+describe('EventsWorkerInvokerClient overall deadline', () => {
+    afterEach(() => {
+        vi.useRealTimers();
+    });
+
+    const LEASE_MS = EVENTS_INVOKE_TIMEOUT_MS * EVENTS_WORKER_LEASE_FACTOR;
+
+    /**
+     * A transport on a fake clock: each send costs what `cost` says, and
+     * answers a miss until the deployed header, then a handled 200.
+     */
+    const timedTransport = (cost: (deployed: boolean) => number) => {
+        const sends: Array<{ deployed: boolean; timeoutMs: number }> = [];
+        const transport = {
+            send: async (call: {
+                deployed?: boolean;
+                timeoutMs: number;
+            }): Promise<unknown> => {
+                const deployed = call.deployed === true;
+                sends.push({ deployed, timeoutMs: call.timeoutMs });
+                // A send never outlasts its own timeout.
+                vi.advanceTimersByTime(
+                    Math.min(cost(deployed), call.timeoutMs * 1.5),
+                );
+                return deployed
+                    ? { status: 200, handled: true }
+                    : {
+                          status: null,
+                          dispatchReason: 'missing',
+                          error: 'dispatcher: missing (404)',
+                      };
+            },
+        };
+        return { transport, sends };
+    };
+
+    const run = async (
+        cost: (deployed: boolean) => number,
+        deployMs: number,
+    ) => {
+        vi.useFakeTimers({ toFake: ['Date'] });
+        const { transport, sends } = timedTransport(cost);
+        const client = makeClient();
+        client.setTransport(transport as never);
+        client.setMissHandler(async () => {
+            vi.advanceTimersByTime(deployMs);
+            return 'deployed';
+        });
+        const started = Date.now();
+        const result = await client.invoke(REQUEST);
+        return { result, sends, elapsed: Date.now() - started };
+    };
+
+    it('leaves a fast miss as it was: a full-timeout resend', async () => {
+        const { result, sends } = await run(() => 100, 2_000);
+        expect(result).toEqual({ outcome: 'settled', status: 200 });
+        expect(sends).toEqual([
+            { deployed: false, timeoutMs: EVENTS_INVOKE_TIMEOUT_MS },
+            { deployed: true, timeoutMs: EVENTS_INVOKE_TIMEOUT_MS },
+        ]);
+    });
+
+    it('shortens the resend after a slow deploy, so the call ends before the lease', async () => {
+        // A miss that took 12 s, a deploy that took 30 s, and a resend that
+        // would use everything it is given.
+        const { result, sends, elapsed } = await run(
+            (deployed) => (deployed ? 1e9 : 12_000),
+            30_000,
+        );
+        expect(result.outcome).toBe('settled');
+        expect(sends[1].deployed).toBe(true);
+        expect(sends[1].timeoutMs).toBeLessThan(EVENTS_INVOKE_TIMEOUT_MS);
+        expect(elapsed).toBeLessThanOrEqual(
+            LEASE_MS - EVENTS_DEADLINE_MARGIN_MS,
+        );
+    });
+
+    it('gives up on a deploy that never settles before the lease, leaving it running', async () => {
+        vi.useFakeTimers();
+        const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+        const { transport, sends } = timedTransport(() => 0);
+        const client = makeClient();
+        client.setTransport(transport as never);
+        let rejectDeploy!: (err: Error) => void;
+        client.setMissHandler(
+            () =>
+                new Promise<string>((_resolve, reject) => {
+                    rejectDeploy = reject;
+                }),
+        );
+        let finished: unknown = null;
+        const pending = client.invoke(REQUEST).then((r) => (finished = r));
+
+        // Up to where the call must have ended, and no further.
+        await vi.advanceTimersByTimeAsync(LEASE_MS - EVENTS_DEADLINE_MARGIN_MS);
+        expect(finished).toMatchObject({
+            outcome: 'unavailable',
+            status: null,
+        });
+        await pending;
+        expect(sends).toHaveLength(1);
+        // The deploy was not cancelled; its late failure is logged, not thrown.
+        rejectDeploy(new Error('stalled'));
+        await vi.advanceTimersByTimeAsync(0);
+        expect(warn).toHaveBeenCalledWith(
+            '[events] deploy failed late',
+            expect.any(Error),
+        );
+        warn.mockRestore();
+    });
+
+    it('does not resend when the deploy leaves less than the margin', async () => {
+        const { result, sends } = await run(
+            () => 100,
+            LEASE_MS - EVENTS_DEADLINE_MARGIN_MS * 2 + 1_000,
+        );
+        expect(sends).toHaveLength(1);
+        expect(result).toMatchObject({ outcome: 'unavailable', status: null });
+    });
+});
+
+describe('the holder of a user scope on the wire', () => {
+    const HOLDER = 'user-uuid-1';
+
+    it('sends the holder header on a single invoke, and none for an app scope', async () => {
+        const seen: Array<Record<string, string>> = [];
+        const fetchImpl = (async (_url: string, init?: RequestInit) => {
+            seen.push((init?.headers ?? {}) as Record<string, string>);
+            return new Response(null, {
+                status: 200,
+                headers: { [EVENTS_HANDLED_HEADER]: '1' },
+            });
+        }) as unknown as FetchImpl;
+        const client = makeClient();
+        client.setTransport(
+            new DispatcherInvokeTransport('http://dispatcher', 's', {
+                fetchImpl,
+                batchSize: 1,
+            }),
+        );
+
+        await client.invoke({ ...REQUEST, holder: HOLDER });
+        await client.invoke(REQUEST);
+
+        expect(seen[0][EVENTS_HOLDER_HEADER]).toBe(HOLDER);
+        expect(EVENTS_HOLDER_HEADER in seen[1]).toBe(false);
+    });
+
+    it('puts a holder field on a batch call of a user scope only', async () => {
+        const bodies: Array<{ calls: Array<Record<string, unknown>> }> = [];
+        const fetchImpl = (async (_url: string, init?: RequestInit) => {
+            bodies.push(JSON.parse(String(init?.body)));
+            return new Response(
+                '{"i":0,"status":200,"handled":true}\n{"i":1,"status":200,"handled":true}\n',
+                { status: 200 },
+            );
+        }) as unknown as FetchImpl;
+        const transport = new DispatcherInvokeTransport(
+            'http://dispatcher',
+            's',
+            { fetchImpl },
+        );
+
+        await Promise.all([
+            transport.send({ ...CALL, holder: HOLDER }),
+            transport.send(CALL),
+        ]);
+
+        expect(bodies).toHaveLength(1);
+        expect(bodies[0].calls[0].holder).toBe(HOLDER);
+        expect('holder' in bodies[0].calls[1]).toBe(false);
+    });
+
+    it('hands the holder to the miss handler, and nothing for an app scope', async () => {
+        const seen: Array<{ holder?: string }> = [];
+        const client = makeClient();
+        client.setTransport(
+            new DispatcherInvokeTransport('http://dispatcher', 's', {
+                fetchImpl: missUntilDeployedFetch([]),
+                batchSize: 1,
+            }),
+        );
+        client.setMissHandler(async (_appUid, _script, options) => {
+            seen.push(options);
+            return 'deployed';
+        });
+
+        await client.invoke({ ...REQUEST, holder: HOLDER });
+        await client.invoke(REQUEST);
+
+        expect(seen[0].holder).toBe(HOLDER);
+        expect('holder' in seen[1]).toBe(false);
+    });
+
+    it('keeps the holder out of the body the script sees', async () => {
+        const bodies: string[] = [];
+        const client = makeClient();
+        client.setTransport({
+            send: async (call) => {
+                bodies.push(call.body);
+                expect(call.holder).toBe(HOLDER);
+                return { status: 200, handled: true };
+            },
+        });
+        await client.invoke({ ...REQUEST, holder: HOLDER });
+        expect(Object.keys(JSON.parse(bodies[0])).sort()).toEqual([
+            'ctx',
+            'event',
+            'handler',
+            'token',
+        ]);
+    });
+});

src/backend/clients/events/EventsWorkerInvokerClient.ts

@@ -35,6 +35,7 @@ import { PuterClient } from '../types.js';
  *     x-puter-internal-auth:  <internal secret>
  *     x-puter-events-script:  <script the handler set deploys as>
  *     x-puter-events-app:     <app uid, for the deploy-on-miss callback>
+ *     x-puter-events-holder:  <holder uuid of a user scope; absent for app scope>
  *     x-puter-events-key:     <key derived for that script>
  *     { handler, event, ctx, token }
  *
@@ -48,7 +49,7 @@ import { PuterClient } from '../types.js';
  *
  *     POST <events dispatcher>/invoke-batch
  *     x-puter-internal-auth:  <internal secret>
- *     { calls: [{ script, appUid, key, deployed?, body, waitMs }] }
+ *     { calls: [{ script, appUid, holder?, key, deployed?, body, waitMs }] }
  *
  * The dispatcher runs a few at a time, in order, and streams NDJSON: `{ i,
  * started: true }` when a call goes to its worker, then `{ i, status, handled?,
@@ -127,6 +128,12 @@ const PLATFORM_ERROR_CODES = new Set([
  */
 export const EVENTS_DEPLOYED_HEADER = 'x-puter-events-deployed';
 
+/**
+ * Names the user whose scope a script belongs to, so a miss deploys it from
+ * their handlers. Absent for an app's own scope.
+ */
+export const EVENTS_HOLDER_HEADER = 'x-puter-events-holder';
+
 /**
  * Dispatch-error reasons this backend can resolve itself by deploying, rather
  * than wait on the rehydrate callback finding a backend behind the dispatcher's
@@ -150,6 +157,11 @@ const ALREADY_DEPLOYED_MISS_REASONS = new Set(['deploy-timeout']);
 /** Whose call asked for the deploy, for the share of deploys it may take. */
 export interface WorkerMissOptions {
     lane?: InvokeLane;
+    /**
+     * Holder uuid of the user scope the script belongs to; absent for app
+     * scope.
+     */
+    holder?: string;
 }
 
 /** What a self-deploy attempt did, and to which app/script it applies. */
@@ -159,9 +171,55 @@ export type WorkerMissHandler = (
     options: WorkerMissOptions,
 ) => Promise<'deployed' | string>;
 
+/**
+ * `work`'s result, or null once `ms` has passed. The work keeps running, and a
+ * failure after the cutoff is logged since nothing else would see it.
+ */
+const withinTime = async <T>(
+    work: Promise<T>,
+    ms: number,
+): Promise<T | null> => {
+    let timedOut = false;
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    const limit = new Promise<null>((resolve) => {
+        timer = setTimeout(
+            () => {
+                timedOut = true;
+                resolve(null);
+            },
+            Math.max(0, ms),
+        );
+    });
+    void (async () => {
+        try {
+            await work;
+        } catch (err) {
+            if (timedOut) console.warn('[events] deploy failed late', err);
+        }
+    })();
+    try {
+        return await Promise.race([work, limit]);
+    } finally {
+        clearTimeout(timer);
+    }
+};
+
 /** How long a handler has to answer before the attempt is abandoned. */
 export const EVENTS_INVOKE_TIMEOUT_MS = 30_000;
 
+/**
+ * How many invoke timeouts a delivery's worker lease lasts. The lease store
+ * reads this, and `invoke()` keeps a whole call, deploy and resend included,
+ * inside it.
+ */
+export const EVENTS_WORKER_LEASE_FACTOR = 2;
+
+/**
+ * Left unspent at the end of the lease, and the least a resend is worth
+ * starting with: below it the call is given up as `unavailable` and retried.
+ */
+export const EVENTS_DEADLINE_MARGIN_MS = 5_000;
+
 /**
  * Connections held open to the dispatcher, so a busy fleet is not
  * re-handshaking. Also how many calls one transport makes at once: a call past
@@ -194,6 +252,8 @@ export interface WorkerInvokeRequest {
     /** Script the app's current handler set deploys as. */
     script: string;
     appUid: string;
+    /** Holder uuid, when the handler lives in a user scope. */
+    holder?: string;
     handler: string;
     /** The subscriber's app session token. */
     token: string;
@@ -207,6 +267,8 @@ export interface WorkerInvokeRequest {
 export interface EventsInvokeCall {
     script: string;
     appUid: string;
+    /** Holder uuid of the user scope the script belongs to. */
+    holder?: string;
     /** Value the script compares against its own invoke-key binding. */
     key: string;
     /** Serialized `{ handler, event, ctx, token }`. */
@@ -220,6 +282,11 @@ export interface EventsInvokeCall {
      * connection first, so a send time stamped into it is the real one.
      */
     render?: () => string;
+    /**
+     * Rechecked by a transport that waits before sending; false drops the call
+     * with {@link supersededAnswer}.
+     */
+    beforeSend?: () => Promise<boolean>;
 }
 
 /** What one attempt at delivering an invocation came back with. */
@@ -255,10 +322,7 @@ export interface EventsInvokeTransport {
  * handler); retried like `retriable` but never the handler's fault.
  */
 export type WorkerInvokeOutcome =
-    | 'settled'
-    | 'terminal'
-    | 'retriable'
-    | 'unavailable';
+    'settled' | 'terminal' | 'retriable' | 'unavailable';
 
 export interface WorkerInvokeResult {
     outcome: WorkerInvokeOutcome;
@@ -275,6 +339,8 @@ export interface WorkerInvokeResult {
 /** How one invocation is sent. */
 export interface WorkerInvokeOptions {
     lane?: InvokeLane;
+    /** Rechecked before each send, including a resend after deployment. */
+    beforeSend?: () => Promise<boolean>;
     /** Applied to the event as each attempt is sent. */
     stampEvent?: (event: unknown) => unknown;
 }
@@ -282,6 +348,12 @@ export interface WorkerInvokeOptions {
 const NO_TRANSPORT =
     'no events dispatcher configured (url and internal secret)';
 
+/** What a call whose `beforeSend` said no answers instead of being sent. */
+const supersededAnswer = (): EventsInvokeAnswer => ({
+    status: null,
+    error: 'invocation superseded',
+});
+
 export class EventsWorkerInvokerClient extends PuterClient {
     /** Set only where invocations do not leave the process — local development. */
     #transport: EventsInvokeTransport | null = null;
@@ -329,25 +401,68 @@ export class EventsWorkerInvokerClient extends PuterClient {
                 ctx: request.ctx,
                 token: request.token,
             });
-        const send = (deployed: boolean): Promise<EventsInvokeAnswer> =>
-            transport.send({
+        const timeoutMs = this.#timeoutMs();
+        // The whole call, deploy and resend included, ends before the lease a
+        // delivery holds would let it be claimed again mid-run.
+        // A short configured timeout gets a proportionally short margin.
+        const margin = Math.min(EVENTS_DEADLINE_MARGIN_MS, timeoutMs / 2);
+        const deadline =
+            Date.now() + timeoutMs * EVENTS_WORKER_LEASE_FACTOR - margin;
+        const send = async (
+            deployed: boolean,
+            sendTimeoutMs = timeoutMs,
+        ): Promise<EventsInvokeAnswer> => {
+            if (options.beforeSend && !(await options.beforeSend()))
+                return supersededAnswer();
+            return transport.send({
                 script: request.script,
                 appUid: request.appUid,
+                ...(request.holder ? { holder: request.holder } : {}),
                 key: request.key,
                 body: render(),
-                timeoutMs: this.#timeoutMs(),
+                timeoutMs: sendTimeoutMs,
                 ...(deployed ? { deployed: true } : {}),
                 ...(options.lane ? { lane: options.lane } : {}),
                 ...(stampEvent ? { render } : {}),
+                ...(options.beforeSend
+                    ? { beforeSend: options.beforeSend }
+                    : {}),
             });
+        };
+
+        // A send may wait for a connection for half its timeout before the
+        // run's own timeout starts, so it is given what is left divided by that.
+        const resend = (): Promise<EventsInvokeAnswer> | null => {
+            const remaining = deadline - Date.now();
+            if (remaining < margin) return null;
+            return send(
+                true,
+                Math.floor(
+                    Math.min(
+                        timeoutMs,
+                        remaining / (1 + CONNECTION_WAIT_SHARE),
+                    ),
+                ),
+            );
+        };
+        const outOfTime = (): WorkerInvokeResult => ({
+            outcome: 'unavailable',
+            status: null,
+            error: 'out of time to resend after deploy',
+        });
 
         let result = await send(false);
         if (this.#missHandler && selfDeployable(result)) {
-            const outcome = await this.#missHandler(
-                request.appUid,
-                request.script,
-                { lane: options.lane },
+            // The deploy may be shared with other callers, so it is left
+            // running when this call runs out of time for it.
+            const outcome = await withinTime(
+                this.#missHandler(request.appUid, request.script, {
+                    lane: options.lane,
+                    ...(request.holder ? { holder: request.holder } : {}),
+                }),
+                deadline - Date.now() - margin,
             );
+            if (outcome === null) return outOfTime();
             if (outcome !== 'deployed')
                 return {
                     outcome: 'unavailable',
@@ -355,7 +470,9 @@ export class EventsWorkerInvokerClient extends PuterClient {
                     error: `deploy: ${outcome}`,
                     ...(outcome === DEPLOY_BUSY ? { deployBusy: true } : {}),
                 };
-            result = await send(true);
+            const resent = await resend();
+            if (!resent) return outOfTime();
+            result = resent;
         } else if (
             result.status === null &&
             result.dispatchReason &&
@@ -363,7 +480,9 @@ export class EventsWorkerInvokerClient extends PuterClient {
         ) {
             // No deploy to trigger — just give propagation the one retry
             // it usually needs, without spending an upload on it.
-            result = await send(true);
+            const resent = await resend();
+            if (!resent) return outOfTime();
+            result = resent;
         }
 
         const { status, handled, error, timedOut, retryAfterMs } = result;
@@ -434,6 +553,8 @@ export class EventsWorkerInvokerClient extends PuterClient {
 interface BatchedCall {
     call: EventsInvokeCall;
     resolve: (answer: EventsInvokeAnswer) => void;
+    /** For a `beforeSend` that threw. */
+    reject: (err: unknown) => void;
     /** When its wait for a connection began, for what is left of it. */
     waitingSince: number;
 }
@@ -504,9 +625,14 @@ export class DispatcherInvokeTransport implements EventsInvokeTransport {
                 error: 'no free connection to the events dispatcher',
             };
         try {
-            if (this.#batchSize === 1) return await this.#sendOne(call);
-            return await new Promise<EventsInvokeAnswer>((resolve) => {
-                this.#batch.push({ call, resolve, waitingSince });
+            if (this.#batchSize === 1) {
+                // The wait for a connection may have outlived the call.
+                if (call.beforeSend && !(await call.beforeSend()))
+                    return supersededAnswer();
+                return await this.#sendOne(call);
+            }
+            return await new Promise<EventsInvokeAnswer>((resolve, reject) => {
+                this.#batch.push({ call, resolve, reject, waitingSince });
                 if (this.#batch.length >= this.#batchSize) this.#flush();
                 else
                     this.#batchTimer ??= setTimeout(
@@ -526,6 +652,12 @@ export class DispatcherInvokeTransport implements EventsInvokeTransport {
         const batch = this.#batch;
         this.#batch = [];
         if (batch.length === 0) return;
+        if (batch.some(({ call }) => call.beforeSend))
+            void this.#sendStillCurrent(batch);
+        else this.#sendGathered(batch);
+    }
+
+    #sendGathered(batch: BatchedCall[]): void {
         if (batch.length === 1 || Date.now() < this.#batchUnsupportedUntil) {
             for (const { call, resolve } of batch)
                 void this.#sendOne(call).then(resolve);
@@ -534,6 +666,26 @@ export class DispatcherInvokeTransport implements EventsInvokeTransport {
         void this.#sendBatch(batch);
     }
 
+    /** Drops calls superseded while they were gathered, then sends the rest. */
+    async #sendStillCurrent(batch: BatchedCall[]): Promise<void> {
+        const checked = await Promise.all(
+            batch.map(async (entry) => {
+                if (!entry.call.beforeSend) return entry;
+                try {
+                    if (await entry.call.beforeSend()) return entry;
+                    entry.resolve(supersededAnswer());
+                } catch (err) {
+                    entry.reject(err);
+                }
+                return null;
+            }),
+        );
+        const current = checked.filter(
+            (entry): entry is BatchedCall => entry !== null,
+        );
+        if (current.length > 0) this.#sendGathered(current);
+    }
+
     /** One call on the single route. */
     async #sendOne(call: EventsInvokeCall): Promise<EventsInvokeAnswer> {
         try {
@@ -546,6 +698,9 @@ export class DispatcherInvokeTransport implements EventsInvokeTransport {
                         'x-puter-internal-auth': this.#secret,
                         'x-puter-events-script': call.script,
                         'x-puter-events-app': call.appUid,
+                        ...(call.holder
+                            ? { [EVENTS_HOLDER_HEADER]: call.holder }
+                            : {}),
                         'x-puter-events-key': call.key,
                         ...(call.deployed
                             ? { [EVENTS_DEPLOYED_HEADER]: '1' }
@@ -585,13 +740,15 @@ export class DispatcherInvokeTransport implements EventsInvokeTransport {
         let open = batch.length;
         const answered = batch.map(() => false);
         const timers: ReturnType<typeof setTimeout>[] = [];
-        const settle = (i: number, answer: EventsInvokeAnswer): void => {
+        const finish = (i: number, done: (entry: BatchedCall) => void) => {
             if (answered[i]) return;
             answered[i] = true;
             clearTimeout(timers[i]);
-            batch[i].resolve(answer);
+            done(batch[i]);
             if (--open === 0) hangUp.abort();
         };
+        const settle = (i: number, answer: EventsInvokeAnswer): void =>
+            finish(i, (entry) => entry.resolve(answer));
         const settleRest = (answer: EventsInvokeAnswer): void => {
             for (let i = 0; i < batch.length; i++) settle(i, answer);
         };
@@ -610,6 +767,7 @@ export class DispatcherInvokeTransport implements EventsInvokeTransport {
             calls: batch.map(({ call }, i) => ({
                 script: call.script,
                 appUid: call.appUid,
+                ...(call.holder ? { holder: call.holder } : {}),
                 key: call.key,
                 ...(call.deployed ? { deployed: true } : {}),
                 body: call.render ? call.render() : call.body,
@@ -673,8 +831,22 @@ export class DispatcherInvokeTransport implements EventsInvokeTransport {
                 this.#batchUnsupportedUntil =
                     Date.now() + BATCH_UNSUPPORTED_RETRY_MS;
                 batch.forEach(({ call }, i) => {
-                    if (!answered[i])
+                    if (answered[i]) return;
+                    const { beforeSend } = call;
+                    if (!beforeSend) {
                         void this.#sendOne(call).then((a) => settle(i, a));
+                        return;
+                    }
+                    // The batch round trip may have outlived the call.
+                    void (async () => {
+                        try {
+                            if (!(await beforeSend()))
+                                return settle(i, supersededAnswer());
+                        } catch (err) {
+                            return finish(i, (entry) => entry.reject(err));
+                        }
+                        settle(i, await this.#sendOne(call));
+                    })();
                 });
                 return;
             }

src/backend/controllers/events/EventsController.ts

@@ -64,6 +64,8 @@ const EVENTS_SCRIPT_REGEX = new RegExp(`^${EVENTS_WORKER_PREFIX}[a-f0-9]{32}$`);
 
 /** Matches the edge dispatcher's own validation of the app uid it forwards. */
 const APP_UID_REGEX = /^app-[A-Za-z0-9_-]{1,64}$/;
+/** A user uuid. */
+const HOLDER_REGEX = /^[A-Za-z0-9-]{1,64}$/;
 
 @Controller('/events')
 export class EventsController extends PuterController {
@@ -132,7 +134,8 @@ export class EventsController extends PuterController {
      *
      * Stateless: no subscription, no stored position, nothing written. The
      * cursor comes back to the caller and goes out again as `cursor` (or
-     * `after`, the name it first shipped under).
+     * `after`, the name it first shipped under). `from=end` with no cursor
+     * starts at the newest row instead of the oldest.
      */
     @Get('/fetch', {
         subdomain: 'api',
@@ -143,9 +146,16 @@ export class EventsController extends PuterController {
     async fetch(req: Request, res: Response): Promise<void> {
         const actor = this.#requireActor(req);
         const query = (req.query ?? {}) as Record<string, unknown>;
+        const from = query.from as 'start' | 'end' | undefined;
+        if (from !== undefined && from !== 'start' && from !== 'end') {
+            throw new HttpError(400, '`from` must be `start` or `end`', {
+                legacyCode: 'bad_request',
+            });
+        }
 
         const page = await this.services.events.fetchMissed(actor, {
             subject: typeof query.subject === 'string' ? query.subject : '',
+            from,
             cursor: typeof query.cursor === 'string' ? query.cursor : undefined,
             after: typeof query.after === 'string' ? query.after : undefined,
             limit: normalizeLimit(query.limit, {
@@ -226,6 +236,17 @@ export class EventsController extends PuterController {
         });
     }
 
+    @Post('/schedules/update', {
+        subdomain: 'api',
+        requireAuth: true,
+        allowAccessToken: true,
+    })
+    async updateSchedule(req: Request, res: Response): Promise<void> {
+        const actor = this.#requireActor(req);
+        const { scheduleId, changes } = bodyRecord(req);
+        res.json(await this.#schedules().update(actor, scheduleId, changes));
+    }
+
     /**
      * POST /events/schedules/remove — end one schedule. An id the caller does
      * not hold reads as absent.
@@ -402,6 +423,7 @@ export class EventsController extends PuterController {
             handlers: await this.services.events.listHandlers(actor, {
                 appUid:
                     typeof query.appUid === 'string' ? query.appUid : undefined,
+                scope: query.scope,
             }),
         });
     }
@@ -500,6 +522,15 @@ export class EventsController extends PuterController {
             throw new HttpError(400, 'Missing or invalid `script`/`appUid`', {
                 legacyCode: 'bad_request',
             });
+        // Absent or empty is the app's own scope.
+        const holder = body.holder === undefined ? '' : body.holder;
+        if (
+            typeof holder !== 'string' ||
+            !(holder === '' || HOLDER_REGEX.test(holder))
+        )
+            throw new HttpError(400, 'Invalid `holder`', {
+                legacyCode: 'bad_request',
+            });
 
         const deployer = this.#eventsWorkerDeployer();
         if (!deployer.enabled) {
@@ -507,7 +538,13 @@ export class EventsController extends PuterController {
             return;
         }
 
-        const outcome = await deployer.ensure(appUid, script);
+        const scope = await deployer.scopeFor(appUid, holder);
+        if (!scope) {
+            res.status(404).json({ deployed: false, reason: 'no-holder' });
+            return;
+        }
+
+        const outcome = await deployer.ensure(scope, script);
         if (outcome === 'deployed') {
             res.json({ deployed: true });
             return;
@@ -540,14 +577,22 @@ export class EventsController extends PuterController {
     override onServerStart(): void {
         const deployer = this.#eventsWorkerDeployer();
         if (!deployer.enabled) return;
+        this.services.events.useEagerDeploy((scope, script) =>
+            deployer.deployEagerly(scope, script),
+        );
         if (this.config.workers?.localServer) {
             this.services.events.useWorkerTransport(
                 new LocalEventsInvokeTransport(this.services, deployer),
             );
             return;
         }
-        this.services.events.useWorkerMissHandler((appUid, script, options) =>
-            deployer.ensure(appUid, script, options),
+        this.services.events.useWorkerMissHandler(
+            async (appUid, script, options) => {
+                const scope = await deployer.scopeFor(appUid, options.holder);
+                return scope
+                    ? deployer.ensure(scope, script, options)
+                    : 'no-holder';
+            },
         );
     }
 

src/backend/controllers/events/limits.test.ts

@@ -34,12 +34,21 @@ import {
     EVENTS_DURABLE_SUBSCRIPTIONS_MAX,
     EVENTS_DURABLE_SUBSCRIPTIONS_PER_APP,
     EVENTS_DURABLE_SUBSCRIPTIONS_PER_USER,
+    EVENTS_HANDLER_PUBLISH_LIMIT,
+    EVENTS_HANDLER_SOURCE_MAX_BYTES,
+    EVENTS_HANDLERS_PER_APP,
     EVENTS_KV_HANDLES_PER_APP,
     EVENTS_KV_HANDLES_PER_USER,
     EVENTS_KV_FILTER_EVALUATIONS_PER_EVENT,
     EVENTS_KV_MATCHED_SUBSCRIPTIONS_PER_EVENT,
     EVENTS_SINGLE_DELIVERY_LIMIT,
+    EVENTS_USER_HANDLERS_PER_SCOPE,
+    EVENTS_USER_SCOPE_SOURCE_MAX_BYTES,
+    EVENTS_USER_WORKER_DEPLOYS_PER_HOUR,
+    EVENTS_WORKER_DEPLOYS_PER_HOUR,
     EVENTS_WORKER_INVOCATION_LIMIT,
+    EVENTS_WORKER_SOURCE_MAX_BYTES,
+    RENTED_UNITS_PER_USER,
     limitFor,
     tiered,
     type TieredLimit,
@@ -183,3 +192,42 @@ describe('the delivery budgets', () => {
         }
     });
 });
+
+describe('the handler limits', () => {
+    it('pins the app-scope numbers the quotas page lists', () => {
+        expect(EVENTS_HANDLERS_PER_APP).toBe(100);
+        expect(EVENTS_HANDLER_SOURCE_MAX_BYTES).toBe(64 * 1024);
+        expect(EVENTS_WORKER_SOURCE_MAX_BYTES).toBe(5 * 1024 * 1024);
+        expect(EVENTS_WORKER_DEPLOYS_PER_HOUR).toBe(30);
+        expect(EVENTS_HANDLER_PUBLISH_LIMIT.limit).toBe(60);
+        expect(EVENTS_HANDLER_PUBLISH_LIMIT.window).toBe(60_000);
+    });
+
+    it('pins the user-scope numbers the quotas page lists', () => {
+        expect(EVENTS_USER_HANDLERS_PER_SCOPE).toBe(20);
+        expect(EVENTS_USER_SCOPE_SOURCE_MAX_BYTES).toBe(1024 * 1024);
+        expect(EVENTS_USER_WORKER_DEPLOYS_PER_HOUR).toBe(10);
+    });
+
+    it('keeps a user scope tighter than an app scope', () => {
+        expect(EVENTS_USER_HANDLERS_PER_SCOPE).toBeLessThan(
+            EVENTS_HANDLERS_PER_APP,
+        );
+        expect(EVENTS_USER_SCOPE_SOURCE_MAX_BYTES).toBeLessThan(
+            EVENTS_WORKER_SOURCE_MAX_BYTES,
+        );
+        expect(EVENTS_USER_WORKER_DEPLOYS_PER_HOUR).toBeLessThan(
+            EVENTS_WORKER_DEPLOYS_PER_HOUR,
+        );
+    });
+
+    it('pins the rented-unit cap by plan', () => {
+        expect(RENTED_UNITS_PER_USER.limit).toBe(100);
+        expect(limitFor(RENTED_UNITS_PER_USER, DEFAULT_FREE_SUBSCRIPTION)).toBe(
+            16,
+        );
+        expect(limitFor(RENTED_UNITS_PER_USER, DEFAULT_TEMP_SUBSCRIPTION)).toBe(
+            16,
+        );
+    });
+});

src/backend/controllers/events/limits.ts

@@ -269,6 +269,12 @@ export const KV_SHARE_NOTIFY_LIMITS = [
  */
 export const EVENTS_HANDLERS_PER_APP = 100;
 
+/**
+ * Handlers one user may hold in their own scope of one app. Each is a script of
+ * its own, so the cap is tighter than the app's.
+ */
+export const EVENTS_USER_HANDLERS_PER_SCOPE = 20;
+
 /** Longest a serialized handler may be. */
 export const EVENTS_HANDLER_SOURCE_MAX_BYTES = 64 * 1024;
 
@@ -280,6 +286,9 @@ export const EVENTS_HANDLER_SOURCE_MAX_BYTES = 64 * 1024;
  */
 export const EVENTS_WORKER_SOURCE_MAX_BYTES = 5 * 1024 * 1024;
 
+/** Source one user scope may hold, all its handlers combined. */
+export const EVENTS_USER_SCOPE_SOURCE_MAX_BYTES = 1024 * 1024;
+
 /**
  * Deploys one app's events worker may trigger per hour.
  *
@@ -289,6 +298,16 @@ export const EVENTS_WORKER_SOURCE_MAX_BYTES = 5 * 1024 * 1024;
  */
 export const EVENTS_WORKER_DEPLOYS_PER_HOUR = 30;
 
+/** Deploys one user scope may trigger per hour. */
+export const EVENTS_USER_WORKER_DEPLOYS_PER_HOUR = 10;
+
+/**
+ * Units one user may rent at once: ordinary workers, user scopes, and the
+ * events workers of apps they own. Only creating a unit is refused; holdings
+ * over the cap are kept.
+ */
+export const RENTED_UNITS_PER_USER = tiered(100, 16, 16);
+
 /**
  * Handlers one `publishAll` may carry. A build step publishes its whole set in
  * one call, and the set is capped by what an app may hold anyway.

src/backend/controllers/events/scheduleRoutes.test.ts

@@ -75,6 +75,7 @@ const fakeSchedules = () =>
             total: 3,
         })),
         get: vi.fn(async () => view),
+        update: vi.fn(async () => view),
         remove: vi.fn(async () => {}),
         receivePeerChanges: vi.fn(async () => ({ applied: 2 })),
         prepareSendAt: vi.fn(),
@@ -129,6 +130,10 @@ const routes: Array<[string, (response: Response) => Promise<void>]> = [
         (r) =>
             events.getSchedule(req({ params: { scheduleId: SCHEDULE_ID } }), r),
     ],
+    [
+        'POST /events/schedules/update',
+        (r) => events.updateSchedule(req({ body: { scheduleId: SCHEDULE_ID, changes: { every: '2h' } } }), r),
+    ],
     [
         'POST /events/schedules/remove',
         (r) =>
@@ -250,6 +255,16 @@ describe('with services.schedules', () => {
         expect(sent.body).toEqual(view);
     });
 
+    it('updates through update and answers its view', async () => {
+        const schedules = fakeSchedules();
+        setSchedules(schedules);
+        const { response, sent } = res();
+        const changes = { every: '2h' };
+        await events.updateSchedule(req({ body: { scheduleId: SCHEDULE_ID, changes } }), response);
+        expect(schedules.update).toHaveBeenCalledWith(actor, SCHEDULE_ID, changes);
+        expect(sent.body).toEqual(view);
+    });
+
     it('removes through remove and answers {}', async () => {
         const schedules = fakeSchedules();
         setSchedules(schedules);

src/backend/controllers/events/updateSchedule.test.ts

@@ -0,0 +1,77 @@
+import type { Request, Response } from 'express';
+import { describe, expect, it } from 'vitest';
+import { makeActor } from '../../core/actor.js';
+import type {
+    ScheduleServiceContract,
+    ScheduleView,
+} from '../../core/schedules.js';
+import { EventsController } from './EventsController.js';
+
+const actor = makeActor({
+    user: { id: 1, uuid: 'user-1', username: 'user1' } as never,
+});
+const request = (body: unknown) => ({ actor, body }) as Request;
+const controller = (schedules?: Pick<ScheduleServiceContract, 'update'>) =>
+    new EventsController(
+        {} as never,
+        {} as never,
+        {} as never,
+        { schedules } as never,
+        {} as never,
+    );
+
+describe('update schedule route contract', () => {
+    it('answers events_disabled when schedules are unavailable', async () => {
+        await expect(
+            controller().updateSchedule(
+                request({ scheduleId: 'id', changes: {} }),
+                {} as Response,
+            ),
+        ).rejects.toMatchObject({
+            legacyCode: 'events_disabled',
+            statusCode: 503,
+            noAlarm: true,
+        });
+    });
+
+    it('passes the actor, id and changes through and returns the updated view', async () => {
+        const view = {
+            scheduleId: 'id',
+            kind: 'recurring',
+            state: 'suspended',
+        } as ScheduleView;
+        const changes = { cron: '0 9 * * *', tz: 'UTC' };
+        const calls: unknown[][] = [];
+        const events = controller({
+            update: async (...args) => {
+                calls.push(args);
+                return view;
+            },
+        });
+        let sent: unknown;
+        await events.updateSchedule(request({ scheduleId: 'id', changes }), {
+            json: (value: unknown) => {
+                sent = value;
+            },
+        } as Response);
+        expect(calls).toEqual([[actor, 'id', changes]]);
+        expect(sent).toBe(view);
+    });
+
+    it('preserves validation and sending errors from the implementation', async () => {
+        const error = {
+            code: 'events_schedule_sending',
+            message: 'Already sending',
+        };
+        await expect(
+            controller({
+                update: async () => {
+                    throw error;
+                },
+            }).updateSchedule(
+                request({ scheduleId: 'id', changes: {} }),
+                {} as Response,
+            ),
+        ).rejects.toBe(error);
+    });
+});

src/backend/controllers/events/workerDeploy.test.ts

@@ -25,14 +25,35 @@
 
 import MockRedis from 'ioredis-mock';
 import { describe, expect, it } from 'vitest';
-import type { EventsInvokeCall } from '../../clients/events/EventsWorkerInvokerClient.js';
-import { EVENTS_WORKER_DEPLOYS_PER_HOUR } from './limits.js';
+import type { fetch as undiciFetch } from 'undici';
+import {
+    DispatcherInvokeTransport,
+    EVENTS_DEPLOYED_HEADER,
+    EVENTS_DISPATCH_ERROR_HEADER,
+    EVENTS_HANDLED_HEADER,
+    EventsWorkerInvokerClient,
+    type EventsInvokeCall,
+} from '../../clients/events/EventsWorkerInvokerClient.js';
+import { INTERNAL_DEPLOY_TARGET } from '../../drivers/workers/WorkerDriver.js';
+import {
+    EVENTS_USER_WORKER_DEPLOYS_PER_HOUR,
+    EVENTS_WORKER_DEPLOYS_PER_HOUR,
+} from './limits.js';
 import {
     EventsWorkerDeployer,
     LocalEventsInvokeTransport,
+    type EventsDeployOptions,
     type EventsDeployOutcome,
 } from './workerDeploy.js';
-import { eventsWorkerScript } from '../../services/events/workerRuntime.js';
+import {
+    eventsWorkerScript,
+    userHandlerScript,
+} from '../../services/events/workerRuntime.js';
+import {
+    appHandlerScope,
+    hashContent,
+    type HandlerScope,
+} from '../../stores/events/EventHandlerStore.js';
 import { handlerSetHash } from '../../services/events/workerSource.js';
 import type { IConfig } from '../../types.js';
 
@@ -51,14 +72,22 @@ interface Owner {
 type Layers = ConstructorParameters<typeof EventsWorkerDeployer>[0];
 
 /** Stub layers whose only real dependency is a fresh redis mock. */
-const makeLayers = (owners: Record<string, Owner | null>) => {
+const makeLayers = (
+    owners: Record<string, Owner | null>,
+    events: Record<string, unknown> = {},
+) => {
     const redis = new MockRedis.Cluster(['redis://localhost:7001']);
     const created: string[] = [];
+    const targets: Array<Record<string, unknown>> = [];
     /** Apps whose handler sources were read, once per read. */
     const sourceReads: string[] = [];
     const layers = {
         config: {
-            events: { workerRuntime: true, internalSecret: 'sekret' },
+            events: {
+                workerRuntime: true,
+                internalSecret: 'sekret',
+                ...events,
+            },
             // `#namespace()` needs a local-worker shape to resolve without
             // throwing — this stub never reaches a real Cloudflare or
             // Miniflare deploy either way.
@@ -68,7 +97,7 @@ const makeLayers = (owners: Record<string, Owner | null>) => {
         stores: {
             eventHandler: {
                 setForApp: async () => [{ name: 'h', sourceHash: SOURCE_HASH }],
-                allForApp: async (appUid: string) => {
+                allForApp: async ({ appUid }: { appUid: string }) => {
                     sourceReads.push(appUid);
                     return [
                         {
@@ -91,6 +120,18 @@ const makeLayers = (owners: Record<string, Owner | null>) => {
                 },
             },
             user: {
+                getByUuid: async (uuid: string) => {
+                    const owner = Object.values(owners).find(
+                        (o) => `uuid-${o?.ownerUserId}` === uuid,
+                    );
+                    if (!owner) return null;
+                    return {
+                        id: owner.ownerUserId,
+                        uuid,
+                        username: `user-${owner.ownerUserId}`,
+                        suspended: owner.suspended ?? false,
+                    };
+                },
                 getById: async (id: number) => {
                     const owner = Object.values(owners).find(
                         (o) => o?.ownerUserId === id,
@@ -108,8 +149,12 @@ const makeLayers = (owners: Record<string, Owner | null>) => {
         services: {},
         drivers: {
             workers: {
-                create: async (args: { workerName: string }) => {
+                create: async (args: {
+                    workerName: string;
+                    [INTERNAL_DEPLOY_TARGET]?: Record<string, unknown>;
+                }) => {
                     created.push(args.workerName);
+                    targets.push(args[INTERNAL_DEPLOY_TARGET] ?? {});
                     return { success: true, errors: [] };
                 },
             },
@@ -118,6 +163,7 @@ const makeLayers = (owners: Record<string, Owner | null>) => {
     return {
         layers: layers as unknown as Layers,
         created,
+        targets,
         redis,
         sourceReads,
     };
@@ -136,8 +182,8 @@ describe('EventsWorkerDeployer.ensure', () => {
         const deployer = new EventsWorkerDeployer(layers);
 
         const [a, b] = await Promise.all([
-            deployer.ensure('app-a', SCRIPT),
-            deployer.ensure('app-b', SCRIPT),
+            deployer.ensure(appHandlerScope('app-a'), SCRIPT),
+            deployer.ensure(appHandlerScope('app-b'), SCRIPT),
         ]);
         expect(a).toBe('deployed');
         expect(b).toBe('no-owner');
@@ -154,7 +200,9 @@ describe('EventsWorkerDeployer.ensure', () => {
             String(EVENTS_WORKER_DEPLOYS_PER_HOUR),
         );
 
-        expect(await deployer.ensure('app-c', SCRIPT)).toBe('throttled');
+        expect(await deployer.ensure(appHandlerScope('app-c'), SCRIPT)).toBe(
+            'throttled',
+        );
         expect(sourceReads).toEqual([]);
         expect(created).toEqual([]);
     });
@@ -169,16 +217,41 @@ describe('EventsWorkerDeployer.ensure', () => {
             '',
         );
 
-        expect(await deployer.ensure('app-e', stale)).toBe('stale');
+        expect(await deployer.ensure(appHandlerScope('app-e'), stale)).toBe(
+            'stale',
+        );
         expect(sourceReads).toEqual([]);
         const hour = new Date().toISOString().slice(0, 13);
         expect(await redis.get(`ev:deploys:{app-e}:${hour}`)).toBeNull();
     });
 
+    it('passes events.workerCpuMs to the deploy target', async () => {
+        const { layers, targets } = makeLayers(
+            { 'app-f': { ownerUserId: 6 } },
+            { workerCpuMs: 50 },
+        );
+        const deployer = new EventsWorkerDeployer(layers);
+        expect(await deployer.ensure(appHandlerScope('app-f'), SCRIPT)).toBe(
+            'deployed',
+        );
+        expect(targets[0]!.cpuMs).toBe(50);
+    });
+
+    it('passes no cpuMs when events.workerCpuMs is unset', async () => {
+        const { layers, targets } = makeLayers({ 'app-g': { ownerUserId: 7 } });
+        const deployer = new EventsWorkerDeployer(layers);
+        expect(await deployer.ensure(appHandlerScope('app-g'), SCRIPT)).toBe(
+            'deployed',
+        );
+        expect(targets[0]!.cpuMs).toBeUndefined();
+    });
+
     it('deploys normally under the cap', async () => {
         const { layers } = makeLayers({ 'app-d': { ownerUserId: 4 } });
         const deployer = new EventsWorkerDeployer(layers);
-        expect(await deployer.ensure('app-d', SCRIPT)).toBe('deployed');
+        expect(await deployer.ensure(appHandlerScope('app-d'), SCRIPT)).toBe(
+            'deployed',
+        );
     });
 });
 
@@ -209,16 +282,22 @@ describe('the schedules` deploy gate', () => {
     it('is skipped without schedules, or with schedules that have no gate', async () => {
         const { layers, created } = makeLayers({ 'app-x': { ownerUserId: 1 } });
         await expect(
-            new EventsWorkerDeployer(layers).ensure('app-x', SCRIPT, {
-                lane: 'schedule',
-            }),
+            new EventsWorkerDeployer(layers).ensure(
+                appHandlerScope('app-x'),
+                SCRIPT,
+                {
+                    lane: 'schedule',
+                },
+            ),
         ).resolves.toBe('deployed');
         const gateless = new EventsWorkerDeployer({
             ...layers,
             services: { ...layers.services, schedules: {} },
         } as unknown as Layers);
         await expect(
-            gateless.ensure('app-x', SCRIPT, { lane: 'schedule' }),
+            gateless.ensure(appHandlerScope('app-x'), SCRIPT, {
+                lane: 'schedule',
+            }),
         ).resolves.toBe('deployed');
         expect(created).toEqual([SCRIPT, SCRIPT]);
     });
@@ -227,11 +306,13 @@ describe('the schedules` deploy gate', () => {
         const { layers, created } = makeLayers({ 'app-x': { ownerUserId: 1 } });
         const { deployer, gated } = withGate(layers);
 
-        await expect(deployer.ensure('app-x', SCRIPT)).resolves.toBe(
-            'deployed',
-        );
         await expect(
-            deployer.ensure('app-x', SCRIPT, { lane: 'schedule' }),
+            deployer.ensure(appHandlerScope('app-x'), SCRIPT),
+        ).resolves.toBe('deployed');
+        await expect(
+            deployer.ensure(appHandlerScope('app-x'), SCRIPT, {
+                lane: 'schedule',
+            }),
         ).resolves.toBe('deployed');
         expect(gated).toEqual([
             { script: SCRIPT, capped: false },
@@ -245,11 +326,13 @@ describe('the schedules` deploy gate', () => {
         const { deployer } = withGate(layers, (capped) => capped);
 
         await expect(
-            deployer.ensure('app-x', SCRIPT, { lane: 'schedule' }),
+            deployer.ensure(appHandlerScope('app-x'), SCRIPT, {
+                lane: 'schedule',
+            }),
         ).resolves.toBe('busy');
-        await expect(deployer.ensure('app-x', SCRIPT)).resolves.toBe(
-            'deployed',
-        );
+        await expect(
+            deployer.ensure(appHandlerScope('app-x'), SCRIPT),
+        ).resolves.toBe('deployed');
         expect(created).toEqual([SCRIPT]);
     });
 
@@ -257,12 +340,12 @@ describe('the schedules` deploy gate', () => {
         const { layers, created } = makeLayers({ 'app-x': { ownerUserId: 1 } });
         const { deployer, gated } = withGate(layers, (capped) => capped);
 
-        const scheduled = deployer.ensure('app-x', SCRIPT, {
+        const scheduled = deployer.ensure(appHandlerScope('app-x'), SCRIPT, {
             lane: 'schedule',
         });
         const deliveries = [
-            deployer.ensure('app-x', SCRIPT),
-            deployer.ensure('app-x', SCRIPT),
+            deployer.ensure(appHandlerScope('app-x'), SCRIPT),
+            deployer.ensure(appHandlerScope('app-x'), SCRIPT),
         ];
         await expect(scheduled).resolves.toBe('busy');
         await expect(Promise.all(deliveries)).resolves.toEqual([
@@ -277,8 +360,8 @@ describe('the schedules` deploy gate', () => {
         const { layers, created } = makeLayers({ 'app-x': { ownerUserId: 1 } });
         const { deployer, gated } = withGate(layers, (capped) => capped);
 
-        const delivery = deployer.ensure('app-x', SCRIPT);
-        const scheduled = deployer.ensure('app-x', SCRIPT, {
+        const delivery = deployer.ensure(appHandlerScope('app-x'), SCRIPT);
+        const scheduled = deployer.ensure(appHandlerScope('app-x'), SCRIPT, {
             lane: 'schedule',
         });
         await expect(Promise.all([delivery, scheduled])).resolves.toEqual([
@@ -312,6 +395,7 @@ describe('LocalEventsInvokeTransport', () => {
                     resident = true;
                     return 'deployed';
                 },
+                scopeFor: async (appUid: string) => appHandlerScope(appUid),
             } as unknown as EventsWorkerDeployer,
         );
         let renders = 0;
@@ -329,3 +413,484 @@ describe('LocalEventsInvokeTransport', () => {
         expect(bodies).toEqual(['{"n":1}', '{"n":2}']);
     });
 });
+
+describe('deploy-on-miss of an evicted script', () => {
+    it('redeploys the evicted script, then resends the run with the deployed marker', async () => {
+        const { layers, created } = makeLayers({ 'app-m': { ownerUserId: 8 } });
+        // The namespace only has the script once the deploy lands: before
+        // that the dispatcher answers a miss.
+        let resident = false;
+        layers.drivers.workers.create = (async (args: {
+            workerName: string;
+        }) => {
+            created.push(args.workerName);
+            resident = true;
+            return { success: true, errors: [] };
+        }) as never;
+        const deployer = new EventsWorkerDeployer(layers);
+
+        const sent: boolean[] = [];
+        const fetchImpl = (async (_url: string, init?: RequestInit) => {
+            const headers = (init?.headers ?? {}) as Record<string, string>;
+            sent.push(headers[EVENTS_DEPLOYED_HEADER] === '1');
+            if (resident)
+                return new Response(null, {
+                    status: 200,
+                    headers: { [EVENTS_HANDLED_HEADER]: '1' },
+                });
+            return new Response(null, {
+                status: 404,
+                headers: { [EVENTS_DISPATCH_ERROR_HEADER]: 'missing' },
+            });
+        }) as unknown as typeof undiciFetch;
+
+        const client = new EventsWorkerInvokerClient({
+            events: { workerRuntime: true },
+        } as IConfig);
+        client.setTransport(
+            new DispatcherInvokeTransport('http://dispatcher', 's', {
+                fetchImpl,
+            }),
+        );
+        client.setMissHandler((appUid, script, options) =>
+            deployer.ensure(appHandlerScope(appUid), script, options),
+        );
+
+        const result = await client.invoke({
+            script: SCRIPT,
+            appUid: 'app-m',
+            handler: 'h',
+            token: 't',
+            key: 'k',
+            event: {},
+            ctx: {},
+        });
+
+        expect(result).toEqual({ outcome: 'settled', status: 200 });
+        expect(created).toEqual([SCRIPT]);
+        // One miss, then the resend carrying the deployed marker.
+        expect(sent).toEqual([false, true]);
+    });
+});
+
+// The redis mock is shared across tests, so each one uses its own app and code.
+let fresh = 0;
+const nextApp = () => `app-u${++fresh}`;
+const userScope = (holder: number, appUid: string) => ({ appUid, holder });
+const sourceN = (label: string) =>
+    `async () => { await ${label}${++fresh}(); }`;
+const scriptOf = (name: string, source: string) =>
+    userHandlerScript({ name, sourceHash: hashContent(source) }, '');
+
+type Sets = Record<number, Array<{ name: string; source: string }>>;
+
+/** Layers whose handler sets are per holder (0 is the app's own). */
+const withSets = (layers: Layers, sets: Sets) => {
+    const handlersOf = (scope: { appUid: string; holder: number }) =>
+        (sets[scope.holder] ?? []).map((h) => ({
+            appUid: scope.appUid,
+            name: h.name,
+            source: h.source,
+            sourceHash: hashContent(h.source),
+            createdAt: 0,
+            updatedAt: 0,
+        }));
+    const store = layers.stores.eventHandler as unknown as Record<
+        string,
+        unknown
+    >;
+    store.setForApp = async (scope: { appUid: string; holder: number }) =>
+        handlersOf(scope).map(({ name, sourceHash }) => ({ name, sourceHash }));
+    store.allForApp = async (scope: { appUid: string; holder: number }) =>
+        handlersOf(scope);
+};
+
+const holders = (...ids: number[]) =>
+    Object.fromEntries(
+        ids.map((id) => [`holder-${id}`, { ownerUserId: id }]),
+    ) as Record<string, Owner>;
+
+describe('EventsWorkerDeployer in a user scope', () => {
+    it('deploys the one handler whose script was asked for, as the holder', async () => {
+        const app = nextApp();
+        const a = sourceN('a');
+        const b = sourceN('b');
+        const { layers, created, targets } = makeLayers(holders(10));
+        withSets(layers, {
+            10: [
+                { name: 'a', source: a },
+                { name: 'b', source: b },
+            ],
+        });
+        const deployer = new EventsWorkerDeployer(layers);
+
+        const script = scriptOf('b', b);
+        expect(await deployer.ensure(userScope(10, app), script)).toBe(
+            'deployed',
+        );
+
+        expect(created).toEqual([script]);
+        const target = targets[0]!;
+        expect(target.tags).toEqual([`events-app:${app}`, 'user:uuid-10']);
+        // One handler's script: the other one's code is not in it.
+        expect(target.source).toContain(b);
+        expect(target.source).not.toContain(a);
+    });
+
+    it('answers a script no handler of the scope matches as stale, before the throttle', async () => {
+        const app = nextApp();
+        const { layers, redis, created } = makeLayers(holders(10));
+        withSets(layers, { 10: [{ name: 'a', source: sourceN('a') }] });
+        const deployer = new EventsWorkerDeployer(layers);
+
+        expect(
+            await deployer.ensure(
+                userScope(10, app),
+                scriptOf('b', sourceN('b')),
+            ),
+        ).toBe('stale');
+        expect(created).toEqual([]);
+        const hour = new Date().toISOString().slice(0, 13);
+        expect(await redis.get(`ev:deploys:{${app}}:10:${hour}`)).toBeNull();
+    });
+
+    it('answers a scope with no handlers as no-handlers', async () => {
+        const { layers } = makeLayers(holders(10));
+        withSets(layers, {});
+        const deployer = new EventsWorkerDeployer(layers);
+        expect(
+            await deployer.ensure(
+                userScope(10, nextApp()),
+                scriptOf('a', sourceN('a')),
+            ),
+        ).toBe('no-handlers');
+    });
+
+    it('does not deploy for a holder that is suspended or gone', async () => {
+        const source = sourceN('a');
+        const { layers, created } = makeLayers({
+            'holder-10': { ownerUserId: 10, suspended: true },
+        });
+        withSets(layers, {
+            10: [{ name: 'a', source }],
+            11: [{ name: 'a', source }],
+        });
+        const deployer = new EventsWorkerDeployer(layers);
+        const script = scriptOf('a', source);
+        const app = nextApp();
+
+        expect(await deployer.ensure(userScope(10, app), script)).toBe(
+            'no-owner',
+        );
+        expect(await deployer.ensure(userScope(11, app), script)).toBe(
+            'no-owner',
+        );
+        expect(created).toEqual([]);
+    });
+
+    it('gives each scope its own hourly cap, apart from the app scope', async () => {
+        const app = nextApp();
+        const source = sourceN('a');
+        const { layers, created } = makeLayers({
+            ...holders(10, 11),
+            [app]: { ownerUserId: 12 },
+        });
+        withSets(layers, {
+            0: [{ name: 'a', source }],
+            10: [{ name: 'a', source }],
+            11: [{ name: 'a', source }],
+        });
+        const deployer = new EventsWorkerDeployer(layers);
+        const script = scriptOf('a', source);
+
+        for (let i = 0; i < EVENTS_USER_WORKER_DEPLOYS_PER_HOUR; i++)
+            expect(await deployer.ensure(userScope(10, app), script)).toBe(
+                'deployed',
+            );
+        expect(await deployer.ensure(userScope(10, app), script)).toBe(
+            'throttled',
+        );
+        expect(created).toHaveLength(EVENTS_USER_WORKER_DEPLOYS_PER_HOUR);
+
+        // Another holder of the same app, and the app's own scope, still go.
+        expect(await deployer.ensure(userScope(11, app), script)).toBe(
+            'deployed',
+        );
+        expect(await deployer.ensure(appHandlerScope(app), script)).toBe(
+            'deployed',
+        );
+    });
+
+    it('collapses concurrent deploys of one script across holders into one upload', async () => {
+        const app = nextApp();
+        const source = sourceN('a');
+        const { layers, created } = makeLayers(holders(10, 11));
+        withSets(layers, {
+            10: [{ name: 'a', source }],
+            11: [{ name: 'a', source }],
+        });
+        const deployer = new EventsWorkerDeployer(layers);
+        const script = scriptOf('a', source);
+
+        await Promise.all([
+            deployer.ensure(userScope(10, app), script),
+            deployer.ensure(userScope(10, app), script),
+            deployer.ensure(userScope(11, app), script),
+            deployer.ensure(userScope(11, nextApp()), script),
+        ]);
+        expect(created).toHaveLength(1);
+    });
+
+    it('names a script for identical code the same under any holder and app', async () => {
+        const source = sourceN('a');
+        const { layers, created } = makeLayers(holders(10, 11));
+        withSets(layers, {
+            10: [{ name: '@x', source }],
+            11: [{ name: '@x', source }],
+        });
+        const deployer = new EventsWorkerDeployer(layers);
+        const script = scriptOf('@x', source);
+
+        expect(await deployer.ensure(userScope(10, nextApp()), script)).toBe(
+            'deployed',
+        );
+        expect(await deployer.ensure(userScope(11, nextApp()), script)).toBe(
+            'deployed',
+        );
+        expect(created).toEqual([script, script]);
+    });
+});
+
+describe('the deployed marker', () => {
+    const setup = () => {
+        const source = sourceN('a');
+        const made = makeLayers(holders(10, 11));
+        withSets(made.layers, {
+            10: [{ name: 'a', source }],
+            11: [{ name: 'a', source }],
+        });
+        return {
+            ...made,
+            deployer: new EventsWorkerDeployer(made.layers),
+            script: scriptOf('a', source),
+            app: nextApp(),
+        };
+    };
+
+    it('is left by a user-scope deploy with a ttl under a day', async () => {
+        const { deployer, redis, script, app } = setup();
+        await deployer.ensure(userScope(10, app), script);
+        const ttl = await redis.ttl(`ev:deployed:${script}`);
+        expect(ttl).toBeGreaterThan(0);
+        expect(ttl).toBeLessThan(24 * 60 * 60);
+    });
+
+    it('lets an eager deploy skip the upload another holder already made', async () => {
+        const { deployer, created, script, app } = setup();
+        expect(await deployer.deployEagerly(userScope(10, app), script)).toBe(
+            'deployed',
+        );
+        expect(await deployer.deployEagerly(userScope(11, app), script)).toBe(
+            'deployed',
+        );
+        expect(created).toEqual([script]);
+    });
+
+    it('spends no throttle on a skipped eager deploy', async () => {
+        const { deployer, redis, script, app } = setup();
+        await deployer.deployEagerly(userScope(10, app), script);
+        await deployer.deployEagerly(userScope(11, app), script);
+        const hour = new Date().toISOString().slice(0, 13);
+        expect(await redis.get(`ev:deploys:{${app}}:11:${hour}`)).toBeNull();
+    });
+
+    it('never skips a deploy-on-miss', async () => {
+        const { deployer, created, script, app } = setup();
+        await deployer.deployEagerly(userScope(10, app), script);
+        expect(await deployer.ensure(userScope(11, app), script)).toBe(
+            'deployed',
+        );
+        expect(created).toEqual([script, script]);
+    });
+
+    it('is not left by an app-scope deploy', async () => {
+        const app = nextApp();
+        const source = sourceN('a');
+        const { layers, redis, created } = makeLayers({
+            [app]: { ownerUserId: 4 },
+        });
+        withSets(layers, { 0: [{ name: 'a', source }] });
+        const deployer = new EventsWorkerDeployer(layers);
+        const script = scriptOf('a', source);
+        await deployer.ensure(appHandlerScope(app), script);
+        expect(created).toEqual([script]);
+        expect(await redis.get(`ev:deployed:${script}`)).toBeNull();
+    });
+
+    it('still deploys eagerly when the marker cannot be read', async () => {
+        const { deployer, redis, created, script, app } = setup();
+        await deployer.deployEagerly(userScope(10, app), script);
+        const get = redis.get.bind(redis);
+        redis.get = (async (key: string) => {
+            if (key.startsWith('ev:deployed:')) throw new Error('down');
+            return get(key);
+        }) as never;
+        expect(await deployer.deployEagerly(userScope(11, app), script)).toBe(
+            'deployed',
+        );
+        expect(created).toEqual([script, script]);
+    });
+});
+
+describe('scopeFor', () => {
+    it('reads no holder as the app scope, and resolves a uuid to the user scope', async () => {
+        const { layers } = makeLayers(holders(10));
+        const deployer = new EventsWorkerDeployer(layers);
+        expect(await deployer.scopeFor('app-u')).toEqual({
+            appUid: 'app-u',
+            holder: 0,
+        });
+        expect(await deployer.scopeFor('app-u', '')).toEqual({
+            appUid: 'app-u',
+            holder: 0,
+        });
+        expect(await deployer.scopeFor('app-u', 'uuid-10')).toEqual({
+            appUid: 'app-u',
+            holder: 10,
+        });
+        expect(await deployer.scopeFor('app-u', 'uuid-99')).toBeNull();
+    });
+});
+
+describe('LocalEventsInvokeTransport in a user scope', () => {
+    it('deploys the holder`s script on a miss and refuses an unknown holder', async () => {
+        const source = sourceN('a');
+        const { layers, created } = makeLayers(holders(10));
+        withSets(layers, { 10: [{ name: 'a', source }] });
+        const deployer = new EventsWorkerDeployer(layers);
+        let resident = false;
+        const transport = new LocalEventsInvokeTransport(
+            {
+                localworkerservice: {
+                    dispatchEventsWorker: async () => {
+                        if (!resident) return null;
+                        return new Response(null, {
+                            status: 200,
+                            headers: { 'x-puter-events-handled': '1' },
+                        });
+                    },
+                },
+            } as never,
+            {
+                ensure: async (
+                    scope: HandlerScope,
+                    script: string,
+                    options: EventsDeployOptions,
+                ) => {
+                    const outcome = await deployer.ensure(
+                        scope,
+                        script,
+                        options,
+                    );
+                    resident = outcome === 'deployed';
+                    return outcome;
+                },
+                scopeFor: (appUid: string, holder?: string) =>
+                    deployer.scopeFor(appUid, holder),
+            } as unknown as EventsWorkerDeployer,
+        );
+        const script = scriptOf('a', source);
+        const call: EventsInvokeCall = {
+            script,
+            appUid: nextApp(),
+            holder: 'uuid-10',
+            key: 'k',
+            body: '{}',
+            timeoutMs: 5000,
+        };
+
+        await expect(transport.send(call)).resolves.toMatchObject({
+            status: 200,
+        });
+        expect(created).toEqual([script]);
+
+        resident = false;
+        await expect(
+            transport.send({ ...call, holder: 'uuid-99' }),
+        ).resolves.toMatchObject({ status: null, error: 'deploy: no-holder' });
+        expect(created).toEqual([script]);
+    });
+});
+
+describe('concurrent eager deploys of one script', () => {
+    const setup = () => {
+        const source = sourceN('a');
+        const made = makeLayers(holders(10, 11));
+        withSets(made.layers, {
+            10: [{ name: 'a', source }],
+            11: [{ name: 'a', source }],
+        });
+        return {
+            ...made,
+            script: scriptOf('a', source),
+            app: nextApp(),
+        };
+    };
+
+    it('upload once when two holders publish the same new code together', async () => {
+        const { layers, created, script, app } = setup();
+        const deployer = new EventsWorkerDeployer(layers);
+
+        const outcomes = await Promise.all([
+            deployer.deployEagerly(userScope(10, app), script),
+            deployer.deployEagerly(userScope(11, app), script),
+        ]);
+
+        expect(outcomes).toEqual(['deployed', 'deployed']);
+        expect(created).toEqual([script]);
+    });
+
+    it('skip the upload when the marker appears while they wait on the gate', async () => {
+        const { layers, redis, created, script, app } = setup();
+        // Another node's deploy of the script finishes before the gate opens.
+        const gated = new EventsWorkerDeployer({
+            ...layers,
+            services: {
+                schedules: {
+                    gateDeploy: async (
+                        _script: string,
+                        _options: { capped: boolean },
+                        deploy: () => Promise<EventsDeployOutcome>,
+                    ) => {
+                        await redis.set(`ev:deployed:${script}`, '1');
+                        return deploy();
+                    },
+                },
+            },
+        } as unknown as Layers);
+
+        expect(
+            await gated.ensure(userScope(10, app), script, { eager: true }),
+        ).toBe('deployed');
+        expect(created).toEqual([]);
+        // A miss still uploads, whatever the marker says.
+        expect(await gated.ensure(userScope(11, app), script)).toBe('deployed');
+        expect(created).toEqual([script]);
+    });
+
+    it('make a miss that joins an eager deploy deploy after it', async () => {
+        const { layers, redis, created, script, app } = setup();
+        const deployer = new EventsWorkerDeployer(layers);
+        await redis.set(`ev:deployed:${script}`, '1');
+
+        const eager = deployer.ensure(userScope(10, app), script, {
+            eager: true,
+        });
+        const miss = deployer.ensure(userScope(11, app), script);
+
+        expect(await eager).toBe('deployed');
+        expect(await miss).toBe('deployed');
+        // The eager one skipped on the marker; the miss uploaded.
+        expect(created).toEqual([script]);
+    });
+});

src/backend/controllers/events/workerDeploy.ts

@@ -42,23 +42,33 @@ import {
     eventsInvokeKey,
     eventsWorkerScope,
     eventsWorkerScript,
+    userHandlerScript,
 } from '../../services/events/workerRuntime.js';
 import {
     generateEventsWorkerSource,
     handlerSetHash,
 } from '../../services/events/workerSource.js';
+import {
+    appHandlerScope,
+    type HandlerScope,
+} from '../../stores/events/EventHandlerStore.js';
 import type { puterStores } from '../../stores/index.js';
 import type { IConfig, LayerInstances } from '../../types.js';
-import { EVENTS_WORKER_DEPLOYS_PER_HOUR } from './limits.js';
+import {
+    EVENTS_USER_WORKER_DEPLOYS_PER_HOUR,
+    EVENTS_WORKER_DEPLOYS_PER_HOUR,
+} from './limits.js';
 
 /**
  * Deploys an app's events worker from its published handlers.
  *
  * Deployed the first time a delivery needs it and again on eviction — a publish
- * only writes rows. Scripts carry no worker token and no `subdomains` row: not
- * one of the owner's workers, not addressable from the internet, not listed or
- * deleted as if it were. A republished set leaves the old script behind rather
- * than deleting it; redeploying a still-live one is always safe.
+ * only writes rows (a user-scope publish also deploys eagerly). An app's scope
+ * is one script for the whole set; a user scope is one script per handler,
+ * deployed as the holder. Scripts carry no worker token and no `subdomains`
+ * row: not one of the owner's workers, not addressable from the internet, not
+ * listed or deleted as if it were. A republished set leaves the old script
+ * behind rather than deleting it; redeploying a still-live one is always safe.
  */
 
 /** Why a deploy could not happen, for the callers that answer differently. */
@@ -74,6 +84,11 @@ export type EventsDeployOutcome =
 /** Whose call asked for the deploy: a schedule run's is held to a share. */
 export interface EventsDeployOptions {
     lane?: InvokeLane;
+    /**
+     * A user-scope publish's deploy, which skips the upload when the script's
+     * deployed marker is already set. A deploy-on-miss is never eager.
+     */
+    eager?: boolean;
 }
 
 interface DeployLayers {
@@ -86,14 +101,22 @@ interface DeployLayers {
 }
 
 /**
- * `ev:deploys:{<appUid>}:<hour>` bucket TTL — comfortably past the hour it
- * counts.
+ * `ev:deploys:{<appUid>}[:<holder>]:<hour>` bucket TTL — comfortably past the
+ * hour it counts.
  */
 const DEPLOY_THROTTLE_TTL_SECONDS = 2 * 60 * 60;
 
+/** How long `ev:deployed:<script>` says a script was uploaded. Under a day. */
+const DEPLOYED_MARKER_TTL_SECONDS = 20 * 60 * 60;
+
+const deployedMarkerKey = (script: string): string => `ev:deployed:${script}`;
+
+const isUserScope = (scope: HandlerScope): boolean => scope.holder !== 0;
+
 interface InFlightDeploy {
     /** A schedule run's, which the region's deploy slots may refuse. */
     capped: boolean;
+    eager: boolean;
     promise: Promise<EventsDeployOutcome>;
 }
 
@@ -120,38 +143,76 @@ export class EventsWorkerDeployer {
     }
 
     /**
-     * Deploy `script`, which must be what the app's handlers currently hash to.
-     * A request for anything else is `stale` — the set moved on, and the next
-     * delivery resolves the new script rather than this one being revived.
+     * Deploy `script`, which must be what the scope's handlers currently hash
+     * to: the whole set for an app, one handler for a user scope. A request for
+     * anything else is `stale` — the handlers moved on, and the next delivery
+     * resolves the new script rather than this one being revived. Always
+     * uploads; a deploy-on-miss means whatever said it was there is wrong.
      */
     ensure(
-        appUid: string,
+        scope: HandlerScope,
         script: string,
         options: EventsDeployOptions = {},
     ): Promise<EventsDeployOutcome> {
-        const key = `${appUid}|${script}`;
+        // A user scope's script is the same bytes whoever holds it, so
+        // concurrent deploys of it from any holder or app are one.
+        const key = isUserScope(scope)
+            ? `user|${script}`
+            : `${scope.appUid}|${scope.holder}|${script}`;
         const capped = options.lane === 'schedule';
         const existing = this.#inFlight.get(key);
-        if (!existing) return this.#start(key, appUid, script, options);
+        if (!existing) return this.#start(key, scope, script, options);
+        // An eager deploy may have skipped the upload, which a miss must not
+        // take for done.
+        if (existing.eager && !options.eager)
+            return this.#afterEager(
+                existing.promise,
+                key,
+                scope,
+                script,
+                options,
+            );
         if (capped || !existing.capped) return existing.promise;
-        return this.#afterCapped(
-            existing.promise,
-            key,
-            appUid,
-            script,
-            options,
-        );
+        return this.#afterCapped(existing.promise, key, scope, script, options);
+    }
+
+    /**
+     * {@link ensure} for the deploy a user-scope publish starts, which skips the
+     * upload when another holder's deploy of the same script left its marker.
+     * Only this path reads the marker.
+     */
+    async deployEagerly(
+        scope: HandlerScope,
+        script: string,
+    ): Promise<EventsDeployOutcome> {
+        if (await this.#markedDeployed(script)) return 'deployed';
+        return this.ensure(scope, script, { eager: true });
+    }
+
+    /**
+     * The scope a script request names: the app's own, or the user scope of
+     * `holder` (a user uuid). Null for a holder that does not exist.
+     */
+    async scopeFor(
+        appUid: string,
+        holder?: string | null,
+    ): Promise<HandlerScope | null> {
+        if (!holder) return appHandlerScope(appUid);
+        const user = await this.#layers.stores.user.getByUuid(holder);
+        if (!user?.id) return null;
+        return { appUid, holder: Number(user.id) };
     }
 
     #start(
         key: string,
-        appUid: string,
+        scope: HandlerScope,
         script: string,
         options: EventsDeployOptions,
     ): Promise<EventsDeployOutcome> {
         const entry: InFlightDeploy = {
             capped: options.lane === 'schedule',
-            promise: this.#gated(appUid, script, options).finally(() => {
+            eager: options.eager === true,
+            promise: this.#gated(scope, script, options).finally(() => {
                 if (this.#inFlight.get(key) === entry)
                     this.#inFlight.delete(key);
             }),
@@ -160,6 +221,20 @@ export class EventsWorkerDeployer {
         return entry.promise;
     }
 
+    /** A miss that found an eager deploy in flight deploys after it. */
+    async #afterEager(
+        eager: Promise<EventsDeployOutcome>,
+        key: string,
+        scope: HandlerScope,
+        script: string,
+        options: EventsDeployOptions,
+    ): Promise<EventsDeployOutcome> {
+        await eager;
+        const current = this.#inFlight.get(key);
+        if (current && !current.eager) return current.promise;
+        return this.#start(key, scope, script, options);
+    }
+
     /**
      * A delivery that joined a schedule run's deploy: `busy` means no deploy
      * started, and a delivery is never refused a slot, so it asks again.
@@ -167,7 +242,7 @@ export class EventsWorkerDeployer {
     async #afterCapped(
         capped: Promise<EventsDeployOutcome>,
         key: string,
-        appUid: string,
+        scope: HandlerScope,
         script: string,
         options: EventsDeployOptions,
     ): Promise<EventsDeployOutcome> {
@@ -175,7 +250,7 @@ export class EventsWorkerDeployer {
         if (outcome !== 'busy') return outcome;
         const current = this.#inFlight.get(key);
         if (current && !current.capped) return current.promise;
-        return this.#start(key, appUid, script, options);
+        return this.#start(key, scope, script, options);
     }
 
     /**
@@ -185,11 +260,12 @@ export class EventsWorkerDeployer {
      * may be refused with `busy`. A delivery's deploy is never refused.
      */
     #gated(
-        appUid: string,
+        scope: HandlerScope,
         script: string,
         options: EventsDeployOptions,
     ): Promise<EventsDeployOutcome> {
-        const deploy = () => this.#deploy(appUid, script);
+        const deploy = () =>
+            this.#deploy(scope, script, options.eager === true);
         return (
             this.#layers.services.schedules?.gateDeploy?.(
                 script,
@@ -200,28 +276,55 @@ export class EventsWorkerDeployer {
     }
 
     async #deploy(
-        appUid: string,
+        handlerScope: HandlerScope,
         script: string,
+        eager: boolean,
     ): Promise<EventsDeployOutcome> {
+        const { appUid } = handlerScope;
         const { stores, drivers } = this.#layers;
-        const scope = eventsWorkerScope(this.#layers.config);
+        const backend = eventsWorkerScope(this.#layers.config);
+        const userScope = isUserScope(handlerScope);
 
         // Names and hashes are enough to tell a stale request, so the set's
         // sources are read and built only once the throttle has let it through.
-        const set = await stores.eventHandler.setForApp(appUid);
+        const set = await stores.eventHandler.setForApp(handlerScope);
         if (set.length === 0) return 'no-handlers';
         // Two apps that published byte-identical sets share one script, which
         // is sound: the source is the same, and everything per-app arrives with
-        // the invocation. Whoever deploys first owns it.
-        if (eventsWorkerScript(handlerSetHash(set), scope) !== script)
+        // the invocation. Whoever deploys first owns it. A user scope's script
+        // is one handler's, so it is shared the same way across holders.
+        const wanted = userScope
+            ? set.find((entry) => userHandlerScript(entry, backend) === script)
+            : undefined;
+        if (
+            userScope
+                ? !wanted
+                : eventsWorkerScript(handlerSetHash(set), backend) !== script
+        )
             return 'stale';
 
-        if (await this.#tooManyDeploysThisHour(appUid)) return 'throttled';
+        // Asked again inside the gate, where another deploy of this script may
+        // have just finished.
+        if (eager && userScope && (await this.#markedDeployed(script)))
+            return 'deployed';
 
-        const handlers = await stores.eventHandler.allForApp(appUid);
+        if (await this.#tooManyDeploysThisHour(handlerScope))
+            return 'throttled';
+
+        const all = await stores.eventHandler.allForApp(handlerScope);
+        const handlers = wanted
+            ? all.filter(
+                  (handler) =>
+                      handler.name === wanted.name &&
+                      handler.sourceHash === wanted.sourceHash,
+              )
+            : all;
         const generated = generateEventsWorkerSource(handlers);
         // The set can move between the two reads.
-        if (eventsWorkerScript(generated.setHash, scope) !== script)
+        if (
+            handlers.length === 0 ||
+            eventsWorkerScript(generated.setHash, backend) !== script
+        )
             return 'stale';
         if (generated.tooLarge) {
             console.error(
@@ -235,7 +338,7 @@ export class EventsWorkerDeployer {
                 generated.broken.join(', '),
             );
 
-        const owner = await this.#owner(appUid);
+        const owner = await this.#owner(handlerScope);
         if (!owner) return 'no-owner';
 
         const secret = this.#layers.config.events?.internalSecret;
@@ -264,6 +367,7 @@ export class EventsWorkerDeployer {
                         runtime: 'events',
                         source: generated.source,
                         omitOwnerToken: true,
+                        cpuMs: this.#layers.config.events?.workerCpuMs,
                         // What the script compares an invocation against.
                         // Derived from the script name, so a redeploy of
                         // the same set binds the same key.
@@ -294,34 +398,74 @@ export class EventsWorkerDeployer {
             );
             return 'failed';
         }
+        if (userScope) await this.#markDeployed(script);
         return 'deployed';
     }
 
-    /**
-     * Whether this app has already deployed `EVENTS_WORKER_DEPLOYS_PER_HOUR`
-     * times this hour. A flapping set (publish, remove, republish) provisions
-     * upstream on every miss, and this is the ceiling on that loop.
-     */
-    async #tooManyDeploysThisHour(appUid: string): Promise<boolean> {
-        const redis = this.#layers.clients.redis;
-        const hour = new Date().toISOString().slice(0, 13);
-        const key = `ev:deploys:{${appUid}}:${hour}`;
-        const count = await redis.incr(key);
-        if (count === 1) await redis.expire(key, DEPLOY_THROTTLE_TTL_SECONDS);
-        return count > EVENTS_WORKER_DEPLOYS_PER_HOUR;
+    async #markedDeployed(script: string): Promise<boolean> {
+        try {
+            return !!(await this.#layers.clients.redis.get(
+                deployedMarkerKey(script),
+            ));
+        } catch (err) {
+            console.warn('[events] deployed marker unreadable', err);
+            return false;
+        }
     }
 
-    /** The app owner, as an actor the deploy can run as. */
+    async #markDeployed(script: string): Promise<void> {
+        try {
+            await this.#layers.clients.redis.set(
+                deployedMarkerKey(script),
+                '1',
+                'EX',
+                DEPLOYED_MARKER_TTL_SECONDS,
+            );
+        } catch (err) {
+            console.warn('[events] could not mark a script deployed', err);
+        }
+    }
+
+    /**
+     * Whether this scope has already deployed its hourly cap this hour. A
+     * flapping set (publish, remove, republish) provisions upstream on every
+     * miss, and this is the ceiling on that loop. An app's counter is per app;
+     * a user scope has its own, so one user cannot spend another's.
+     */
+    async #tooManyDeploysThisHour(scope: HandlerScope): Promise<boolean> {
+        const redis = this.#layers.clients.redis;
+        const hour = new Date().toISOString().slice(0, 13);
+        const userScope = isUserScope(scope);
+        const key = userScope
+            ? `ev:deploys:{${scope.appUid}}:${scope.holder}:${hour}`
+            : `ev:deploys:{${scope.appUid}}:${hour}`;
+        const count = await redis.incr(key);
+        if (count === 1) await redis.expire(key, DEPLOY_THROTTLE_TTL_SECONDS);
+        return (
+            count >
+            (userScope
+                ? EVENTS_USER_WORKER_DEPLOYS_PER_HOUR
+                : EVENTS_WORKER_DEPLOYS_PER_HOUR)
+        );
+    }
+
+    /**
+     * The user a scope's deploy runs as, as an actor: the app's owner, or the
+     * holder of a user scope.
+     */
     async #owner(
-        appUid: string,
+        scope: HandlerScope,
     ): Promise<
         | (Actor & { user: { id: number; uuid: string; username: string } })
         | null
     > {
         const { stores } = this.#layers;
-        const app = await stores.app.getByUid(appUid);
-        const ownerUserId = Number(app?.owner_user_id);
-        if (!app || !Number.isFinite(ownerUserId)) return null;
+        let ownerUserId = scope.holder;
+        if (!isUserScope(scope)) {
+            const app = await stores.app.getByUid(scope.appUid);
+            ownerUserId = Number(app?.owner_user_id);
+            if (!app || !Number.isFinite(ownerUserId)) return null;
+        }
 
         const user = await stores.user.getById(ownerUserId);
         if (!user?.id || !user.uuid || !user.username || user.suspended)
@@ -402,11 +546,14 @@ export class LocalEventsInvokeTransport {
             const resident = await this.#dispatch(request(), call.timeoutMs);
             if (resident !== null) return resident;
 
-            const outcome = await this.#deployer.ensure(
+            const scope = await this.#deployer.scopeFor(
                 call.appUid,
-                call.script,
-                { lane: call.lane },
+                call.holder,
             );
+            if (!scope) return { status: null, error: 'deploy: no-holder' };
+            const outcome = await this.#deployer.ensure(scope, call.script, {
+                lane: call.lane,
+            });
             if (outcome !== 'deployed')
                 return {
                     status: null,

src/backend/controllers/homepage/HomepageController.test.ts

@@ -27,6 +27,7 @@ import type { Actor } from '../../core/actor.js';
 import { PuterRouter } from '../../core/http/PuterRouter.js';
 import { PuterServer } from '../../server.js';
 import { setupTestServer } from '../../testUtil.js';
+import { embedFrameAncestors } from './HomepageController.js';
 
 // ── Test harness ────────────────────────────────────────────────────
 //
@@ -529,3 +530,23 @@ describe('HomepageController GET /sw.js', () => {
         expect(route?.options.subdomain).toBe('');
     });
 });
+
+describe('embedFrameAncestors', () => {
+    const config = {
+        origin: 'https://example.test',
+        domain: 'example.test',
+        api_base_url: 'https://backend.example.test',
+    };
+
+    it('names a sibling subdomain that embeds the browser', () => {
+        expect(
+            embedFrameAncestors(config, 'https://sheets.example.test/doc/1'),
+        ).toBe("'self' https://sheets.example.test");
+    });
+
+    it('refuses the configured API host even off the api label', () => {
+        expect(
+            embedFrameAncestors(config, 'https://backend.example.test/x'),
+        ).toBe("'self'");
+    });
+});

src/backend/controllers/homepage/HomepageController.ts

@@ -22,6 +22,11 @@ import path from 'node:path';
 import { PuterController } from '../types.js';
 import { toAppShellView } from '../../util/appShellView.js';
 import type { PuterRouter } from '../../core/http/PuterRouter';
+import {
+    isReservedSubdomain,
+    subdomainLabelOf,
+} from '../../core/http/middleware/hostRedirects.js';
+import type { IConfig } from '../../types';
 import type {
     PuterHomepageService,
     PageMeta,
@@ -43,9 +48,9 @@ const APP_LANDING_LIMIT = {
 };
 
 /**
- * App descriptions can run long; search snippets and social cards want a
- * short blurb. Collapses whitespace, then cuts at a word boundary with an
- * ellipsis so the result never exceeds `APP_META_DESCRIPTION_MAX`.
+ * App descriptions can run long; search snippets and social cards want a short
+ * blurb. Collapses whitespace, then cuts at a word boundary with an ellipsis so
+ * the result never exceeds `APP_META_DESCRIPTION_MAX`.
  */
 export function appMetaDescription(text: string): string {
     const clean = text.replace(/\s+/g, ' ').trim();
@@ -56,6 +61,53 @@ export function appMetaDescription(text: string): string {
     return `${cut.replace(/[\s,;:.!?…—-]+$/, '')}…`;
 }
 
+/**
+ * `frame-ancestors` for the app browser embed. A wildcard over `*.<domain>`
+ * would also admit user-hosted sites whenever the hosting domains sit under it,
+ * so the embedding page is named exactly, from the request's referrer. Only a
+ * single label under `<domain>` qualifies, and not one this server answers
+ * itself (the API, WebDAV, SDK and native-app hosts).
+ */
+export function embedFrameAncestors(
+    config: Pick<
+        IConfig,
+        | 'origin'
+        | 'domain'
+        | 'api_base_url'
+        | 'static_hosting_domain'
+        | 'static_hosting_domain_alt'
+        | 'private_app_hosting_domain'
+        | 'private_app_hosting_domain_alt'
+    >,
+    referer: string | undefined,
+): string {
+    const gui = new URL(config.origin ?? `https://${config.domain}`);
+    let parent: URL;
+    try {
+        parent = new URL(referer ?? '');
+    } catch {
+        return "'self'";
+    }
+    const host = parent.hostname.toLowerCase();
+    const label = subdomainLabelOf(host, config.domain);
+    const hostingDomains = [
+        config.static_hosting_domain,
+        config.static_hosting_domain_alt,
+        config.private_app_hosting_domain,
+        config.private_app_hosting_domain_alt,
+    ]
+        .map((d) => (d ?? '').toLowerCase().split(':')[0])
+        .filter(Boolean);
+    const allowed =
+        parent.protocol === gui.protocol &&
+        parent.port === gui.port &&
+        label !== undefined &&
+        !isReservedSubdomain(label) &&
+        host !== new URL(config.api_base_url).hostname &&
+        !hostingDomains.some((d) => host === d || host.endsWith(`.${d}`));
+    return allowed ? `'self' ${parent.origin}` : "'self'";
+}
+
 /**
  * Routes that render the Puter GUI shell, plus a catch-all static fallback
  * under `<gui_assets_root>/src` for non-dist/src paths (images, fonts, lib
@@ -105,6 +157,27 @@ export class HomepageController extends PuterController {
 
         router.get('/', {}, (req, res) => sendShell(req, res));
 
+        router.get('/embed/apps', {}, async (req, res) => {
+            // SDK bootstrap parameters must not change this page's account or API origin.
+            // Checked on the raw URL; `req.query` drops pairs past the parser's limit.
+            if (req.originalUrl.includes('?')) {
+                res.redirect('/embed/apps');
+                return;
+            }
+            res.removeHeader('X-Frame-Options');
+            res.setHeader(
+                'Content-Security-Policy',
+                `frame-ancestors ${embedFrameAncestors(this.config, req.get('referer'))}`,
+            );
+            res.setHeader('Cache-Control', 'no-store');
+            // Shown to visitors without a session; a signed-in embed fetches
+            // its own list, so a failure here only costs signed-out visitors.
+            const guestApps = await this.services.recommendedApps
+                .getRecommendedApps()
+                .catch((): Array<Record<string, unknown>> => []);
+            res.send(homepage.renderAppBrowserEmbed({ guestApps }));
+        });
+
         router.get('/settings', {}, (req, res) => sendShell(req, res));
         router.get('/settings/*splat', {}, (req, res) => sendShell(req, res));
 

src/backend/controllers/oidc/OIDCController.test.ts

@@ -244,7 +244,10 @@ describe('OIDCController GET /auth/oidc/providers', () => {
         await callRoute('get', '/auth/oidc/providers', makeReq({}), res);
         // We configured a single `custom` provider; the live service
         // walks the config and returns its id.
-        expect(captured.body).toEqual({ providers: ['custom'] });
+        expect(captured.body).toEqual({
+            providers: ['custom'],
+            signupOidcOnly: false,
+        });
     });
 });
 

src/backend/controllers/oidc/OIDCController.ts

@@ -396,9 +396,12 @@ export class OIDCController extends PuterController {
                 },
             },
             async (_req: Request, res: Response) => {
-                const providers =
-                    await this.services.oidc.getEnabledProviderIds();
-                res.json({ providers });
+                const [providers, policy] = await Promise.all([
+                    this.services.oidc.getEnabledProviderIds(),
+                    this.services.signup.signupPolicy(),
+                ]);
+                // The signup window drops its email form when this is set.
+                res.json({ providers, signupOidcOnly: policy.oidcOnly });
             },
         );
 

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/controllers/static/StaticAssetsController.test.ts

@@ -19,8 +19,9 @@
 
 import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
+import type { AddressInfo } from 'node:net';
 import path from 'node:path';
-import type { Request, Response } from 'express';
+import express, { type Request, type Response } from 'express';
 import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it, vi } from 'vitest';
 import { PuterRouter } from '../../core/http/PuterRouter.js';
 import type { RouteDescriptor } from '../../core/http/types.js';
@@ -111,6 +112,7 @@ const callGetHandler = async (
     let captured: { filename?: string; root?: string } = {};
     const req = {} as Request;
     const res = {
+        setHeader: vi.fn(),
         sendFile: vi.fn((filename: string, opts: { root: string }) => {
             captured = { filename, root: opts.root };
         }),
@@ -238,6 +240,48 @@ describe('StaticAssetsController puterjs_root', () => {
     });
 });
 
+// ── push-sw.js caching ──────────────────────────────────────────────
+
+/** Serves the route's handler over real HTTP and returns the response. */
+const fetchThroughExpress = async (router: PuterRouter, routePath: string) => {
+    const route = findRoute(router, 'get', routePath);
+    if (!route) throw new Error(`No GET ${routePath} registered`);
+    const app = express();
+    app.get(routePath, (req, res, next) => route.handler(req, res, next));
+    const listener = app.listen(0);
+    await new Promise((resolve) => listener.once('listening', resolve));
+    try {
+        const { port } = listener.address() as AddressInfo;
+        return await fetch(`http://127.0.0.1:${port}${routePath}`);
+    } finally {
+        listener.close();
+    }
+};
+
+describe('StaticAssetsController push-sw.js', () => {
+    it.each([
+        ['client_libs_root', 'puter.js/push-sw.js'],
+        ['puterjs_root', 'push-sw.js'],
+    ] as const)(
+        'lets the CDN keep it for five minutes from %s',
+        async (configKey, file) => {
+            const root = makeTempDir();
+            mkdirSync(path.dirname(path.join(root, file)), { recursive: true });
+            writeFileSync(path.join(root, file), '/* worker */');
+            const router = buildController({ [configKey]: root });
+
+            for (const route of ['/push-sw.js', '/v2/push-sw.js']) {
+                const response = await fetchThroughExpress(router, route);
+                expect(response.status).toBe(200);
+                expect(response.headers.get('cache-control')).toBe(
+                    'public, max-age=0, s-maxage=300',
+                );
+                expect(await response.text()).toBe('/* worker */');
+            }
+        },
+    );
+});
+
 // ── gui_assets_root ─────────────────────────────────────────────────
 
 describe('StaticAssetsController gui_assets_root', () => {

src/backend/controllers/static/StaticAssetsController.ts

@@ -23,6 +23,9 @@ import path from 'node:path';
 import { PuterController } from '../types.js';
 import type { PuterRouter } from '../../core/http/PuterRouter';
 
+// Sites import push-sw.js by URL, so the CDN refetches it within five minutes.
+const PUSH_WORKER_CACHE_CONTROL = 'public, max-age=0, s-maxage=300';
+
 /**
  * Static asset routes.
  *
@@ -58,6 +61,7 @@ export class StaticAssetsController extends PuterController {
             // `/v2/push-sw.js` is the path older docs gave.
             for (const route of ['/push-sw.js', '/v2/push-sw.js']) {
                 router.get(route, { subdomain: 'js' }, (_req, res) => {
+                    res.setHeader('Cache-Control', PUSH_WORKER_CACHE_CONTROL);
                     res.sendFile('puter.js/push-sw.js', { root });
                 });
             }
@@ -108,6 +112,10 @@ export class StaticAssetsController extends PuterController {
                 });
                 for (const route of ['/push-sw.js', '/v2/push-sw.js']) {
                     router.get(route, { subdomain: 'js' }, (_req, res) => {
+                        res.setHeader(
+                            'Cache-Control',
+                            PUSH_WORKER_CACHE_CONTROL,
+                        );
                         res.sendFile('push-sw.js', { root: puterjsRoot });
                     });
                 }

src/backend/core/http/middleware/hostRedirects.test.ts

@@ -187,9 +187,9 @@ describe('createUserSubdomainNotFound', () => {
     });
 
     it('passes through reserved subdomains (api, js, native apps, etc.)', () => {
-        // `api`, `js`, `dav`, `docs`, `developer`, `editor`, `pdf`,
+        // `api`, `js`, `dav`, `docs`, `developer`, `about`, `apps`,
         // `puter-app-icons`, etc. all pass through.
-        for (const sub of ['api', 'js', 'docs', 'editor', 'puter-app-icons']) {
+        for (const sub of ['api', 'js', 'docs', 'about', 'puter-app-icons']) {
             const { out, next } = run(
                 createUserSubdomainNotFound(config),
                 makeReq({
@@ -865,13 +865,13 @@ describe('createNativeAppStatic', () => {
 
     beforeAll(() => {
         root = mkdtempSync(nodePath.join(tmpdir(), 'native-apps-'));
-        mkdirSync(nodePath.join(root, 'editor', 'assets'), { recursive: true });
+        mkdirSync(nodePath.join(root, 'about', 'assets'), { recursive: true });
         writeFileSync(
-            nodePath.join(root, 'editor', 'index.html'),
-            '<h1>editor</h1>',
+            nodePath.join(root, 'about', 'index.html'),
+            '<h1>about</h1>',
         );
         writeFileSync(
-            nodePath.join(root, 'editor', 'assets', 'app.js'),
+            nodePath.join(root, 'about', 'assets', 'app.js'),
             'console.log(1);',
         );
         mkdirSync(nodePath.join(root, 'docs', 'dist'), { recursive: true });
@@ -893,7 +893,7 @@ describe('createNativeAppStatic', () => {
 
     it('leaves a native app name alone on a host outside our domains', async () => {
         const req = staticReq({
-            subdomains: ['com', 'example', 'editor'],
+            subdomains: ['com', 'example', 'about'],
             path: '/index.html',
         });
         (req as Request & { is_custom_domain?: boolean }).is_custom_domain =
@@ -907,7 +907,7 @@ describe('createNativeAppStatic', () => {
         const { out, next } = await runStatic(
             createNativeAppStatic(config),
             staticReq({
-                subdomains: ['localhost', 'puter', 'editor'],
+                subdomains: ['localhost', 'puter', 'about'],
                 path: '/index.html',
             }),
         );
@@ -915,17 +915,24 @@ describe('createNativeAppStatic', () => {
         expect(next).toHaveBeenCalledTimes(1);
     });
 
-    it('passes through subdomains that are not native apps', async () => {
-        const { out, next } = await runStatic(
-            withRoot(),
-            staticReq({
-                subdomains: ['localhost', 'puter', 'api'],
-                path: '/index.html',
-            }),
-        );
-        expect(out.sent).toBeUndefined();
-        expect(next).toHaveBeenCalledTimes(1);
-    });
+    // `editor`, `markus` and `pdf` are web apps on standard host routing,
+    // even with a folder of their own under the native apps root.
+    it.each(['api', 'editor', 'markus', 'pdf'])(
+        'passes %s through, as it is not a native app',
+        async (sub) => {
+            mkdirSync(nodePath.join(root, sub), { recursive: true });
+            writeFileSync(nodePath.join(root, sub, 'index.html'), sub);
+            const { out, next } = await runStatic(
+                withRoot(),
+                staticReq({
+                    subdomains: ['localhost', 'puter', sub],
+                    path: '/index.html',
+                }),
+            );
+            expect(out.sent).toBeUndefined();
+            expect(next).toHaveBeenCalledTimes(1);
+        },
+    );
 
     it('passes through when there is no subdomain at all', async () => {
         const { next } = await runStatic(
@@ -939,13 +946,13 @@ describe('createNativeAppStatic', () => {
         const { out, next } = await runStatic(
             withRoot(),
             staticReq({
-                subdomains: ['localhost', 'puter', 'editor'],
+                subdomains: ['localhost', 'puter', 'about'],
                 path: '/index.html',
             }),
         );
         expect(out.sent).toEqual({
             path: '/index.html',
-            root: nodePath.join(root, 'editor'),
+            root: nodePath.join(root, 'about'),
         });
         expect(next).not.toHaveBeenCalled();
     });
@@ -954,11 +961,11 @@ describe('createNativeAppStatic', () => {
         const { out } = await runStatic(
             withRoot(),
             staticReq({
-                subdomains: ['localhost', 'puter', 'EDITOR'],
+                subdomains: ['localhost', 'puter', 'ABOUT'],
                 path: '/index.html',
             }),
         );
-        expect(out.sent?.root).toBe(nodePath.join(root, 'editor'));
+        expect(out.sent?.root).toBe(nodePath.join(root, 'about'));
     });
 
     it('serves docs out of its dist/ subdirectory, not the app root', async () => {
@@ -979,7 +986,7 @@ describe('createNativeAppStatic', () => {
         const { out, next } = await runStatic(
             withRoot(),
             staticReq({
-                subdomains: ['localhost', 'puter', 'editor'],
+                subdomains: ['localhost', 'puter', 'about'],
                 path: '/assets',
                 originalUrl: '/assets?v=2',
             }),
@@ -995,7 +1002,7 @@ describe('createNativeAppStatic', () => {
         const { out } = await runStatic(
             withRoot(),
             staticReq({
-                subdomains: ['localhost', 'puter', 'editor'],
+                subdomains: ['localhost', 'puter', 'about'],
                 path: '/assets/',
             }),
         );
@@ -1007,7 +1014,7 @@ describe('createNativeAppStatic', () => {
         const { out, next } = await runStatic(
             withRoot(),
             staticReq({
-                subdomains: ['localhost', 'puter', 'editor'],
+                subdomains: ['localhost', 'puter', 'about'],
                 path: '/nope.html',
             }),
         );
@@ -1019,7 +1026,7 @@ describe('createNativeAppStatic', () => {
         const { next } = await runStatic(
             withRoot(),
             staticReq({
-                subdomains: ['localhost', 'puter', 'editor'],
+                subdomains: ['localhost', 'puter', 'about'],
                 path: '/index.html',
             }),
             new Error('send failed'),
@@ -1032,7 +1039,7 @@ describe('createNativeAppStatic', () => {
             runStatic(
                 withRoot(),
                 staticReq({
-                    subdomains: ['localhost', 'puter', 'editor'],
+                    subdomains: ['localhost', 'puter', 'about'],
                     path: '/../../etc/passwd',
                 }),
             ),

src/backend/core/http/middleware/hostRedirects.ts

@@ -27,15 +27,7 @@ import { HttpError, isHttpError } from '../HttpError';
 import { isLocalWorkerHost } from './localWorkerProxy';
 
 /** Native-app subdomains served via `nativeAppStatic`. */
-const NATIVE_APP_SUBDOMAINS = [
-    'about',
-    'developer',
-    'docs',
-    'editor',
-    'markus',
-    'pdf',
-    'apps',
-] as const;
+const NATIVE_APP_SUBDOMAINS = ['about', 'developer', 'docs', 'apps'] as const;
 
 /** Subset served out of a `dist/` subdirectory rather than the app root. */
 const NATIVE_APPS_WITH_DIST = new Set(['docs', 'developer']);
@@ -111,6 +103,10 @@ export const subdomainLabelOf = (
     return label && !label.includes('.') ? label : undefined;
 };
 
+/** Whether core itself answers `<name>.<domain>` (`www` redirects to the root). */
+export const isReservedSubdomain = (name: string): boolean =>
+    name === 'www' || RESERVED_SUBDOMAINS.has(name);
+
 /**
  * Record a claim on `<name>.<domain>`. Throws on a malformed or uppercase
  * label, a subdomain core already handles, or a name that is already claimed.
@@ -123,7 +119,7 @@ export const addClaimedSubdomain = (
     if (typeof name !== 'string' || !SUBDOMAIN_LABEL.test(name)) {
         throw new Error(`Invalid subdomain label: ${JSON.stringify(name)}`);
     }
-    if (name === 'www' || RESERVED_SUBDOMAINS.has(name)) {
+    if (isReservedSubdomain(name)) {
         throw new Error(`Subdomain '${name}' is reserved`);
     }
     if (claims.has(name)) {

src/backend/core/schedules.ts

@@ -69,6 +69,8 @@ export interface ScheduleView {
     appUid: string;
     /** `null` once ended: the handler binding goes with the schedule. */
     handlerName: string | null;
+    /** Set only when the handler lives in the holder's own scope. */
+    handlerScope?: 'user';
     contextKeys: string[] | null;
     contextHash: string | null;
     /** Interval of an `every` schedule. */
@@ -168,8 +170,16 @@ export interface ScheduleServiceContract {
         request: ScheduleListRequest,
     ): Promise<PageResult<ScheduleView>>;
     get(actor: Actor, scheduleId: unknown): Promise<ScheduleView>;
+    update(
+        actor: Actor,
+        scheduleId: unknown,
+        changes: unknown,
+    ): Promise<ScheduleView>;
     remove(actor: Actor, scheduleId: unknown): Promise<void>;
-    receivePeerChanges(body: unknown): Promise<{ applied: number }>;
+    /** `results`: each change's index outcome, in order (`null` if dropped). */
+    receivePeerChanges(
+        body: unknown,
+    ): Promise<{ applied: number; results?: Array<number | null> }>;
     /** Checks a caller supplying `sendAt`; `events_disabled` when off. */
     prepareSendAt(actor: Actor, sendAt: unknown): Promise<DeferredSendPlan>;
     createDeferredAppMessage(

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

@@ -463,10 +463,26 @@ describe('ImageGenerationDriver.generate provider routing', () => {
             driver.generate({ prompt: 'a landscape' }),
         );
         expect(openaiImagesGenerateMock).toHaveBeenCalledWith(
-            expect.objectContaining({ model: 'gpt-image-2' }),
+            expect.objectContaining({ model: 'gpt-image-2.6-flare' }),
         );
     });
 
+    it.each(['gpt-image-2.6-flare', 'gpt-image-2.6-sunburst'])(
+        'routes %s and its OpenAI alias', async (model) => {
+            for (const id of [model, `openai/${model}`]) {
+                openaiImagesGenerateMock.mockResolvedValueOnce({
+                    data: [{ url: 'https://oai/image.png' }],
+                });
+                await withDriverName('ai-image', () => driver.generate({
+                    model: id, prompt: 'a landscape',
+                }));
+                expect(openaiImagesGenerateMock).toHaveBeenLastCalledWith(
+                    expect.objectContaining({ model }),
+                );
+            }
+        },
+    );
+
     it('rejects an excluded model regardless of caller casing', async () => {
         await expect(withActor(() =>
             driver.generate({
@@ -742,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',
@@ -836,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;
@@ -1146,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),
         );
     });
 
@@ -1649,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',
@@ -150,9 +150,9 @@ describe('OpenAiImageProvider construction', () => {
 // ── Model catalog ───────────────────────────────────────────────────
 
 describe('OpenAiImageProvider model catalog', () => {
-    it('returns gpt-image-2 as the default', () => {
+    it('returns gpt-image-2.6-flare as the default', () => {
         const provider = makeProvider();
-        expect(provider.getDefaultModel()).toBe('gpt-image-2');
+        expect(provider.getDefaultModel()).toBe('gpt-image-2.6-flare');
     });
 
     it('drops the deprecated gpt-image-1 family and chatgpt-image-latest', () => {
@@ -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();
     });
 });
@@ -235,9 +235,60 @@ describe('OpenAiImageProvider.generate argument validation', () => {
 // ── Credit gate ─────────────────────────────────────────────────────
 
 describe('OpenAiImageProvider.generate credit gate', () => {
+    it('waits for the real usage write before returning an image', async () => {
+        const actor = makeActor({
+            user: {
+                id: 62,
+                uuid: `image-write-${Date.now()}`,
+                username: 'metered',
+            },
+        });
+        const redis = server.clients.redis as unknown as {
+            meterIncr: (...args: string[]) => Promise<unknown>;
+        };
+        const realIncr = redis.meterIncr.bind(redis);
+        let release!: () => void;
+        const held = new Promise<void>((resolve) => {
+            release = resolve;
+        });
+        let blocked = false;
+        vi.spyOn(redis, 'meterIncr').mockImplementation(async (...args) => {
+            const actorKey = `:actor:${actor.user!.uuid}:`;
+            if (!blocked && args.some((arg) => arg.includes(actorKey))) {
+                blocked = true;
+                await held;
+            }
+            return realIncr(...args);
+        });
+        generateMock.mockResolvedValueOnce({
+            data: [{ url: 'https://image.example/result.png' }],
+        });
+        const provider = makeProvider();
+        let finished = false;
+        const generating = withTestActor(
+            () =>
+                provider.generate({
+                    model: 'gpt-image-2',
+                    prompt: 'an image',
+                    ratio: { w: 1024, h: 1024 },
+                }),
+            actor,
+        ).then((result) => {
+            finished = true;
+            return result;
+        });
+        try {
+            await vi.waitFor(() => expect(blocked).toBe(true));
+            expect(finished).toBe(false);
+        } finally {
+            release();
+            await generating;
+        }
+    });
+
     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({
@@ -273,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.
@@ -677,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);
     });
 
@@ -703,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);
     });
 });
@@ -857,3 +908,64 @@ it('keeps a landscape aspect hint landscape at gpt-image-2 sizes', async () => {
     expect(w).toBeGreaterThan(h);
     expect(Math.abs(w / h - 1.7)).toBeLessThan(0.1);
 });
+
+
+describe('OpenAiImageProvider GPT Image 2.6', () => {
+    it.each(['gpt-image-2.6-flare', 'gpt-image-2.6-sunburst'])(
+        '%s generates and edits with token-based billing', async (model) => {
+            const provider = makeProvider();
+            const response = {
+                data: [{ b64_json: 'AAAA' }],
+                usage: {
+                    input_tokens: 100,
+                    output_tokens: 800,
+                    input_tokens_details: { text_tokens: 100, image_tokens: 0 },
+                },
+            };
+            generateMock.mockResolvedValue(response);
+            editMock.mockResolvedValue(response);
+            for (const input_image of [undefined, 'data:image/png;base64,AAAA']) {
+                const result = await withTestActor(() => provider.generate({
+                    model, prompt: 'hi', quality: 'xhigh',
+                    ratio: { w: 1024, h: 1024 }, input_image,
+                }));
+                expect(result).toBe('data:image/png;base64,AAAA');
+            }
+            for (const mock of [generateMock, editMock]) {
+                expect(mock.mock.calls[0]![0]).toMatchObject({
+                    model, quality: 'xhigh', size: '1024x1024',
+                });
+            }
+            const [, entries] = batchIncrementUsagesSpy.mock.calls[0]!;
+            expect(entries).toEqual(expect.arrayContaining([
+                expect.objectContaining({
+                    usageType: `openai:${model}:xhigh:1024x1024:output`,
+                    costOverride: 2_400_000,
+                }),
+            ]));
+        },
+    );
+
+    it.each([
+        ['low', 1024, 1024, 823],
+        ['medium', 1024, 1024, 1449],
+        ['high', 1024, 1024, 1756],
+        ['xhigh', 1024, 1024, 3122],
+        ['max', 1024, 1024, 7024],
+        ['auto', 1024, 1024, 1449],
+        ['low', 2048, 1088, 571],
+    ])('estimates %s at %sx%s from the 2.6 calculator', async (quality, w, h, tokens) => {
+        generateMock.mockResolvedValue({ data: [{ b64_json: 'AAAA' }] });
+        await withTestActor(() => makeProvider().generate({
+            model: 'gpt-image-2.6-flare', prompt: 'hi', quality: String(quality),
+            ratio: { w: Number(w), h: Number(h) },
+        }));
+        const [, entries] = batchIncrementUsagesSpy.mock.calls[0]!;
+        const output = (entries as Array<{ usageType: string; costOverride: number }>)
+            .find((entry) => entry.usageType.endsWith(':output'))!;
+        expect(output.usageType).toBe(`openai:gpt-image-2.6-flare:${quality}:${w}x${h}:output`);
+        // The metering conversion rounds fractional microcents upward.
+        expect(output.costOverride).toBeGreaterThanOrEqual(Number(tokens) * 3000);
+        expect(output.costOverride).toBeLessThanOrEqual(Number(tokens) * 3000 + 1);
+    });
+});

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

@@ -56,8 +56,8 @@ interface OpenAIImageUsage {
 
 /**
  * OpenAI image generation provider for v2. Supports the GPT Image models
- * (gpt-image-2, -2.5-sunburst, -2.5-flare), including image-to-image editing
- * via `input_images` (the `images.edit` endpoint).
+ * (gpt-image-2 and the 2.5/2.6 Sunburst and Flare models), including
+ * image-to-image editing via `input_images` (the `images.edit` endpoint).
  */
 export class OpenAiImageProvider implements IImageProvider {
     #meteringService: AiMeteringService;
@@ -109,7 +109,7 @@ export class OpenAiImageProvider implements IImageProvider {
     }
 
     getDefaultModel(): string {
-        return 'gpt-image-2';
+        return 'gpt-image-2.6-flare';
     }
 
     async generate({
@@ -293,7 +293,10 @@ export class OpenAiImageProvider implements IImageProvider {
                 });
             }
             if (usageEntries.length) {
-                this.#meteringService.batchIncrementUsages(actor, usageEntries);
+                await this.#meteringService.batchIncrementUsages(
+                    actor,
+                    usageEntries,
+                );
             }
 
             const url =
@@ -601,17 +604,36 @@ export class OpenAiImageProvider implements IImageProvider {
         height: number,
         quality?: string,
     ): number {
-        const factors = model.startsWith('gpt-image-2.5')
-            ? OpenAiImageProvider.#GPT_IMAGE_2_5_LATENT_FACTORS
-            : OpenAiImageProvider.#GPT_IMAGE_2_LATENT_FACTORS;
+        const isGptImage26 = model.startsWith('gpt-image-2.6');
+        const factors =
+            isGptImage26 || model.startsWith('gpt-image-2.5')
+                ? OpenAiImageProvider.#GPT_IMAGE_2_5_LATENT_FACTORS
+                : OpenAiImageProvider.#GPT_IMAGE_2_LATENT_FACTORS;
         const factor = factors[quality ?? ''] ?? factors.medium;
         const longEdge = Math.max(width, height);
         const shortEdge = Math.min(width, height);
-        const shortLatent = Math.round((factor * shortEdge) / longEdge);
+        const shortGrid = (factor * shortEdge) / longEdge;
+        const floorGrid = Math.floor(shortGrid);
+        const shortLatent =
+            isGptImage26 && shortGrid - floorGrid === 0.5
+                ? floorGrid + (floorGrid % 2)
+                : Math.round(shortGrid);
         const latentW = width >= height ? factor : shortLatent;
         const latentH = width >= height ? shortLatent : factor;
         const baseArea = latentW * latentH;
-        return Math.ceil((baseArea * (2_000_000 + width * height)) / 4_000_000);
+        const tokens = Math.ceil(
+            (baseArea * (2_000_000 + width * height)) / 4_000_000,
+        );
+        // GPT Image 2.6 bills more tokens at low and medium quality.
+        const estimatedQuality =
+            quality && quality in factors ? quality : 'medium';
+        const multiplier =
+            estimatedQuality === 'low'
+                ? 4.2
+                : estimatedQuality === 'medium'
+                  ? 3.3
+                  : 1;
+        return isGptImage26 ? Math.round(tokens * multiplier) : tokens;
     }
 
     #estimateOutputCostFromTokens(

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

@@ -20,6 +20,46 @@
 import type { IImageModel } from '../../types.js';
 
 export const OPEN_AI_IMAGE_GENERATION_MODELS: IImageModel[] = [
+    {
+        puterId: 'openai:openai/gpt-image-2.6-sunburst',
+        id: 'gpt-image-2.6-sunburst',
+        aliases: ['openai/gpt-image-2.6-sunburst'],
+        name: 'GPT Image 2.6 Sunburst',
+        version: '2.6',
+        costs_currency: 'usd-cents',
+        index_cost_key: 'low:1024x1024',
+        costs: {
+            // Text tokens (per 1M tokens)
+            text_input: 500, // $5.00
+            text_cached_input: 125, // $1.25
+            // Image tokens (per 1M tokens)
+            image_input: 800, // $8.00
+            image_cached_input: 200, // $2.00
+            image_output: 3000, // $30.00
+            'low:1024x1024': 2.469,
+        },
+        allowedQualityLevels: ['low', 'medium', 'high', 'xhigh', 'max', 'auto'],
+    },
+    {
+        puterId: 'openai:openai/gpt-image-2.6-flare',
+        id: 'gpt-image-2.6-flare',
+        aliases: ['openai/gpt-image-2.6-flare'],
+        name: 'GPT Image 2.6 Flare',
+        version: '2.6',
+        costs_currency: 'usd-cents',
+        index_cost_key: 'low:1024x1024',
+        costs: {
+            // Text tokens (per 1M tokens)
+            text_input: 500, // $5.00
+            text_cached_input: 125, // $1.25
+            // Image tokens (per 1M tokens)
+            image_input: 800, // $8.00
+            image_cached_input: 200, // $2.00
+            image_output: 3000, // $30.00
+            'low:1024x1024': 2.469,
+        },
+        allowedQualityLevels: ['low', 'medium', 'high', 'xhigh', 'max', 'auto'],
+    },
     {
         puterId: 'openai:openai/gpt-image-2.5-sunburst',
         id: 'gpt-image-2.5-sunburst',

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/apps/AppDriver.js

@@ -31,7 +31,7 @@ import {
     normalizeRawBase64ImageString,
     validateIconDataUrl,
 } from '../../util/appIcon.js';
-import { toAppReadView } from '../../util/appView.js';
+import { isOriginBootstrapApp, toAppReadView } from '../../util/appView.js';
 import { awaitLater } from '../../util/concurrency.js';
 import { isUniqueViolation } from '../../util/dbError.js';
 import {
@@ -1088,22 +1088,6 @@ export class AppDriver extends PuterDriver {
         }
     }
 
-    /**
-     * Origin-bootstrap detection: rows auto-created when an unknown origin
-     * first needed an app row (no human-supplied metadata). Marker is `name ===
-     * uid && title === uid` and a description starting with "App created from
-     * origin ". Only these rows are eligible for same-owner merging — refusing
-     * to merge arbitrary same-owner apps prevents accidental data loss.
-     */
-    #isOriginBootstrapApp(app) {
-        if (!app || typeof app !== 'object') return false;
-        if (typeof app.uid !== 'string' || !app.uid) return false;
-        if (app.name !== app.uid) return false;
-        if (app.title !== app.uid) return false;
-        if (typeof app.description !== 'string') return false;
-        return app.description.startsWith('App created from origin ');
-    }
-
     // -- Canonical-uid alias kvstore pair -----------------------------
     //
     // After a merge, the source app uid → canonical uid mapping is
@@ -1266,7 +1250,7 @@ export class AppDriver extends PuterDriver {
         if (
             Number.isInteger(conflictOwnerUserId) &&
             conflictOwnerUserId === user.id &&
-            !this.#isOriginBootstrapApp(appToJoin)
+            !isOriginBootstrapApp(appToJoin)
         ) {
             // Prevent merging arbitrary same-owner apps; only allow the
             // auto-created origin bootstrap row to be absorbed.

src/backend/drivers/notification/NotificationDriver.appMessage.test.ts

@@ -188,7 +188,11 @@ describe('app.message with live delivery over the socket wire', () => {
             captureBus(state.server, 'outer.gui.notif.message', async () => {
                 created = (await withActor(asApp(holder, app), () =>
                     state.driver.create(
-                        message({ text: 'Body', channel: 'replies' }),
+                        message({
+                            text: 'Body',
+                            priority: 'high',
+                            channel: 'replies',
+                        }),
                     ),
                 )) as Record<string, unknown>;
             }).then((seen) => (desktop = seen)),
@@ -200,7 +204,7 @@ describe('app.message with live delivery over the socket wire', () => {
             title: 'Hello',
             text: 'Body',
             channel: 'replies',
-            priority: 'normal',
+            priority: 'high',
             ttl: 3600,
             app: { uid: app.uid, name: 'App message test' },
         });
@@ -212,6 +216,7 @@ describe('app.message with live delivery over the socket wire', () => {
             app_uid: app.uid,
             audience: 'app-user',
             type: 'app.message',
+            value: expect.objectContaining({ priority: 'high' }),
         });
         // Not silent, but sent for the app alone: the desktop wire stays quiet.
         expect(written).toEqual([
@@ -220,7 +225,7 @@ describe('app.message with live delivery over the socket wire', () => {
                 uid,
                 type: 'app.message',
                 appUid: app.uid,
-            }),
+                value: expect.objectContaining({ priority: 'high' }),            }),
         ]);
         expect(desktop).toEqual([]);
     });

src/backend/drivers/notification/NotificationDriver.handle.integration.test.ts

@@ -207,6 +207,7 @@ describe('app.message to the other party of a share', () => {
         const written = await captureBus('notif.written', async () => {
             sent = await send(inApp(owner, app), {
                 title: 'New message',
+                priority: 'high',
                 to: { handle },
             });
         });
@@ -222,7 +223,7 @@ describe('app.message to the other party of a share', () => {
         expect(row!.value).toEqual({
             type: 'app.message',
             title: 'New message',
-            priority: 'normal',
+            priority: 'high',
             ttl: 3600,
             app: { uid: app.uid, name: 'Handle App' },
         });

src/backend/drivers/notification/NotificationDriver.sendAt.test.ts

@@ -165,6 +165,7 @@ const fakeSchedules = (plan: Partial<DeferredSendPlan>) =>
         createFor: vi.fn(),
         list: vi.fn(),
         get: vi.fn(),
+        update: vi.fn(),
         remove: vi.fn(),
         receivePeerChanges: vi.fn(),
         prepareSendAt: vi.fn(async (): Promise<DeferredSendPlan> => ({
@@ -270,7 +271,9 @@ describe('notify({ sendAt }) with services.schedules', () => {
         const schedules = fakeSchedules({ sendAt: at });
         setSchedules(schedules);
 
-        await expect(notify({ sendAt: at, text: 'later' })).resolves.toEqual({
+        await expect(
+            notify({ sendAt: at, text: 'later', priority: 'high' }),
+        ).resolves.toEqual({
             scheduled: { scheduleId: 'sched-1', sendAt: at },
         });
         expect(schedules.prepareSendAt).toHaveBeenCalledWith(
@@ -283,6 +286,7 @@ describe('notify({ sendAt }) with services.schedules', () => {
                 message: expect.objectContaining({
                     title: 'Hi',
                     text: 'later',
+                    priority: 'high',
                 }),
             },
         );
@@ -318,11 +322,20 @@ describe('deferredAppMessages.write', () => {
         const key = uuidv4();
         const id = await claimed(token);
 
-        await expect(write(key, txFor(id, token))).resolves.toBe('delivered');
+        await expect(
+            write(key, txFor(id, token), {
+                payload: JSON.stringify({
+                    message: { title: 'Later', priority: 'high' },
+                }),
+            }),
+        ).resolves.toBe('delivered');
         const rows = await mailbox();
         expect(rows).toHaveLength(1);
         expect(rows[0]).toMatchObject({ uid: key, send_key: key });
-        expect(valueOf(rows[0])).toMatchObject({ title: 'Later' });
+        expect(valueOf(rows[0])).toMatchObject({
+            title: 'Later',
+            priority: 'high',
+        });
     });
 
     it('writes nothing when the guard no longer holds: another claim took it', async () => {

src/backend/drivers/notification/NotificationDriver.test.ts

@@ -859,3 +859,32 @@ describe('NotificationDriver — rows written before the scope columns', () => {
         expect(await selectUids(holder.actor)).toEqual([uid]);
     });
 });
+
+
+describe('NotificationDriver displayed notification catch-up', () => {
+    it('selects named ids within the app and user scope', async () => {
+        const box = await mailbox();
+        await server.services.notification.markAcknowledged(box.rows.appUser, box.holder.userId);
+        const rows = await withActor(box.ownAppActor, () => driver.select({
+            subject: 'notif:app-user',
+            uids: Object.values(box.rows),
+            limit: 50,
+        }));
+        expect(rows).toEqual([expect.objectContaining({
+            uid: box.rows.appUser, acknowledged: expect.any(Number),
+        })]);
+    });
+
+    it.each([Array(51).fill('one'), [''], [7], 'one', ['x'.repeat(129)]])(
+        'rejects an invalid or oversized id batch: %s', async (uids) => {
+            const { actor } = await makeUser();
+            await expect(withActor(actor, () => driver.select({ uids })))
+                .rejects.toMatchObject({ statusCode: 400 });
+        },
+    );
+
+    it('returns no rows for an empty id batch', async () => {
+        const { actor } = await makeUser();
+        expect(await withActor(actor, () => driver.select({ uids: [] }))).toEqual([]);
+    });
+});

src/backend/drivers/notification/NotificationDriver.ts

@@ -46,7 +46,7 @@ import {
     ownedAppUids,
 } from '../../services/notification/notificationAudience.js';
 import {
-    NOTIFICATION_VALUE_MAX_BYTES,
+    assertNotificationValueFits,
     OUTSIDE_ACCOUNT_MAILBOX_TYPES,
     resolveNotificationWrite,
     type NotificationTypeName,
@@ -120,19 +120,6 @@ interface MailboxScope {
     appUid: string | null | undefined;
 }
 
-const assertValueFits = (value: Record<string, unknown>): void => {
-    if (
-        Buffer.byteLength(JSON.stringify(value), 'utf8') >
-        NOTIFICATION_VALUE_MAX_BYTES
-    ) {
-        throw new HttpError(
-            400,
-            `\`value\` may not exceed ${NOTIFICATION_VALUE_MAX_BYTES} bytes`,
-            { legacyCode: 'notification_value_too_large' },
-        );
-    }
-};
-
 const typeNotAllowed = (message: string): HttpError =>
     new HttpError(403, message, {
         legacyCode: 'forbidden',
@@ -277,7 +264,7 @@ export class NotificationDriver extends PuterDriver {
                 value,
             );
         }
-        assertValueFits(value);
+        assertNotificationValueFits(value);
         if (type === APP_MESSAGE_TYPE) {
             throw typeNotAllowed(`Only apps can create ${APP_MESSAGE_TYPE}`);
         }
@@ -342,13 +329,34 @@ export class NotificationDriver extends PuterDriver {
             : predicate;
 
         const scope = this.#resolveScope(actor, args.subject);
+        const uids = args.uids;
+        if (
+            uids !== undefined &&
+            (!Array.isArray(uids) ||
+                uids.length > 50 ||
+                uids.some(
+                    (uid) =>
+                        typeof uid !== 'string' ||
+                        uid.length === 0 ||
+                        uid.length > 128,
+                ))
+        ) {
+            throw new HttpError(
+                400,
+                'uids must contain at most 50 notification ids',
+                {
+                    legacyCode: 'bad_request',
+                },
+            );
+        }
         const query: {
             limit: number;
             scope: MailboxScope | null;
             filter?: string;
             onlyUnacknowledged?: boolean;
             excludeTypes?: readonly string[];
-        } = { limit, scope };
+            uids?: string[];
+        } = { limit, scope, ...(uids ? { uids: uids as string[] } : {}) };
         // The whole mailbox, or a slice naming no app, is the desktop's view of
         // it, which leaves out the types only an app has a use for. A slice
         // naming the app still returns them.
@@ -430,7 +438,7 @@ export class NotificationDriver extends PuterDriver {
         }
         const handle = to === undefined ? undefined : parseNotifyTarget(to);
         const message = parseAppMessage(fields);
-        assertValueFits(value);
+        assertNotificationValueFits(value);
         const timing =
             sendAt === undefined || sendAt === null
                 ? null
@@ -539,9 +547,7 @@ export class NotificationDriver extends PuterDriver {
         };
     }
 
-    /**
-     * For extensions. A field, not a method, so `/drivers/call` can't reach it.
-     */
+    /** For extensions. A field, not a method, so `/drivers/call` can't reach it. */
     readonly deferredAppMessages = {
         write: (input: DeferredWriteInput, tx: DeferredWriteTx) =>
             this.#writeDeferredAppMessage(input, tx),

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/drivers/util/pipeStreamResult.test.ts

@@ -129,6 +129,27 @@ describe('pipeStreamResult', () => {
         expect(warn).not.toHaveBeenCalled();
     });
 
+    it('adds at most two close listeners to the response', async () => {
+        // The response already carries close listeners from metering,
+        // compression and tracing; Node warns past ten.
+        let added = -1;
+        server = createServer((_req, res) => {
+            const before = res.listenerCount('close');
+            pipeStreamResult(Readable.from(['a', 'b']), res, 'test.run');
+            added = res.listenerCount('close') - before;
+        });
+        await new Promise<void>((resolve) => server!.listen(0, resolve));
+        const { port } = server.address() as AddressInfo;
+        await new Promise<void>((resolve) =>
+            get(`http://127.0.0.1:${port}/`, (res) => {
+                res.resume();
+                res.on('end', () => resolve());
+            }),
+        );
+        expect(added).toBeGreaterThan(0);
+        expect(added).toBeLessThanOrEqual(2);
+    });
+
     it('drops the source, without throwing, when the client left before the result was ready', async () => {
         const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
         const source = Readable.from(['late']);

src/backend/drivers/util/pipeStreamResult.ts

@@ -17,7 +17,7 @@
  * along with this program.  If not, see <https://www.gnu.org/licenses/>.
  */
 
-import { pipeline, type Readable } from 'node:stream';
+import type { Readable } from 'node:stream';
 
 // Only what's used here, so callers on another @types/node (or express's
 // Response) still fit.
@@ -32,24 +32,32 @@ type ResponseSink = NodeJS.WritableStream & {
  * mid-body destroys the response, so the client sees an aborted transfer rather
  * than a clean end, and the failure is logged once instead of surfacing as an
  * unhandled stream error. A client that hangs up stops the source.
+ *
+ * `pipe` rather than `pipeline`: pipeline puts seven close listeners on the
+ * response, and with the ones metering, compression and tracing add, every
+ * streamed response tripped Node's ten-listener warning.
  */
 export function pipeStreamResult(
     stream: Readable,
     res: ResponseSink,
     label: string,
 ): void {
-    // The caller hung up while the driver ran; `pipeline` throws on a closed
-    // destination, so drop the source instead.
+    // The caller hung up while the driver ran: nothing will read the source.
     if (res.closed || res.destroyed) {
         stream.destroy();
         return;
     }
-    pipeline(stream, res, (err) => {
-        if (!err) return;
+    stream.once('error', (err) => {
+        stream.unpipe(res);
         if (!res.destroyed) res.destroy();
-        // The client hanging up is not a failure of ours.
-        if ((err as { code?: string }).code === 'ERR_STREAM_PREMATURE_CLOSE')
-            return;
         console.warn(`[drivers] ${label} stream failed mid-response:`, err);
     });
+    // A response that closes before the source ended is a client hanging up.
+    res.once('close', () => {
+        if (stream.readableEnded) return;
+        stream.unpipe(res);
+        stream.destroy();
+    });
+    res.once('error', () => stream.destroy());
+    stream.pipe(res);
 }

src/backend/drivers/workers/WorkerDriver.cloudflare.test.ts

@@ -754,6 +754,50 @@ describe('WorkerDriver.create with a configured deploy backend', () => {
             expect(putCalls()).toHaveLength(1);
         });
 
+        const uploadedMetadata = () => {
+            const [, init] = putCalls().at(-1)!;
+            const form = (init as RequestInit).body as FormData;
+            return JSON.parse(form.get('metadata') as string);
+        };
+
+        it('sends limits.cpu_ms in the upload metadata when cpuMs is set', async () => {
+            const { user, actor } = await makeUser();
+            const path = `/${user.username}/cpu.worker.js`;
+            await writeSource(actor, user.id, path, 'export default {}');
+            const scriptName = `dt-cpu-${user.username}`;
+            await inCtx(actor, () =>
+                target.create({
+                    appId: '',
+                    workerName: scriptName,
+                    filePath: path,
+                    [INTERNAL_DEPLOY_TARGET]: { scriptName, cpuMs: 50 },
+                }),
+            );
+            expect(uploadedMetadata().limits).toEqual({ cpu_ms: 50 });
+        });
+
+        it('sends no limits key without cpuMs, and none on an ordinary create', async () => {
+            const { user, actor } = await makeUser();
+            const path = `/${user.username}/nocpu.worker.js`;
+            await writeSource(actor, user.id, path, 'export default {}');
+            const scriptName = `dt-nocpu-${user.username}`;
+            await deployTo(actor, path, scriptName);
+            expect(uploadedMetadata()).not.toHaveProperty('limits');
+
+            const name = `plain-${user.username}`;
+            await inCtx(actor, () =>
+                target.create({ appId: '', workerName: name, filePath: path }),
+            );
+            const metadata = uploadedMetadata();
+            expect(metadata).not.toHaveProperty('limits');
+            expect(Object.keys(metadata)).toEqual([
+                'body_part',
+                'compatibility_flags',
+                'compatibility_date',
+                'bindings',
+            ]);
+        });
+
         it('refuses a file another user owns, even with manage on it', async () => {
             const owner = await makeUser();
             const deployer = await makeUser();

src/backend/drivers/workers/WorkerDriver.test.ts

@@ -3,6 +3,7 @@
 //  however the interactions with the Puter API are
 import {
     afterAll,
+    afterEach,
     beforeAll,
     beforeEach,
     describe,
@@ -13,6 +14,7 @@ import {
 import { Actor, makeActor as resolveActor } from '../../core/actor.js';
 import { runWithContext } from '../../core/context.js';
 import { PuterServer } from '../../server.js';
+import { DEFAULT_FREE_SUBSCRIPTION } from '../../services/metering/consts.js';
 import {
     setupPuterTestEnv,
     setupTestServer,
@@ -797,6 +799,174 @@ describe('WorkerDriver', () => {
         });
     });
 
+    describe('rented-unit cap', () => {
+        const FREE_CAP = 16;
+        const PAID_CAP = 100;
+
+        // The cap sits after the deploy-credentials gate, so the driver needs
+        // credentials to reach it; a create under the cap then fails on the
+        // missing source file, which is what tells it past the cap check.
+        let originalWorkersConfig: unknown;
+        let originalEvents: unknown;
+        beforeAll(() => {
+            const driverConfig = (
+                target as unknown as { config: Record<string, unknown> }
+            ).config;
+            originalEvents = driverConfig.events;
+            driverConfig.events = { userHandlers: true };
+            originalWorkersConfig = driverConfig.workers;
+            driverConfig.workers = {
+                XAUTHKEY: 'test-key',
+                ACCOUNTID: 'test-account',
+            };
+        });
+        afterAll(() => {
+            const driverConfig = (
+                target as unknown as { config: Record<string, unknown> }
+            ).config;
+            driverConfig.workers = originalWorkersConfig;
+            driverConfig.events = originalEvents;
+        });
+
+        const holding = (
+            plan: string,
+            held: { workers?: number; scopes?: number; owned?: number },
+        ) => {
+            vi.spyOn(
+                server.services.metering,
+                'getActorSubscription',
+            ).mockResolvedValue({ id: plan } as never);
+            vi.spyOn(
+                server.stores.subdomain,
+                'countByUserIdAndPrefix',
+            ).mockResolvedValue(held.workers ?? 0);
+            vi.spyOn(
+                server.stores.eventHandler,
+                'countUserScopesWithHandlersForUser',
+            ).mockResolvedValue(held.scopes ?? 0);
+            vi.spyOn(
+                server.stores.eventHandler,
+                'countAppsWithHandlersForOwner',
+            ).mockResolvedValue(held.owned ?? 0);
+        };
+        afterEach(() => {
+            vi.restoreAllMocks();
+        });
+
+        const createWorker = () =>
+            inCtx(() =>
+                target.create({
+                    appId: 'test-app',
+                    workerName: 'capped',
+                    filePath: '/test.js',
+                }),
+            );
+
+        it('keeps the flat 100-worker cap over ordinary workers with user scopes off', async () => {
+            const driverConfig = (
+                target as unknown as { config: Record<string, unknown> }
+            ).config;
+            driverConfig.events = { userHandlers: false };
+            try {
+                // 16 workers is fine here, and scopes and owned apps don't count.
+                holding(DEFAULT_FREE_SUBSCRIPTION, {
+                    workers: 16,
+                    scopes: 50,
+                    owned: 50,
+                });
+                const list = vi
+                    .spyOn(server.stores.subdomain, 'listByUserIdAndPrefix')
+                    .mockResolvedValue(
+                        Array.from({ length: 16 }, () => ({})) as never,
+                    );
+                await expect(createWorker()).rejects.not.toMatchObject({
+                    statusCode: 403,
+                });
+
+                list.mockResolvedValue(
+                    Array.from({ length: 100 }, () => ({})) as never,
+                );
+                await expect(createWorker()).rejects.toMatchObject({
+                    statusCode: 403,
+                    message: 'Worker limit reached (max 100)',
+                    legacyCode: 'forbidden',
+                });
+            } finally {
+                driverConfig.events = { userHandlers: true };
+            }
+        });
+
+        it('refuses a free user one unit past the cap, across all three sources', async () => {
+            for (const held of [
+                { workers: FREE_CAP },
+                { scopes: FREE_CAP },
+                { owned: FREE_CAP },
+                { workers: 10, scopes: 4, owned: 2 },
+            ]) {
+                holding(DEFAULT_FREE_SUBSCRIPTION, held);
+                await expect(createWorker()).rejects.toMatchObject({
+                    statusCode: 403,
+                    legacyCode: 'forbidden',
+                });
+            }
+        });
+
+        it('lets a free user create up to the cap', async () => {
+            holding(DEFAULT_FREE_SUBSCRIPTION, {
+                workers: 10,
+                scopes: 3,
+                owned: 2,
+            });
+            await expect(createWorker()).rejects.not.toMatchObject({
+                statusCode: 403,
+            });
+        });
+
+        it('refuses a paid user the unit after 100', async () => {
+            holding('paid-plan', { workers: 90, scopes: 5, owned: 5 });
+            await expect(createWorker()).rejects.toMatchObject({
+                statusCode: 403,
+            });
+            holding('paid-plan', { workers: 90, scopes: 5, owned: 4 });
+            await expect(createWorker()).rejects.not.toMatchObject({
+                statusCode: 403,
+            });
+            expect(PAID_CAP).toBe(100);
+        });
+
+        it('keeps a free user over the cap, redeploys what they hold, and refuses a new one', async () => {
+            holding(DEFAULT_FREE_SUBSCRIPTION, { workers: 20 });
+            const user = actor.user;
+            const exists = vi
+                .spyOn(server.stores.subdomain, 'getBySubdomain')
+                .mockImplementation(
+                    async (name: string) =>
+                        (name === 'workers.puter.capped'
+                            ? { user_id: user.id, uuid: 'existing-uuid' }
+                            : null) as never,
+                );
+            const noApp = makeActor({ app: undefined });
+            const create = (workerName: string) =>
+                inCtx(
+                    () =>
+                        target.create({
+                            appId: '',
+                            workerName,
+                            filePath: '/test.js',
+                        }),
+                    noApp,
+                );
+
+            await expect(create('capped')).rejects.not.toMatchObject({
+                statusCode: 403,
+            });
+            await expect(create('another')).rejects.toMatchObject({
+                statusCode: 403,
+            });
+            exists.mockRestore();
+        });
+    });
+
     describe('admission bypass', () => {
         const unverified = (): Actor =>
             makeActor({

src/backend/drivers/workers/WorkerDriver.ts

@@ -43,6 +43,7 @@ import { PuterDriver } from '../types.js';
 import { BoundedTtlMap } from '../../util/boundedTtlMap.js';
 import { awaitLater } from '../../util/concurrency.js';
 import { isUniqueViolation } from '../../util/dbError.js';
+import { assertRentedUnitRoom } from '../../util/rentedUnits.js';
 import { loadFileInput } from '../util/fileInput.js';
 import {
     normalizeLimit,
@@ -57,6 +58,7 @@ const CF_BASE_URL = 'https://api.cloudflare.com/client/v4/accounts';
 export const WORKER_COMPATIBILITY_DATE = '2025-07-15';
 export const WORKER_COMPATIBILITY_FLAGS = ['global_fetch_strictly_public'];
 const WORKER_NAME_REGEX = /^[a-zA-Z0-9_-]+$/;
+/** Cap on ordinary workers while user-scope handlers are off. */
 const MAX_WORKERS_PER_USER = 100;
 
 /**
@@ -179,12 +181,17 @@ export interface InternalDeployTarget {
      * scripts belong to what.
      */
     tags?: string[];
+    /**
+     * Per-invocation CPU limit in milliseconds, sent with the upload. Unset
+     * sends no limit. Ignored by the local runtime.
+     */
+    cpuMs?: number;
 }
 
 const MAX_SOURCE_SIZE = 10 * 1024 * 1024; // 10 MB
 // How far to scan an app's child apps when resolving which workers it may
-// see. A user is capped at MAX_WORKERS_PER_USER workers, so only that many
-// child apps can actually own one; the ceiling is generous slack over that.
+// see. A user is capped at their plan's rented units, so only that many
+// child apps can actually own a worker; the ceiling is generous slack over that.
 const CHILD_APP_SCAN_LIMIT = 1000;
 
 // -- Preamble --------------------------------------------------------
@@ -452,26 +459,34 @@ export class WorkerDriver extends PuterDriver {
 
         this.#requireCfConfig();
 
-        // Quota check — count existing workers.puter.* subdomains owned by user
-        //
-        // A deploy target creates no such row, so this count can neither see
-        // its scripts nor be grown by them; running it would only make an
-        // unrelated worker quota decide whether these deploy. Whatever bounds
-        // them has to be counted where they actually live, and belongs to the
-        // caller that owns their lifecycle.
-        const existingWorkers =
-            skipAdmission || deployTarget
-                ? []
-                : await this.stores.subdomain.listByUserIdAndPrefix(
-                      actor.user.id,
-                      WORKER_SUBDOMAIN_PREFIX,
-                  );
-        if (existingWorkers.length >= MAX_WORKERS_PER_USER) {
-            throw new HttpError(
-                403,
-                `Worker limit reached (max ${MAX_WORKERS_PER_USER})`,
-                { legacyCode: 'forbidden' },
-            );
+        // With user scopes on, a new worker is one more rented unit under the
+        // plan's cap, and redeploying an existing worker is never refused.
+        // Deploy targets create no worker row and are bounded by their caller.
+        if (this.config.events?.userHandlers === true) {
+            if (!skipAdmission && !deployTarget && !existingSub) {
+                await assertRentedUnitRoom(
+                    {
+                        stores: this.stores,
+                        metering: this.services.metering,
+                    },
+                    actor,
+                );
+            }
+        } else {
+            const existingWorkers =
+                skipAdmission || deployTarget
+                    ? []
+                    : await this.stores.subdomain.listByUserIdAndPrefix(
+                          actor.user.id,
+                          WORKER_SUBDOMAIN_PREFIX,
+                      );
+            if (existingWorkers.length >= MAX_WORKERS_PER_USER) {
+                throw new HttpError(
+                    403,
+                    `Worker limit reached (max ${MAX_WORKERS_PER_USER})`,
+                    { legacyCode: 'forbidden' },
+                );
+            }
         }
 
         // Read source file. loadFileInput runs the read-ACL check internally
@@ -940,6 +955,7 @@ export class WorkerDriver extends PuterDriver {
             compatibility_flags: WORKER_COMPATIBILITY_FLAGS,
             compatibility_date: WORKER_COMPATIBILITY_DATE,
             ...(target?.tags ? { tags: target.tags } : {}),
+            ...(target?.cpuMs ? { limits: { cpu_ms: target.cpuMs } } : {}),
             bindings: [
                 // A script deployed without a token gets no binding at all,
                 // rather than an empty one for its code to find.

src/backend/server.test.ts

@@ -336,6 +336,70 @@ describe('PuterServer host header validation', () => {
         expect(api.headers['x-frame-options']).toBeUndefined();
     });
 
+    it('allows deployment subdomains to frame the app browser embed', async () => {
+        const parent = `http://spreadsheet.puter.localhost:${port}`;
+        for (const path of ['/embed/apps', '/embed/apps/']) {
+            const res = await request(path, {
+                host: `puter.localhost:${port}`,
+                referer: `${parent}/sheet/1`,
+            });
+            expect(res.status).toBe(200);
+            expect(res.headers['x-frame-options']).toBeUndefined();
+            expect(res.headers['content-security-policy']).toBe(
+                `frame-ancestors 'self' ${parent}`,
+            );
+            expect(res.headers['cache-control']).toBe('no-store');
+            expect(res.body).toContain('/dist/apps-embed.min.js');
+            expect(res.body).not.toContain('/dist/bundle.min.js');
+            expect(res.body).toContain(`http://api.puter.localhost:${port}`);
+            const config = JSON.parse(
+                res.body.match(/id="app-browser-config">(.*?)<\/script>/)[1],
+            );
+            expect(Array.isArray(config.guestApps)).toBe(true);
+        }
+        const gui = await request('/embed/apps', {
+            host: `puter.localhost:${port}`,
+            referer: `http://puter.localhost:${port}/dashboard`,
+        });
+        expect(gui.headers['content-security-policy']).toBe("frame-ancestors 'self'");
+        const dashboard = await request('/dashboard', { host: `puter.localhost:${port}` });
+        expect(dashboard.headers['x-frame-options']).toBe('SAMEORIGIN');
+        const api = await request('/embed/apps', { host: `api.puter.localhost:${port}` });
+        expect(api.status).toBe(404);
+    });
+
+    it.each([
+        ['a user-hosted site', 'http://someone.site.puter.localhost:PORT/'],
+        ['a private app host', 'http://someone.app.puter.localhost:PORT/'],
+        ['the API host', 'http://api.puter.localhost:PORT/'],
+        ['the WebDAV host', 'http://dav.puter.localhost:PORT/'],
+        ['a native app host', 'http://about.puter.localhost:PORT/'],
+        ['a nested subdomain', 'http://a.spreadsheet.puter.localhost:PORT/'],
+        ['another site', 'http://evil.test:PORT/'],
+        ['another port', 'http://spreadsheet.puter.localhost:1/'],
+        ['a suppressed referrer', undefined],
+    ])('keeps the embed same-origin only when framed by %s', async (_label, referer) => {
+        const res = await request('/embed/apps', {
+            host: `puter.localhost:${port}`,
+            ...(referer ? { referer: referer.replace('PORT', String(port)) } : {}),
+        });
+        expect(res.status).toBe(200);
+        expect(res.headers['content-security-policy']).toBe("frame-ancestors 'self'");
+    });
+
+    it.each([
+        ['plain', ''],
+        // Past the parser's 1000-pair limit, so `req.query` comes back empty.
+        ['padded', '&'.repeat(1000)],
+    ])('strips %s SDK bootstrap query parameters from the embed route', async (_label, padding) => {
+        const res = await request(`/embed/apps?${padding}puter.app_instance_id=other&puter.api_origin=https://other.test`, {
+            host: `puter.localhost:${port}`,
+        });
+        expect(res.status).toBe(302);
+        expect(res.headers.location).toBe('/embed/apps');
+        expect(res.headers['x-frame-options']).toBe('SAMEORIGIN');
+    });
+
     it('blocks a request the ip.validate listeners veto', async () => {
         const handler = (_key: unknown, data: unknown) => {
             (data as { allow: boolean }).allow = false;
@@ -1492,6 +1556,104 @@ describe('PuterServer keep-alive timeout', () => {
 });
 
 describe('PuterServer lifecycle hooks', () => {
+    it('fails startup before running later hooks when a start hook rejects', async () => {
+        const failure = new Error('startup failed');
+        const later = vi.fn();
+        class FailingStart extends JobScheduler {
+            override async onServerStart() {
+                throw failure;
+            }
+        }
+        class LaterStart extends JobScheduler {
+            override async onServerStart() {
+                later();
+            }
+        }
+        extension.registerService('failingStart', FailingStart as never);
+        extension.registerService('laterStart', LaterStart as never);
+        try {
+            await expect(setupTestServer()).rejects.toBe(failure);
+            expect(later).not.toHaveBeenCalled();
+        } finally {
+            delete (extensionStore.services as Record<string, unknown>)
+                .failingStart;
+            delete (extensionStore.services as Record<string, unknown>)
+                .laterStart;
+        }
+    });
+
+    it.each([false, true])(
+        'continues teardown after failing hooks with listener callback %s',
+        async (prepareFirst) => {
+            const port = await allocateEphemeralPort();
+            const server = await setupTestServer(
+                { port } as unknown as IConfig,
+                { listen: true },
+            );
+            const logged = vi
+                .spyOn(console, 'error')
+                .mockImplementation(() => {});
+            const ran: string[] = [];
+            class FailingHooks {
+                onServerPrepareShutdown() {
+                    ran.push('prepare:failed');
+                    throw new Error('prepare failed');
+                }
+                async onServerShutdown() {
+                    ran.push('shutdown:failed');
+                    throw new Error('shutdown failed');
+                }
+            }
+            (server.services as Record<string, unknown>).fails =
+                new FailingHooks();
+            (server.services as Record<string, unknown>).after = {
+                onServerPrepareShutdown: () => ran.push('prepare:after'),
+                onServerShutdown: () => ran.push('shutdown:after'),
+            };
+            (server.clients as Record<string, unknown>).last = {
+                onServerShutdown: () => ran.push('shutdown:client'),
+            };
+            try {
+                if (prepareFirst) {
+                    await server.prepareShutdown();
+                    await vi.waitFor(() =>
+                        expect(ran).toContain('prepare:after'),
+                    );
+                }
+                await server.shutdown();
+                expect(ran).toEqual([
+                    'prepare:failed',
+                    'prepare:after',
+                    'shutdown:failed',
+                    'shutdown:after',
+                    'shutdown:client',
+                ]);
+                expect(logged).toHaveBeenCalledWith(
+                    '[server] onServerPrepareShutdown failed in FailingHooks',
+                    expect.any(Error),
+                );
+                expect(logged).toHaveBeenCalledWith(
+                    '[server] onServerShutdown failed in FailingHooks',
+                    expect.any(Error),
+                );
+                await expect(
+                    new Promise<void>((resolve, reject) => {
+                        const socket = net.connect(port, '127.0.0.1');
+                        socket.on('connect', () => {
+                            socket.destroy();
+                            resolve();
+                        });
+                        socket.on('error', reject);
+                    }),
+                ).rejects.toMatchObject({ code: 'ECONNREFUSED' });
+            } finally {
+                delete (server.services as Record<string, unknown>).fails;
+                await server.shutdown();
+                logged.mockRestore();
+            }
+        },
+    );
+
     it('runs drain-start and prepare-shutdown bottom-up, once, before tearing down', async () => {
         const port = await allocateEphemeralPort();
         const server = await setupTestServer({ port } as unknown as IConfig, {
@@ -1541,6 +1703,73 @@ describe('PuterServer lifecycle hooks', () => {
             'shutdown:client',
         ]);
     });
+
+    it('keeps accepting connections until every drain-start hook settles, without one holding up another', async () => {
+        const port = await allocateEphemeralPort();
+        const server = await setupTestServer({ port } as unknown as IConfig, {
+            listen: true,
+        });
+        let release!: () => void;
+        const held = new Promise<void>((resolve) => (release = resolve));
+        let otherRan = false;
+        (server.services as unknown as Record<string, unknown>).holdsListener =
+            { onServerDrainStart: () => held };
+        (server.drivers as unknown as Record<string, unknown>).other = {
+            onServerDrainStart: () => {
+                otherRan = true;
+            },
+        };
+
+        const connect = () =>
+            new Promise<void>((resolve, reject) => {
+                const socket = net.connect(port, '127.0.0.1');
+                socket.on('connect', () => {
+                    socket.destroy();
+                    resolve();
+                });
+                socket.on('error', reject);
+            });
+
+        const prepared = server.prepareShutdown({ drainMs: 1_000 });
+        await new Promise((resolve) => setTimeout(resolve, 20));
+        expect(otherRan).toBe(true);
+        await expect(connect()).resolves.toBeUndefined();
+
+        release();
+        await prepared;
+        await expect(connect()).rejects.toMatchObject({
+            code: 'ECONNREFUSED',
+        });
+        await server.shutdown();
+    });
+
+    it('runs every drain-start hook when one of them throws', async () => {
+        const port = await allocateEphemeralPort();
+        const server = await setupTestServer({ port } as unknown as IConfig, {
+            listen: true,
+        });
+        vi.spyOn(console, 'error').mockImplementation(() => {});
+        const ran: string[] = [];
+        (server.stores as unknown as Record<string, unknown>).fails = {
+            onServerDrainStart: () => {
+                throw new Error('drain hook failed');
+            },
+        };
+        (server.services as unknown as Record<string, unknown>).after = {
+            onServerDrainStart: () => {
+                ran.push('after');
+            },
+        };
+
+        await server.prepareShutdown({ drainMs: 1_000 });
+        await server.shutdown();
+
+        expect(ran).toEqual(['after']);
+        expect(console.error).toHaveBeenCalledWith(
+            expect.stringContaining('onServerDrainStart failed'),
+            expect.any(Error),
+        );
+    });
 });
 
 describe('PuterServer shutdown during prepare', () => {

src/backend/server.ts

@@ -1743,12 +1743,7 @@ export class PuterServer {
      */
     async #runHook(
         order: 'bottomUp' | 'topDown',
-        hook:
-            | 'onServerStart'
-            | 'onServerDrainStart'
-            | 'onServerPrepareShutdown'
-            | 'onServerShutdown',
-        info?: ServerDrainInfo,
+        hook: 'onServerStart' | 'onServerPrepareShutdown' | 'onServerShutdown',
     ) {
         const layers = [
             this.clients,
@@ -1760,11 +1755,47 @@ export class PuterServer {
         if (order === 'topDown') layers.reverse();
         for (const layer of layers) {
             for (const instance of Object.values(layer) as WithLifecycle[]) {
-                await instance[hook]?.(info);
+                try {
+                    await instance[hook]?.();
+                } catch (err) {
+                    if (hook === 'onServerStart') throw err;
+                    console.error(
+                        `[server] ${hook} failed in ${instance.constructor.name}`,
+                        err,
+                    );
+                }
             }
         }
     }
 
+    /**
+     * Run every `onServerDrainStart` concurrently, so one hook holding the
+     * listener open doesn't delay the others, and one failing doesn't skip the
+     * rest.
+     */
+    async #runDrainStartHooks(info: ServerDrainInfo) {
+        const instances = [
+            this.clients,
+            this.stores,
+            this.services,
+            this.controllers,
+            this.drivers,
+        ].flatMap((layer) => Object.values(layer) as WithLifecycle[]);
+        const results = await Promise.allSettled(
+            instances.map(async (instance) =>
+                instance.onServerDrainStart?.(info),
+            ),
+        );
+        results.forEach((result, i) => {
+            if (result.status === 'rejected') {
+                console.error(
+                    `[server] onServerDrainStart failed in ${instances[i].constructor.name}`,
+                    result.reason,
+                );
+            }
+        });
+    }
+
     #prepareShutdownHooks: Promise<void> | null = null;
 
     /**
@@ -1782,16 +1813,19 @@ export class PuterServer {
 
     async prepareShutdown(info: ServerDrainInfo = {}) {
         if (this.#server) {
-            try {
-                await this.#runHook('bottomUp', 'onServerDrainStart', info);
-            } catch (err) {
-                console.error('[server] onServerDrainStart failed', err);
-            }
+            await this.#runDrainStartHooks(info);
             this.#server.close(async () => {
                 console.log(
                     'PuterServer has stopped accepting new connections',
                 );
-                await this.#runPrepareShutdownHooks();
+                try {
+                    await this.#runPrepareShutdownHooks();
+                } catch (err) {
+                    console.error(
+                        '[server] prepare-shutdown hooks failed',
+                        err,
+                    );
+                }
             });
         }
     }

src/backend/services/apps/RecommendedAppsService.ts

@@ -27,17 +27,16 @@ import { PuterService } from '../types.js';
  */
 export const RECOMMENDED_APP_NAMES = [
     'builder',
+    'word-processor',
+    'spreadsheet',
+    'presentation',
+    'whiteboard',
+    'pdf-editor',
     'contacts',
     'calendar',
     'meetings',
     'teamchat',
     'email',
-    'whiteboard',
-    'spreadsheet',
-    'word-processor',
-    'presentation',
-    'pdf-editor',
-    'terminal',
     'dev-center',
     'cap-table',
     'invoices',

src/backend/services/broadcast/BroadcastService.test.ts

@@ -1149,3 +1149,154 @@ describe('BroadcastService — same-cluster pub/sub fan-out', () => {
         }
     });
 });
+
+describe('BroadcastService shutdown drain', () => {
+    let server: PuterServer;
+    let broadcast: BroadcastService;
+
+    beforeEach(async () => {
+        axiosRequestMock.mockReset();
+        axiosRequestMock.mockResolvedValue({ status: 200, data: 'ok' });
+        server = await setupTestServer({
+            broadcast: {
+                webhook: { peerId: SELF_PEER_ID, secret: SELF_SECRET },
+                peers: [
+                    {
+                        peerId: PEER_ID,
+                        webhook: true,
+                        webhook_url: PEER_URL,
+                        webhook_secret: PEER_SECRET,
+                    },
+                ],
+                outbound_flush_ms: 10,
+            },
+        } as never);
+        broadcast = server.services.broadcast as unknown as BroadcastService;
+    });
+
+    afterEach(async () => {
+        vi.useRealTimers();
+        await broadcast.onServerPrepareShutdown();
+        await broadcast.onServerShutdown();
+        await server.shutdown();
+    });
+
+    const emit = (hash: string) =>
+        server.clients.event.emit(
+            'outer.fs.write-hash' as never,
+            { hash, uuid: hash } as never,
+            {},
+        );
+
+    it.each(['onServerPrepareShutdown', 'onServerShutdown'] as const)(
+        'waits for the active flush and sends its tail in %s',
+        async (hook) => {
+            let release!: () => void;
+            const held = new Promise<void>((resolve) => {
+                release = resolve;
+            });
+            let releaseTail!: () => void;
+            const tailHeld = new Promise<void>((resolve) => {
+                releaseTail = resolve;
+            });
+            axiosRequestMock
+                .mockImplementationOnce(async () => {
+                    await held;
+                    return { status: 200, data: 'ok' };
+                })
+                .mockImplementationOnce(async () => {
+                    await tailHeld;
+                    return { status: 200, data: 'ok' };
+                });
+            emit('first');
+            await vi.waitFor(() =>
+                expect(axiosRequestMock).toHaveBeenCalledTimes(1),
+            );
+            emit('tail');
+            let finished = false;
+            const draining = broadcast[hook]().then(() => {
+                finished = true;
+            });
+            try {
+                await new Promise((resolve) => setTimeout(resolve, 20));
+                expect(finished).toBe(false);
+                release();
+                await vi.waitFor(() =>
+                    expect(axiosRequestMock).toHaveBeenCalledTimes(2),
+                );
+                expect(finished).toBe(false);
+            } finally {
+                release();
+                releaseTail();
+                await draining;
+            }
+            expect(axiosRequestMock).toHaveBeenCalledTimes(2);
+            expect(axiosRequestMock.mock.calls[1][0].data).toContain('tail');
+        },
+    );
+
+    it('keeps normal timer flushing after prepare on an idle server', async () => {
+        await broadcast.onServerPrepareShutdown();
+        vi.useFakeTimers();
+        axiosRequestMock.mockClear();
+        emit('during-drain');
+        await vi.advanceTimersByTimeAsync(10);
+        expect(axiosRequestMock).toHaveBeenCalledTimes(1);
+        expect(axiosRequestMock.mock.calls[0][0].data).toContain(
+            'during-drain',
+        );
+    });
+
+    it('sends events queued after prepare during shutdown and clears the timer', async () => {
+        await broadcast.onServerPrepareShutdown();
+        vi.useFakeTimers();
+        axiosRequestMock.mockClear();
+        emit('after-prepare');
+        await broadcast.onServerShutdown();
+        expect(axiosRequestMock).toHaveBeenCalledTimes(1);
+        expect(axiosRequestMock.mock.calls[0][0].data).toContain(
+            'after-prepare',
+        );
+        axiosRequestMock.mockClear();
+        await vi.advanceTimersByTimeAsync(100);
+        expect(axiosRequestMock).not.toHaveBeenCalled();
+    });
+
+    it.each(['onServerPrepareShutdown', 'onServerShutdown'] as const)(
+        'bounds a hung flush in %s',
+        async (hook) => {
+            let release!: () => void;
+            const held = new Promise<void>((resolve) => {
+                release = resolve;
+            });
+            axiosRequestMock.mockImplementationOnce(async () => {
+                await held;
+                return { status: 200, data: 'ok' };
+            });
+            emit('hung');
+            await vi.waitFor(() =>
+                expect(axiosRequestMock).toHaveBeenCalledTimes(1),
+            );
+            vi.useFakeTimers();
+            emit('tail');
+            let finished = false;
+            const draining = broadcast[hook]().then(() => {
+                finished = true;
+            });
+            try {
+                await vi.advanceTimersByTimeAsync(4_999);
+                expect(finished).toBe(false);
+                await vi.advanceTimersByTimeAsync(1);
+                await draining;
+                release();
+                await vi.advanceTimersByTimeAsync(100);
+                expect(axiosRequestMock).toHaveBeenCalledTimes(
+                    hook === 'onServerPrepareShutdown' ? 2 : 1,
+                );
+            } finally {
+                release();
+                vi.useRealTimers();
+            }
+        },
+    );
+});

src/backend/services/broadcast/BroadcastService.ts

@@ -21,6 +21,8 @@ import axios from 'axios';
 import { createHmac, randomUUID, timingSafeEqual } from 'node:crypto';
 import { Agent as HttpsAgent } from 'node:https';
 import { IBroadcastPeerConfig } from '../../types.js';
+import { settleWithin } from '../../util/concurrency.js';
+import { FINAL_FLUSH_TIMEOUT_MS } from '../../util/gracefulShutdown.js';
 import { PuterService } from '../types.js';
 
 // -- Wire types ------------------------------------------------------
@@ -121,7 +123,8 @@ export class BroadcastService extends PuterService {
     /** Per peer, serialized events it has not accepted yet, oldest first. */
     #outboundBacklogs = new Map<IBroadcastPeerConfig, string[]>();
     #outboundFlushTimer: ReturnType<typeof setTimeout> | null = null;
-    #outboundIsFlushing = false;
+    #outboundFlush: Promise<void> | null = null;
+    #outboundDraining = false;
 
     #webhookReplayWindowSeconds = 300;
     #outboundFlushMs = 2000;
@@ -165,21 +168,40 @@ export class BroadcastService extends PuterService {
     }
 
     override async onServerPrepareShutdown(): Promise<void> {
+        await this.#drainOutboundEvents();
+        if (this.#redisSub) {
+            try {
+                await this.#redisSub.unsubscribe('pubsub');
+                this.#redisSub.quit();
+            } catch (err) {
+                console.warn('[broadcast] unsubscribe failed', err);
+            } finally {
+                this.#redisSub = null;
+            }
+        }
+    }
+
+    override async onServerShutdown(): Promise<void> {
+        this.#outboundDraining = true;
+        await this.#drainOutboundEvents();
+    }
+
+    async #drainOutboundEvents(): Promise<void> {
         if (this.#outboundFlushTimer) {
             clearTimeout(this.#outboundFlushTimer);
             this.#outboundFlushTimer = null;
         }
-        // Best-effort drain — try one final flush so events queued near
-        // shutdown make it out.
-        try {
-            await this.#flushOutboundEvents();
-        } catch (err) {
-            console.warn('[broadcast] final flush failed', err);
-        }
-        if (this.#redisSub) {
-            await this.#redisSub.unsubscribe('pubsub');
-            this.#redisSub.quit();
-            this.#redisSub = null;
+        const deadline = Date.now() + FINAL_FLUSH_TIMEOUT_MS;
+        const drain = async () => {
+            try {
+                await this.#outboundFlush;
+                if (Date.now() < deadline) await this.#flushOutboundEvents();
+            } catch (err) {
+                console.warn('[broadcast] final flush failed', err);
+            }
+        };
+        if (!(await settleWithin(drain(), FINAL_FLUSH_TIMEOUT_MS))) {
+            console.warn('[broadcast] final flush timed out');
         }
     }
 
@@ -453,24 +475,27 @@ export class BroadcastService extends PuterService {
     }
 
     #scheduleOutboundFlush(): void {
-        if (this.#outboundFlushTimer) return;
-        this.#outboundFlushTimer = setTimeout(() => {
+        if (this.#outboundDraining || this.#outboundFlushTimer) return;
+        this.#outboundFlushTimer = setTimeout(async () => {
             this.#outboundFlushTimer = null;
-            void this.#flushOutboundEvents().catch((err) => {
+            try {
+                await this.#flushOutboundEvents();
+            } catch (err) {
                 console.warn('[broadcast] outbound flush failed', err);
-            });
+            }
         }, this.#outboundFlushMs);
     }
 
-    async #flushOutboundEvents(): Promise<void> {
-        if (
-            this.#outboundIsFlushing ||
-            (this.#outboundQueue.size === 0 &&
-                this.#outboundBacklogs.size === 0)
-        )
-            return;
+    #flushOutboundEvents(): Promise<void> {
+        if (this.#outboundFlush) return this.#outboundFlush;
+        if (this.#outboundQueue.size === 0 && this.#outboundBacklogs.size === 0)
+            return Promise.resolve();
 
-        this.#outboundIsFlushing = true;
+        this.#outboundFlush = this.#sendOutboundEvents();
+        return this.#outboundFlush;
+    }
+
+    async #sendOutboundEvents(): Promise<void> {
         try {
             const fresh = this.#outboundQueue;
             this.#outboundQueue = new Set();
@@ -504,7 +529,7 @@ export class BroadcastService extends PuterService {
             for (const result of flushed)
                 if (result.status === 'rejected') throw result.reason;
         } finally {
-            this.#outboundIsFlushing = false;
+            this.#outboundFlush = null;
             // Anything that arrived during flush, or is still owed to a peer,
             // gets the next tick.
             if (

src/backend/services/events/EventsService.test.ts

@@ -185,7 +185,11 @@ const aclService = () => ({
         !denied.has(resource.path) && !deniedHolders.has(actor.user?.id ?? -1),
     getSafeAclError: async (_actor: Actor, resource: { path: string }) =>
         denied.get(resource.path) === 'forbidden'
-            ? { status: 403, message: 'Forbidden', fields: { code: 'forbidden' } }
+            ? {
+                  status: 403,
+                  message: 'Forbidden',
+                  fields: { code: 'forbidden' },
+              }
             : {
                   status: 404,
                   message: 'Subject does not exist',
@@ -281,8 +285,8 @@ interface ForwardedCall {
 }
 
 /**
- * Each service gets its own outbox. A delivery still in flight when a test
- * ends must land in that test's record, not in the next one's.
+ * Each service gets its own outbox. A delivery still in flight when a test ends
+ * must land in that test's record, not in the next one's.
  */
 const buildService = (
     config: IConfig,
@@ -350,10 +354,7 @@ const buildService = (
             acl: aclService(),
             permission: permissionService(),
             metering: {
-                bufferIncrementUsages: (
-                    actor: Actor,
-                    usages: UsageInput[],
-                ) => {
+                bufferIncrementUsages: (actor: Actor, usages: UsageInput[]) => {
                     for (const usage of usages)
                         lines.push({
                             userUuid: actor.user?.uuid,
@@ -597,6 +598,13 @@ describe('the feature switch', () => {
                 nearPrimary: true,
                 leaseMs: 15 * 60_000,
             },
+            {
+                name: 'events.userHandlers.gc',
+                every: 60 * 60_000,
+                scope: 'fleet',
+                nearPrimary: true,
+                leaseMs: 15 * 60_000,
+            },
             {
                 name: 'events.subscriptions.creditSweep',
                 every: 15 * 60_000,
@@ -1256,7 +1264,9 @@ describe('matching', () => {
     it('stops delivering to a durable row the moment it expires', async () => {
         const { documents, file } = seedTree();
         const now = Math.floor(Date.now() / 1000);
-        const row = (over: Partial<DurableSubscription>): DurableSubscription => ({
+        const row = (
+            over: Partial<DurableSubscription>,
+        ): DurableSubscription => ({
             subId: `durable-${seq}-${over.expiresAt}`,
             token: `f#${documents.uid}`,
             ownerUserId: userId,
@@ -1405,9 +1415,9 @@ describe('matching', () => {
         await dispatch(closed);
         await flush();
 
-        expect(sent.map((s) => (s.envelope.event as { uid: string }).uid)).toEqual([
-            reachable.uid,
-        ]);
+        expect(
+            sent.map((s) => (s.envelope.event as { uid: string }).uid),
+        ).toEqual([reachable.uid]);
     });
 
     it('publishes nothing for an event with no registry entry', async () => {
@@ -1449,9 +1459,9 @@ describe('matching', () => {
         await flush();
 
         expect(sent).toHaveLength(1);
-        expect(
-            (sent[0].envelope.event as { path: string }).path,
-        ).toBe(inside.path);
+        expect((sent[0].envelope.event as { path: string }).path).toBe(
+            inside.path,
+        );
     });
 
     it('does not reach a sibling that only shares the missing name as a prefix', async () => {
@@ -1523,8 +1533,9 @@ describe('coalescing', () => {
         await vi.advanceTimersByTimeAsync(EVENTS_COALESCE_WINDOW_MS + 1);
 
         expect(sent).toHaveLength(2);
-        expect(sent.map((s) => (s.envelope.event as { uid: string }).uid).sort())
-            .toEqual([file.uid, second.uid].sort());
+        expect(
+            sent.map((s) => (s.envelope.event as { uid: string }).uid).sort(),
+        ).toEqual([file.uid, second.uid].sort());
     });
 
     it('counts exactly what it delivered', async () => {
@@ -1670,9 +1681,9 @@ describe('limits', () => {
             }
         }
 
-        await expect(subscribe(`fs:${documents.uid}`)).resolves.toMatchObject(
-            { subId: expect.any(String) },
-        );
+        await expect(subscribe(`fs:${documents.uid}`)).resolves.toMatchObject({
+            subId: expect.any(String),
+        });
     });
 
     it('refuses unsubscribes past their own per-minute budget', async () => {
@@ -1741,9 +1752,7 @@ describe('limits', () => {
             ),
         );
 
-        expect(results.filter((r) => r.status === 'fulfilled')).toHaveLength(
-            1,
-        );
+        expect(results.filter((r) => r.status === 'fulfilled')).toHaveLength(1);
         expect(results.filter((r) => r.status === 'rejected')).toHaveLength(
             attempts - 1,
         );
@@ -1940,9 +1949,9 @@ describe('limits', () => {
         ).toHaveLength(EVENTS_MATCHED_SUBSCRIPTIONS_PER_EVENT);
         // 200 evaluated, 20 never reached: everything past the delivery cap is
         // told it missed something, itself capped.
-        expect(
-            sent.filter((s) => s.envelope.event.op === 'gap'),
-        ).toHaveLength(EVENTS_MATCHED_SUBSCRIPTIONS_PER_EVENT);
+        expect(sent.filter((s) => s.envelope.event.op === 'gap')).toHaveLength(
+            EVENTS_MATCHED_SUBSCRIPTIONS_PER_EVENT,
+        );
         expect(
             sent.find((s) => s.envelope.event.op === 'gap')?.envelope.event,
         ).toMatchObject({ reason: 'filter_evaluation_limit' });
@@ -1993,8 +2002,7 @@ describe('the socket surface', () => {
             fire: (event, ...args) =>
                 (
                     handlers.get(event) as
-                        | ((...a: unknown[]) => void)
-                        | undefined
+                        ((...a: unknown[]) => void) | undefined
                 )?.(...args),
         };
     };
@@ -2175,10 +2183,14 @@ it('names the delivery channel the clients listen on', () => {
 
 describe('asking a kv subscription for the value', () => {
     it('is recorded on the row and reported in the view', async () => {
-        const { sub } = await service.subscribe(appActorFor(OWN_APP), socketId, {
-            subject: `kv:${OWN_APP}:cart`,
-            includeValue: true,
-        });
+        const { sub } = await service.subscribe(
+            appActorFor(OWN_APP),
+            socketId,
+            {
+                subject: `kv:${OWN_APP}:cart`,
+                includeValue: true,
+            },
+        );
         expect(sub.includeValue).toBe(true);
 
         const plain = await subscribeKv(`kv:${OWN_APP}:cart`);
@@ -2261,10 +2273,7 @@ describe('resolving a kv subject', () => {
     });
 
     it('refuses a pattern the grammar cannot enumerate from a key', async () => {
-        for (const subject of [
-            `kv:${OWN_APP}:ca*rt`,
-            `kv:${OWN_APP}:cart?`,
-        ])
+        for (const subject of [`kv:${OWN_APP}:ca*rt`, `kv:${OWN_APP}:cart?`])
             await expect(subscribeKv(subject)).rejects.toSatisfy(
                 (err: unknown) =>
                     isHttpError(err) && err.legacyCode === 'invalid_kv_pattern',
@@ -2379,8 +2388,7 @@ describe('delivering a kv change', () => {
 
     const eventFor = (subId: string) =>
         sent.find((one) => one.envelope.subId === subId)?.envelope.event as
-            | Record<string, unknown>
-            | undefined;
+            Record<string, unknown> | undefined;
 
     it('hands the value to the row that asked for it and to no other', async () => {
         vi.useFakeTimers();
@@ -2495,7 +2503,9 @@ describe('delivering a kv change', () => {
         await dispatchKv(['cart'], { values: ['kept'] });
         await vi.advanceTimersByTimeAsync(EVENTS_COALESCE_WINDOW_MS + 1);
 
-        const deliveries = sent.filter((one) => one.envelope.event.op === 'set');
+        const deliveries = sent.filter(
+            (one) => one.envelope.event.op === 'set',
+        );
         const gaps = sent.filter((one) => one.envelope.event.op === 'gap');
         expect(deliveries).toHaveLength(128);
         expect(gaps).toHaveLength(1);
@@ -2542,12 +2552,12 @@ describe('delivering a kv change', () => {
         await dispatchKv(['cart']);
         await vi.advanceTimersByTimeAsync(EVENTS_COALESCE_WINDOW_MS + 1);
 
-        expect(sent.filter((one) => one.envelope.event.op === 'set')).toHaveLength(
-            EVENTS_KV_MATCHED_SUBSCRIPTIONS_PER_EVENT.limit,
-        );
-        expect(sent.filter((one) => one.envelope.event.op === 'gap')).toHaveLength(
-            1,
-        );
+        expect(
+            sent.filter((one) => one.envelope.event.op === 'set'),
+        ).toHaveLength(EVENTS_KV_MATCHED_SUBSCRIPTIONS_PER_EVENT.limit);
+        expect(
+            sent.filter((one) => one.envelope.event.op === 'gap'),
+        ).toHaveLength(1);
     });
 
     it('uses the free KV limit when owner policy lookup fails', async () => {
@@ -2558,7 +2568,9 @@ describe('delivering a kv change', () => {
         await dispatchKv(['cart']);
         await vi.advanceTimersByTimeAsync(EVENTS_COALESCE_WINDOW_MS + 1);
 
-        expect(sent.filter((one) => one.envelope.event.op === 'set')).toHaveLength(
+        expect(
+            sent.filter((one) => one.envelope.event.op === 'set'),
+        ).toHaveLength(
             EVENTS_KV_MATCHED_SUBSCRIPTIONS_PER_EVENT.bySubscription[
                 DEFAULT_FREE_SUBSCRIPTION
             ],
@@ -2571,7 +2583,9 @@ describe('delivering a kv change', () => {
         await seedKvSubscriptions(
             EVENTS_KV_FILTER_EVALUATIONS_PER_EVENT.bySubscription[
                 DEFAULT_FREE_SUBSCRIPTION
-            ] - 128 + 1,
+            ] -
+                128 +
+                1,
             { includeValue: true, match: 'elsewhere', tag: 'filtered-out' },
         );
 
@@ -2593,7 +2607,9 @@ describe('delivering a kv change', () => {
         });
         await vi.advanceTimersByTimeAsync(EVENTS_COALESCE_WINDOW_MS + 1);
 
-        const deliveries = sent.filter((one) => one.envelope.event.op === 'set');
+        const deliveries = sent.filter(
+            (one) => one.envelope.event.op === 'set',
+        );
         expect(deliveries).toHaveLength(128);
         expect(
             deliveries.every(
@@ -2819,8 +2835,7 @@ describe('what a kv dispatch costs', () => {
 });
 
 describe('the cross-app kv gate', () => {
-    const grantRead = (app: string) =>
-        grants.add(`app-data:${app}:kv:read`);
+    const grantRead = (app: string) => grants.add(`app-data:${app}:kv:read`);
 
     const crossAppService = () =>
         buildService({
@@ -2884,7 +2899,8 @@ describe('the cross-app kv gate', () => {
         ({ service } = crossAppService());
 
         await expect(subscribeKv(`kv:${OTHER_APP}:cart`)).rejects.toSatisfy(
-            (err: unknown) => isHttpError(err) && err.legacyCode === 'forbidden',
+            (err: unknown) =>
+                isHttpError(err) && err.legacyCode === 'forbidden',
         );
     });
 
@@ -2895,8 +2911,7 @@ describe('the cross-app kv gate', () => {
 
         await expect(subscribeKv('kv:app-gone:cart')).rejects.toSatisfy(
             (err: unknown) =>
-                isHttpError(err) &&
-                err.legacyCode === 'subject_does_not_exist',
+                isHttpError(err) && err.legacyCode === 'subject_does_not_exist',
         );
     });
 
@@ -2910,7 +2925,8 @@ describe('the cross-app kv gate', () => {
         });
 
         await expect(subscribeKv(`kv:${OTHER_APP}:cart`)).rejects.toSatisfy(
-            (err: unknown) => isHttpError(err) && err.legacyCode === 'forbidden',
+            (err: unknown) =>
+                isHttpError(err) && err.legacyCode === 'forbidden',
         );
     });
 
@@ -3185,9 +3201,7 @@ describe('cross-user kv handles', () => {
         expect(off.kvHandlesEnabled).toBe(false);
         expect(service.kvHandlesEnabled).toBe(true);
 
-        await expect(
-            subscribeAsGuest(`kv:${handle}:*`, off),
-        ).rejects.toSatisfy(
+        await expect(subscribeAsGuest(`kv:${handle}:*`, off)).rejects.toSatisfy(
             (err: unknown) =>
                 isHttpError(err) &&
                 err.legacyCode === 'events_kv_handles_disabled',
@@ -3395,10 +3409,13 @@ describe('cross-user kv handles', () => {
     it.each([
         ['an unknown handle', () => undefined],
         ['a revoked handle', () => mintHandle({ revokedAt: 1 })],
-        ['a handle whose grant the caller does not hold', () => {
-            mintHandle();
-            grants.delete(permission);
-        }],
+        [
+            'a handle whose grant the caller does not hold',
+            () => {
+                mintHandle();
+                grants.delete(permission);
+            },
+        ],
     ])('answers %s as absent', async (_case, setUp) => {
         setUp();
         await expect(subscribeAsGuest(`kv:${handle}:*`)).rejects.toSatisfy(

src/backend/services/events/appDeletion.integration.test.ts

@@ -19,20 +19,29 @@
 
 /**
  * What deleting an app leaves behind on the events side: its durable rows,
- * their backlog and its published handlers can never deliver again — the
- * grant identity they are re-checked under no longer resolves — so
- * `settleDeletedApp` tears them down on the `app.changed` bus key rather than
- * leaving them to cost their holder an anchor slot forever. Also the hourly
- * sweep that catches whatever neither this nor `workers.destroy` reached.
+ * their backlog and its published handlers can never deliver again — the grant
+ * identity they are re-checked under no longer resolves — so `settleDeletedApp`
+ * tears them down on the `app.changed` bus key rather than leaving them to cost
+ * their holder an anchor slot forever. Also the hourly sweep that catches
+ * whatever neither this nor `workers.destroy` reached.
  */
 
-import { afterAll, beforeAll, beforeEach, describe, expect, it, vi } from 'vitest';
+import {
+    afterAll,
+    beforeAll,
+    beforeEach,
+    describe,
+    expect,
+    it,
+    vi,
+} from 'vitest';
 import { v4 as uuidv4 } from 'uuid';
 import { setupPuterTestEnv, type PuterTestEnv } from '../../testUtil.js';
 import { testJobContext } from '../jobs/jobsTestUtil.js';
 import type { IConfig } from '../../types.js';
 import { EVENTS_BACKGROUND_PERMISSION } from './authorization.js';
 import { EVENTS_WORKER_SESSION_NAME } from './workerRuntime.js';
+import { appHandlerScope } from '../../stores/events/EventHandlerStore.js';
 
 const BOOT_TIMEOUT_MS = 120_000;
 
@@ -126,10 +135,13 @@ const emitDeleted = async (appUid: string): Promise<void> => {
 const publish = (
     token: string,
     body: { appUid: string; name: string; source: string },
-): Promise<ApiResponse> => call('POST', '/events/handlers/publish', token, body);
+): Promise<ApiResponse> =>
+    call('POST', '/events/handlers/publish', token, body);
 
-/** A durable `single` subscription bound to a published handler, with the
- * grants a background delivery needs. Returns the subscribed subId. */
+/**
+ * A durable `single` subscription bound to a published handler, with the grants
+ * a background delivery needs. Returns the subscribed subId.
+ */
 const subscribeBackgroundHandler = async (
     app: { uid: string; token: string },
     handlerName: string,
@@ -163,6 +175,87 @@ const subscribeBackgroundHandler = async (
     return subscribed.body.subId as string;
 };
 
+describe('user scopes of a deleted app or account', () => {
+    const publishUserHandler = (
+        appUid: string,
+        holder: number,
+        name = 'mine',
+    ) =>
+        env.server.stores.eventHandler.publish({
+            scope: { appUid, holder },
+            name,
+            source: SOURCE,
+            broadcast: false,
+        });
+    const userHandlers = (appUid: string, holder: number) =>
+        env.server.stores.eventHandler.listForApp({ appUid, holder });
+
+    let destroyed: Array<{ appUid: string; scope: string; userId: number }>;
+    beforeAll(() => {
+        env.server.clients.event.on('events.worker.destroy', (_key, event) => {
+            destroyed?.push({
+                appUid: event.appUid,
+                scope: event.scope,
+                userId: event.actor.user.id,
+            });
+        });
+    });
+    beforeEach(async () => {
+        destroyed = [];
+        await env.server.clients.db.write(
+            'DELETE FROM `event_user_handlers`',
+            [],
+        );
+    });
+
+    it('removes every holder`s scope with the app, announcing each as the holder', async () => {
+        const app = await makeApp(userId);
+        await publishUserHandler(app.uid, userId);
+        await publishUserHandler(app.uid, otherUserId);
+        await publishUserHandler(app.uid, otherUserId, 'second');
+        const untouched = await makeApp(userId);
+        await publishUserHandler(untouched.uid, userId);
+
+        await emitDeleted(app.uid);
+
+        expect(await userHandlers(app.uid, userId)).toEqual([]);
+        expect(await userHandlers(app.uid, otherUserId)).toEqual([]);
+        expect(
+            destroyed
+                .filter((event) => event.scope === 'user')
+                .map((event) => [event.appUid, event.userId])
+                .sort(),
+        ).toEqual(
+            [
+                [app.uid, userId],
+                [app.uid, otherUserId],
+            ].sort(),
+        );
+        // Another app's scope is not touched.
+        expect(await userHandlers(untouched.uid, userId)).toHaveLength(1);
+    });
+
+    it('removes a deleted account`s scopes in every app, and no one else`s', async () => {
+        const first = await makeApp(userId);
+        const second = await makeApp(userId);
+        for (const app of [first, second]) {
+            await publishUserHandler(app.uid, otherUserId);
+            await publishUserHandler(app.uid, userId);
+        }
+
+        await env.server.clients.event.emitAndWait(
+            'user.delete',
+            { user_id: otherUserId, appUids: [] },
+            {},
+        );
+
+        for (const app of [first, second]) {
+            expect(await userHandlers(app.uid, otherUserId)).toEqual([]);
+            expect(await userHandlers(app.uid, userId)).toHaveLength(1);
+        }
+    });
+});
+
 describe('an app deleted while it has events state', () => {
     it('clears the rows, the backlog and the handlers when the app is deleted', async () => {
         const app = await makeApp(userId);
@@ -187,15 +280,17 @@ describe('an app deleted while it has events state', () => {
 
         await emitDeleted(app.uid);
 
-        const listed = await env.server.stores.durableSubscription.listForHolder(
-            userId,
-            { appUid: app.uid },
-        );
+        const listed =
+            await env.server.stores.durableSubscription.listForHolder(userId, {
+                appUid: app.uid,
+            });
         expect(listed.items).toEqual([]);
         expect(await env.server.stores.pendingDelivery.depth(subId)).toBe(0);
-        expect(await env.server.stores.eventHandler.listForApp(app.uid)).toEqual(
-            [],
-        );
+        expect(
+            await env.server.stores.eventHandler.listForApp(
+                appHandlerScope(app.uid),
+            ),
+        ).toEqual([]);
     });
 
     it("clears the rows and handlers of a deleted account's apps, and the account's subscription keys", async () => {
@@ -218,14 +313,16 @@ describe('an app deleted while it has events state', () => {
             {},
         );
 
-        const listed = await env.server.stores.durableSubscription.listForHolder(
-            userId,
-            { appUid: app.uid },
-        );
+        const listed =
+            await env.server.stores.durableSubscription.listForHolder(userId, {
+                appUid: app.uid,
+            });
         expect(listed.items).toEqual([]);
-        expect(await env.server.stores.eventHandler.listForApp(app.uid)).toEqual(
-            [],
-        );
+        expect(
+            await env.server.stores.eventHandler.listForApp(
+                appHandlerScope(app.uid),
+            ),
+        ).toEqual([]);
         expect(
             await env.server.stores.eventSubscription.isRegionWarm(goneUserId),
         ).toBe(false);
@@ -260,12 +357,10 @@ describe('an app deleted while it has events state', () => {
             expiresAt: null,
         });
 
-        const { actor: ownerActor } = await env.server.services.auth.authenticate(
-            env.users.user.token,
-        );
-        const { actor: otherActor } = await env.server.services.auth.authenticate(
-            env.users.other.token,
-        );
+        const { actor: ownerActor } =
+            await env.server.services.auth.authenticate(env.users.user.token);
+        const { actor: otherActor } =
+            await env.server.services.auth.authenticate(env.users.other.token);
         const ownerToken = await env.server.services.auth.createWorkerAppToken(
             ownerActor!,
             app.uid,

src/backend/services/events/fetch.integration.test.ts

@@ -616,6 +616,210 @@ describe('reading again from a saved cursor', () => {
     });
 });
 
+describe('starting from the end', () => {
+    const SUBJECT = 'notif:app-user';
+
+    const message = async (title: string, inApp = appUid): Promise<string> =>
+        (
+            await env.server.stores.notification.create({
+                userId,
+                value: { type: 'app.message', title },
+                type: 'app.message',
+                audience: 'app-user',
+                appUid: inApp,
+                group: `group-${uuidv4()}`,
+            })
+        ).uid as string;
+
+    const fromEnd = async (token = appToken): Promise<string> => {
+        const end = await fetchPage(token, { subject: SUBJECT, from: 'end' });
+        expect(end.status).toBe(200);
+        expect(end.body.items).toEqual([]);
+        expect(end.body.cursor).toBeTruthy();
+        return end.body.cursor!;
+    };
+
+    it('answers a cursor on an empty slice that returns what comes after', async () => {
+        await clearMailboxes();
+        const cursor = await fromEnd();
+
+        const later = await message('later');
+        const next = await fetchPage(appToken, { subject: SUBJECT, cursor });
+        expect(uidsOf(next)).toEqual([later]);
+    });
+
+    it('skips what is there and returns only newer rows', async () => {
+        await clearMailboxes();
+        for (let i = 0; i < 3; i++) await message(`before ${i}`);
+        const cursor = await fromEnd();
+
+        const quiet = await fetchPage(appToken, { subject: SUBJECT, cursor });
+        expect(quiet.body.items).toEqual([]);
+        expect(quiet.body.cursor).toBeUndefined();
+
+        const later = [await message('after 0'), await message('after 1')];
+        const next = await fetchPage(appToken, { subject: SUBJECT, cursor });
+        expect(uidsOf(next)).toEqual(later);
+    });
+
+    it('returns a row replaced after the cursor was taken', async () => {
+        await clearMailboxes();
+        const old = await message('old');
+        await message('older still unchanged');
+        const cursor = await fromEnd();
+
+        await env.server.services.notification.notifyUpdate(
+            old,
+            userId,
+            { title: 'replaced' },
+            { type: 'app.message', replace: true },
+        );
+
+        const next = await fetchPage(appToken, { subject: SUBJECT, cursor });
+        expect(uidsOf(next)).toEqual([old]);
+        expect(next.body.items![0]).toMatchObject({
+            replaced: true,
+            notification: { title: 'replaced' },
+        });
+    });
+
+    it('returns a replacement stamped by a clock behind the server`s', async () => {
+        await clearMailboxes();
+        const behind = Date.now() - 60_000;
+        const [early, late] = [await message('early'), await message('late')];
+        const replace = (uid: string, title: string, replacedAt: number) =>
+            env.server.stores.notification.updateValue(
+                uid,
+                userId,
+                { type: 'app.message', title },
+                { onlyUnseen: true, replacedAt },
+            );
+        await replace(early, 'replaced before', behind - 1_000);
+        const cursor = await fromEnd();
+
+        await replace(late, 'replaced after', behind);
+
+        const next = await fetchPage(appToken, { subject: SUBJECT, cursor });
+        expect(uidsOf(next)).toEqual([late]);
+        expect(next.body.items![0]).toMatchObject({
+            notification: { title: 'replaced after' },
+        });
+    });
+
+    it('keeps to the slice the subject names', async () => {
+        await clearMailboxes();
+        await message('own before');
+        const cursor = await fromEnd();
+
+        await message('other app', otherAppUid);
+        await seed(userId, { title: 'account row' });
+        const own = await message('own after');
+
+        const next = await fetchPage(appToken, { subject: SUBJECT, cursor });
+        expect(uidsOf(next)).toEqual([own]);
+    });
+
+    it('answers no cursor for a slice the caller cannot see', async () => {
+        await clearMailboxes();
+        await message('other app', otherAppUid);
+
+        for (const [token, subject] of [
+            [appToken, `notif:${otherAppUid}:app-user`],
+            [appToken, `notif:${userUuid}:account`],
+            [appReadUrlToken, SUBJECT],
+        ] as const) {
+            const page = await fetchPage(token, { subject, from: 'end' });
+            expect(page.status).toBe(200);
+            expect(page.body.items).toEqual([]);
+            expect(page.body.cursor).toBeUndefined();
+        }
+    });
+
+    it('reads from the cursor when one is given', async () => {
+        await clearMailboxes();
+        const uids = [await message('m0'), await message('m1')];
+        const first = await fetchPage(appToken, { subject: SUBJECT, limit: 1 });
+
+        const page = await fetchPage(appToken, {
+            subject: SUBJECT,
+            cursor: first.body.cursor,
+            from: 'end',
+        });
+        expect(uidsOf(page)).toEqual([uids[1]]);
+    });
+
+    it('rejects a `from` that is neither start nor end', async () => {
+        const page = await fetchPage(appToken, {
+            subject: SUBJECT,
+            from: 'middle',
+        });
+        expect(page.status).toBe(400);
+
+        const start = await fetchPage(appToken, {
+            subject: SUBJECT,
+            from: 'start',
+        });
+        expect(start.status).toBe(200);
+    });
+
+    it('starts the SDK feed without catch-up in one read', async () => {
+        await clearMailboxes();
+        for (let i = 0; i < 3; i++) await message(`before ${i}`);
+
+        const appActor = (await env.server.services.auth.authenticate(appToken))
+            .actor!;
+        const reads: Array<Record<string, unknown>> = [];
+        let receive: (delivery: { event: unknown }) => void = () => {};
+        const titles: string[] = [];
+        const feed = new NotificationFeed(
+            {
+                authToken: appToken,
+                events: {
+                    onLocal: async (
+                        _subject: string,
+                        handler: typeof receive,
+                    ) => {
+                        receive = handler;
+                        return { off: async () => {} };
+                    },
+                    fetch: async (options: Record<string, unknown>) => {
+                        reads.push(options);
+                        return env.server.services.events.fetchMissed(
+                            appActor,
+                            options,
+                        );
+                    },
+                },
+            } as never,
+            (notification: { title: string | null }) => {
+                titles.push(String(notification.title));
+            },
+            { catchUp: false },
+        );
+
+        try {
+            await feed.start();
+            expect(reads).toEqual([
+                { subject: SUBJECT, limit: 200, from: 'end' },
+            ]);
+
+            await message('after start');
+            receive({ event: { op: 'gap', reason: 'reconnect' } });
+            await vi.waitFor(() => expect(reads).toHaveLength(2));
+            await new Promise((resolve) => setTimeout(resolve, 0));
+        } finally {
+            await feed.off();
+        }
+
+        expect(reads[1]).toEqual({
+            subject: SUBJECT,
+            limit: 200,
+            cursor: expect.any(String),
+        });
+        expect(titles).toEqual(['after start']);
+    });
+});
+
 describe('cross-user isolation', () => {
     it('returns nothing of another account, whatever the subject names', async () => {
         await clearMailboxes();