docs: refresh KV sharing, Events and Notifications docs; fix router CORS and KV size error (#4445)

* docs: refresh KV sharing, Events and Notifications docs and recipes

Bring the KV, Events and Notifications reference pages and the recipes that
use them in line with current behavior, and tighten them.

- KV: share levels, re-share and recipient rules, handle scoping, list
  limits, the 399 KB value limit, and full error tables per method.
- Events: kv:<handle> subjects, what each way of losing access does to a
  subscription, fetch() notification types, handler ownership, and accurate
  anchor-deletion and deleted-app behavior.
- Notifications: where a push goes, desktop and website behavior, sensitive
  taps, share-notify limits, and enable()/status() errors.
- Recipes: fix broken code paths (undefined helpers, single-page share
  listings, read-modify-write races, oversized batch writes, missing value
  fallbacks), use events.update(), onlyIfAbsent and batch share recipients
  where they fit, and cut repetition.
- New recipes: Add a Notification Settings Switch, Clean Up Background Work.
- Rename push-when-closed to reach-a-user-when-your-app-is-closed, drop
  playground examples that need an app the reader owns, and redirect both.

* fix(workers): send CORS on router 404s and readable 500 bodies

Unmatched paths and methods now carry Access-Control-Allow-Origin like
every other router response, so a browser sees the 404 instead of a CORS
failure. A handler response with immutable headers is copied rather than
turned into a 500, and a thrown puter.js error object is sent as JSON.

* fix(kv): one error code for oversized values, and SDK types that match the store

The store now rejects a value over 399 KB with value_too_large, as the
SDK's own check and a growing path write already did. get() declares its
batch form, and the JSDoc gives the 399 KB limit and says watch shares
can list keys.

* docs(notifications): notifications sent within 250 ms reach live listeners as one

* test(events): give the per-handle subscription cap test room on a loaded runner

It fills the whole cap of 1,000 session subscriptions one add at a time,
which went past vitest's 5 s default on a busy CI shard.

.github/workflows/ai-provider-integration-tests.yaml

@@ -47,3 +47,13 @@ jobs:
                   PUTER_TEST_AI_MOONSHOT_API_KEY: ${{ secrets.PUTER_TEST_AI_MOONSHOT_API_KEY }}
                   PUTER_TEST_AI_ZAI_API_KEY: ${{ secrets.PUTER_TEST_AI_ZAI_API_KEY }}
                   PUTER_TEST_AI_ELEVENLABS_API_KEY: ${{ secrets.PUTER_TEST_AI_ELEVENLABS_API_KEY }}
+
+            # Realtime conversations through the SDK against live OpenAI. Builds
+            # the SDK bundle these tests load itself, so it runs even when the
+            # step above fails; the tests skip themselves without the key.
+            - name: Run live realtime conversation tests
+              if: ${{ !cancelled() }}
+              run: npm run setupExtensions && (cd src/puter-js && npm run build) && npx vitest run --config src/puter-js/tests/api/vitest.config.ts src/puter-js/tests/api/realtime/convoLive.test.ts
+              env:
+                  CI: 'true'
+                  PUTER_TEST_AI_OPENAI_API_KEY: ${{ secrets.PUTER_TEST_AI_OPENAI_API_KEY }}

.github/workflows/puterjs-tests.yaml

@@ -118,9 +118,13 @@ jobs:
       fail-fast: false
       matrix:
         include:
+          # The base branch lives in this repo; for a fork PR, the head
+          # repo's copy of it can be arbitrarily stale.
           - ref: ${{ github.base_ref }}
+            repository: ${{ github.repository }}
             artifact: base
           - ref: ${{ github.head_ref }}
+            repository: ${{ github.event.pull_request.head.repo.full_name }}
             artifact: pr
 
     steps:
@@ -129,7 +133,7 @@ jobs:
         uses: actions/checkout@v7
         with:
           ref: ${{ matrix.ref }}
-          repository: ${{ github.event.pull_request.head.repo.full_name }}
+          repository: ${{ matrix.repository }}
 
       - name: Set up Node.js
         if: needs.changes.outputs.puterjs == 'true'

AGENTS.md

@@ -201,6 +201,6 @@ Recipes are tested, copy-pasteable patterns for a task, one layer above the per-
 
 - **Reuse existing UI primitives before writing new ones.** Windows and dialogs are `UIWindow*` functions in [src/gui/src/UI/](src/gui/src/UI/); generic pieces already exist (`UIAlert`, `UIPrompt`, `UIContextMenu`, `UINotification`, `UIPopover`, widgets in [UI/Components/](src/gui/src/UI/Components/)). A new window should read like its neighbors: an async function taking an options object, composing an HTML string, wiring behavior with jQuery, delegating to `UIWindow(...)`.
 - **Match the visual language.** Use existing CSS classes (`button`, `button-primary`, window chrome, form styles) and copy the layout patterns of neighboring windows; new styles go in [src/gui/src/css/](src/gui/src/css/) following existing conventions. Verify anything positional (menus, overlays, z-index) on both desktop and mobile viewports.
-- **i18n every user-facing string.** No hardcoded UI text — use `i18n('key')` and add the key to [src/gui/src/i18n/translations/en.js](src/gui/src/i18n/translations/en.js). Run `npm run check-translations` before opening the PR.
+- **i18n every user-facing string.** No hardcoded UI text — use `i18n('key')` and add the key to [src/gui/src/i18n/translations/en.js](src/gui/src/i18n/translations/en.js).
 - **Shared logic goes in helpers/services.** Reusable non-UI logic belongs in [src/gui/src/helpers/](src/gui/src/helpers/) or [src/gui/src/services/](src/gui/src/services/), not copy-pasted between windows.
 - **Tests.** Vitest is wired for the GUI (`src/**/*.test.js`; see [appOrder.test.js](src/gui/src/UI/Dashboard/appOrder.test.js) for the shape). Extract pure logic into functions and test those. Desktop behavior driven through puter.js (`puter.ui.*`) is covered by the Playwright harness in [src/puter-js/tests/e2e/](src/puter-js/tests/e2e/) — add a spec there when you change how the desktop renders SDK-driven UI.

Dockerfile

@@ -73,6 +73,12 @@ COPY --from=build --chown=node:node /opt/puter .
 RUN mkdir -p /etc/puter /var/puter && \
     chown -R node:node /etc/puter /var/puter
 
+# Fix outdated HOME_URL in /etc/os-release (see issue #4329)
+# The base image may contain a reference to the old phoenix repository.
+RUN if [ -f /etc/os-release ]; then \
+      sed -i 's|HOME_URL="https://github.com/HeyPuter/phoenix"|HOME_URL="https://github.com/HeyPuter/puter"|' /etc/os-release; \
+    fi
+
 # Self-hosters mount their override at this exact path. The v2 loader
 # deep-merges it over config.default.json (see backend/index.ts).
 ENV PUTER_CONFIG_PATH=/etc/puter/config.json
@@ -87,4 +93,4 @@ USER node
 HEALTHCHECK --interval=30s --timeout=3s --start-period=30s --retries=3 \
     CMD wget --no-verbose --tries=1 --spider http://puter.localhost:4100/test || exit 1
 
-CMD ["node", "-r", "./dist/src/backend/telemetry.js", "./dist/src/backend/index.js"]
+CMD ["node", "-r", "./dist/src/backend/telemetry.js", "./dist/src/backend/index.js"]

config.template.jsonc

@@ -350,6 +350,9 @@
     // not, a row past this is swept. Off by default; any value above 0 arms
     // the sweep.
     // "notificationRetentionDays": 14,
+    //
+    // Ms a live notification waits for open tabs to acknowledge it.
+    // "notificationAckTimeoutMs": 5000,
 
     // ── Alarms / alerting ───────────────────────────────────────────────
     // Where system alarms go. Severity is the routing decision — each

doc/contributing-apis.md

@@ -47,7 +47,7 @@ Both are supported ways to define an API. **Prefer a controller when you need fi
 
 Provider sign-in requires the account's authenticator or a recovery code when 2FA is enabled, including signup callbacks that resolve an existing account. The five-minute challenge uses the same single-use `/login/otp` and `/login/recovery-code` verification as password sign-in. The GUI carries it in a URL fragment and removes it before initialization. A session and successful popup-return proof are issued only after verification; cancelling retains the popup's signed retry context without marking it authenticated.
 
-Disabling 2FA through `/user-protected/disable-2fa` requires both password or OIDC revalidation and the current six-digit authenticator `code`. Missing, malformed, or incorrect codes leave the secret and recovery codes intact. A team's requirement for 2FA still prevents disabling it.
+Disabling 2FA through `/user-protected/disable-2fa` requires both password or OIDC revalidation and either the current six-digit authenticator `code` or an unused recovery code in `code`. Recovery codes are consumed atomically. Missing or incorrect codes leave the secret and remaining recovery codes intact. A team's requirement for 2FA still prevents disabling it.
 
 Email changes through `/user-protected/change-email` require the password or OIDC revalidation cookie, plus a six-digit `code` from the authenticator when 2FA is enabled. Missing or malformed codes return `400 bad_request`; incorrect codes return `401 code_mismatch`. Both include `factor: 'otp'`. Confirmation links are bound to that verified request. A 2FA-enabled account must request a new link if its existing link was issued without second-factor verification.
 

doc/pagination.md

@@ -59,6 +59,10 @@ store:
   row — and the query seeks past it (`WHERE (col, id) > (?, ?) ORDER BY col,
   id`). Any SQL list gaining a cursor must have a deterministic `ORDER BY`
   ending in a unique tiebreaker (`id`).
+- The notification catch-up (`GET /events/fetch`) holds two keysets in one
+  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.
 
 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

@@ -0,0 +1,79 @@
+# 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)`.
+
+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`.
+
+## Push payload
+
+`sw.js` reads the push's JSON body. The message is its `puter` field, or `data.puter` for services that only carry string data, as an object or a JSON string:
+
+```ts
+{ uid?: string; title?: string; body?: string; icon?: string; group?: string;
+  target?: { app?: string; path?: string }; data?: unknown; channel?: string;
+  type?: 'challenge'; challenge?: string }
+```
+
+`uid` is the notification's uid, a later push with the same `group` replaces the one showing, and `target` and `data` reach the app when the user taps it.
+
+When the browser replaces the subscription (`pushsubscriptionchange`), `sw.js` posts `{ type: 'puter-push-subscription-changed' }` to every open window on Puter's origin. The worker has no token or session, so the page's push client registers the new subscription.
+
+## Receipts
+
+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 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.
+
+## Registering
+
+The registry is in [src/gui/src/helpers/pushClient.js](../src/gui/src/helpers/pushClient.js). A service script registers its client like this:
+
+```js
+service_script(async (api) => {
+    api.use()['push.registerPushClient']?.(client);
+});
+```
+
+`use(id)` throws when nothing is registered under `id`, so the form above also runs on a Puter version without the registry and does nothing there. Any script that runs after the GUI bundle can call `use()['push.registerPushClient']?.(client)` the same way. Registering again replaces the client. Registering dispatches `push-client-registered` on `window`, and an open Notifications tab redraws.
+
+With no client registered, the tab says push notifications aren't available in this browser.
+
+### Built-in Web Push client
+
+When the server also sets the `pushWebPushKey` gui param (a VAPID public key), core registers its own client ([webPushClient.js](../src/gui/src/helpers/webPushClient.js)) unless an extension registered one first. It uses `puter.notifications.enable()` / `disable()`, the same standard Web Push flow apps use on their own origins:
+
+1. `GET /push/web/key` for the key, then `pushManager.subscribe()` on the `/sw.js` registration.
+2. `POST /push/web/subscriptions { subscription }`. A subscription the server already has answers `{ status: 'active' }`. A new one answers `{ status: 'pending' }`, and the server sends it a push with `{ type: 'challenge', challenge }`.
+3. The worker shows that push and posts `{ type: 'puter-push-challenge', challenge }` to the origin's windows; the page sends it to `POST /push/web/subscriptions/verify`. The device is registered once the page hands the confirmation back.
+4. `DELETE /push/web/subscriptions { endpoint }` removes it.
+
+Apps on their own origin do the same through `push-sw.js`, which they import into their own worker. A subscription made with an app token is the app's: its pushes are that app's notifications only.
+
+## Interface
+
+```ts
+interface PushClient {
+    enable(): Promise<{ deviceUid: string }>;
+    disable(): Promise<void>;
+    status(): Promise<{
+        permission: 'default' | 'granted' | 'denied';
+        registered: boolean;
+        deviceUid?: string;
+    }>;
+}
+```
+
+- `enable()` may ask for notification permission, so core calls it from a click: Turn on in the Notifications tab, Allow on a permission prompt that includes `notifications:push` while this browser is off, and the "Turn on notifications" button of the `/action/enable-push` popup and the matching desktop dialog (`UIEnablePushDialog`). Core also calls it without a click, from `helpers/pushSync.js`, when `Notification.permission` is already `granted`, `status()` reports the browser as not registered, the user has not turned push off in this browser, and an app holds `notifications:push`; the browser does not prompt then. The built-in client runs `puter.notifications.enable()`, which subscribes with the `/sw.js` registration and registers the browser through the Web Push flow above (`platform: 'webpush'`). It then resolves the `uid` of this browser's `webpush` device from `listDevices()`. It rejects when permission is refused or the browser wasn't registered.
+- `disable()` runs `puter.notifications.disable()`, which sends `DELETE /push/web/subscriptions { endpoint }` and ends the browser's subscription. The tab calls it for Turn off, and for Remove on the device marked as this browser. Remove on any other device is `DELETE /push/devices/:uid`.
+- `status()` reports the state without prompting. `permission` is `Notification.permission`. `registered` is true when this browser has a device registered for the signed-in user, and `deviceUid` is that device's `uid`.
+
+After `enable()` resolves, the tab calls `POST /push/devices/:uid/test` and asks the user whether a notification showed up.
+
+The tab also reads `GET /push/apps` and `GET`/`POST /push/preferences`.
+
+Core keeps its own record of a browser the user turned off, `puter.push.browser-off:<user uuid>` in `localStorage`, written by Turn off and by Remove on this browser's device, and cleared when `enable()` resolves. The silent registration above skips a browser with that record, so a device removed here stays removed while one removed from another device, or a new sign-in in a browser that already allows notifications, registers again.

doc/self-hosting.md

@@ -12,7 +12,17 @@ Generates secrets, writes `.env` + `puter/config/config.json`, downloads `docker
 
 ## Requirements
 
-- **Docker** with the `compose` plugin.
+- **Docker** with the `compose` plugin. This is the one thing you have to install
+  yourself — the installer checks for it and stops with an explanation rather
+  than installing it for you.
+  - **macOS / Windows:** [Docker Desktop](https://docs.docker.com/get-docker/).
+    Both ship the `compose` plugin.
+  - **Linux:** [Docker Engine](https://docs.docker.com/engine/install/) plus the
+    [`docker-compose-plugin`](https://docs.docker.com/compose/install/) package.
+  - Confirm before running anything else: `docker compose version` should print a
+    version, not `command not found`.
+  - If Docker is installed but the shell can't see it, make sure your user is in
+    the `docker` group (Linux) or that Docker Desktop is actually running.
 - A **domain** with DNS access — you need a wildcard record (`*.your-domain.com` → server IP). Puter routes by subdomain (`api.<domain>`, `site.<domain>`, `app.<domain>`).
 - Optional: **TLS certs** (or `certbot` to grab them — see Step 3).
 
@@ -657,6 +667,14 @@ Migrations re-apply idempotently across pulls. Volumes are preserved.
 
 ## Troubleshooting
 
+**`missing required command: docker` — the installer stops immediately.**
+Docker isn't on your `PATH` yet. Puter self-hosting is a Docker Compose stack, so
+nothing can run without it. Install [Docker Desktop](https://docs.docker.com/get-docker/)
+on macOS/Windows or [Docker Engine](https://docs.docker.com/engine/install/) plus
+`docker-compose-plugin` on Linux, then confirm `docker compose version` works in
+the same shell and re-run the installer. On Linux, a fresh Docker install usually
+needs a new login session before your user picks up the `docker` group.
+
 **Site loads but I get a 502 / "Bad Gateway" from Caddy.**
 The puter container failed to come up. `docker compose logs puter` will tell you which dependency rejected it (most often DB password mismatch between `.env` and `config.json`).
 

extensions/thumbnails.test.ts

@@ -314,6 +314,41 @@ describe('thumbnails extension — handleThumbnailRead', () => {
         await server?.shutdown();
     });
 
+    it('keeps read URLs stable within an hour and rotates them at the next hour', async () => {
+        const key = mintedKey();
+        const signedAt = Date.UTC(2026, 9, 26, 10);
+        const read = async () => {
+            const entry: Record<string, unknown> = {
+                thumbnail: `s3://${BUCKET}/${key}`,
+            };
+            await handleThumbnailRead(entry, {
+                s3,
+                s3Presign,
+                bucketName: BUCKET,
+                bucketEndpoint: BUCKET_ENDPOINT,
+                fsEntry: server.stores.fsEntry,
+            });
+            return entry.thumbnail as string;
+        };
+        vi.useFakeTimers({ toFake: ['Date'] });
+        try {
+            vi.setSystemTime(signedAt + 1000);
+            const first = await read();
+            vi.setSystemTime(signedAt + 3599_000);
+            expect(await read()).toBe(first);
+            expect(new URL(first).searchParams.get('X-Amz-Date')).toBe(
+                '20261026T100000Z',
+            );
+            expect(new URL(first).searchParams.get('X-Amz-Expires')).toBe(
+                '604800',
+            );
+            vi.setSystemTime(signedAt + 3600_000);
+            expect(await read()).not.toBe(first);
+        } finally {
+            vi.useRealTimers();
+        }
+    });
+
     // Thumbnails stored before keys were bound to entries keep displaying.
     it.each([
         ['an entry-bound key', () => mintedKey()],

extensions/thumbnails.ts

@@ -307,6 +307,9 @@ export const handleThumbnailRead = async (
     const thumb = entry.thumbnail;
     if (typeof thumb !== 'string' || !thumb) return;
     const presignClient = deps.s3Presign;
+    const signingDate = new Date(
+        Math.floor(Date.now() / 3_600_000) * 3_600_000,
+    );
 
     if (isStoragePointer(thumb, deps.bucketEndpoint)) {
         const key = resolveThumbnailKey(thumb);
@@ -319,7 +322,7 @@ export const handleThumbnailRead = async (
         entry.thumbnail = await getSignedUrl(
             presignClient,
             new GetObjectCommand({ Bucket: deps.bucketName, Key: key }),
-            { expiresIn: 604800 },
+            { expiresIn: 604800, signingDate },
         );
     } else if (thumb.startsWith('data')) {
         // Move an inline thumbnail into storage. The row only takes the new
@@ -373,7 +376,7 @@ export const handleThumbnailRead = async (
         entry.thumbnail = await getSignedUrl(
             presignClient,
             new GetObjectCommand({ Bucket: deps.bucketName, Key: key }),
-            { expiresIn: 604800 },
+            { expiresIn: 604800, signingDate },
         );
     }
 };

install.sh

@@ -53,9 +53,29 @@ need() {
     command -v "$1" >/dev/null 2>&1 || die "missing required command: $1"
 }
 
+check_docker() {
+    if command -v docker >/dev/null 2>&1; then
+        return 0
+    fi
+    echo >&2 ""
+    echo >&2 "[puter-install] missing required command: docker"
+    echo >&2 ""
+    echo >&2 "Docker is required to run Puter self-hosted."
+    echo >&2 ""
+    echo >&2 "Installation instructions:"
+    echo >&2 "  - macOS (Apple Silicon & Intel): https://docs.docker.com/desktop/setup/install/mac-install/"
+    echo >&2 "    (Docker Desktop is recommended. Alternatives: OrbStack, Colima)"
+    echo >&2 "  - Linux: https://docs.docker.com/engine/install/"
+    echo >&2 "  - Windows: https://docs.docker.com/desktop/setup/install/windows-install/"
+    echo >&2 ""
+    echo >&2 "After installing Docker, make sure it's running and try again."
+    echo >&2 ""
+    exit 1
+}
+
 # ── Step 1: dependency check ────────────────────────────────────────
 log "checking dependencies"
-need docker
+check_docker
 need curl
 need openssl
 docker compose version >/dev/null 2>&1 \

package.json

@@ -54,7 +54,6 @@
     "dev": "npm start",
     "build": "npm run setupExtensions && npm run build:ts && cd src/gui && node ./build.js && cd ../puter-js && npm run build",
     "build:workerLib": "cd src/puter-js && npm run build && cd ../worker && npm run build",
-    "check-translations": "node tools/check-translations.js",
     "prepare": "husky",
     "build:ts": "tsc -p tsconfig.build.json && node ./tools/write-dist-package-json.mjs",
     "check:puterjs:types": "node tools/checkPuterjsTypes.mjs",
@@ -79,7 +78,8 @@
     "javascript-time-ago": "^2.5.11",
     "libphonenumber-js": "1.13.15",
     "miniflare": "^4.20260617.1",
-    "open": "^10.1.0"
+    "open": "^10.1.0",
+    "sharp": "^0.35.5"
   },
   "engines": {
     "node": ">=24.0.0"

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

@@ -108,6 +108,25 @@ describe('AbstractDatabaseClient — unimplemented surface', () => {
 });
 
 describe('AbstractDatabaseClient — replica-aware reads', () => {
+    it('avoids a primary read when the replica has rows in sequential mode', async () => {
+        const client = new FixtureDatabaseClient([{ id: 1 }], [{ id: 2 }]);
+        expect(
+            await client.tryHardRead('SELECT 1', [], { race: false }),
+        ).toEqual([{ id: 1 }]);
+        expect(client.preads).toEqual([]);
+    });
+
+    it.each([[], new Error('replica unavailable')])(
+        'falls back once in sequential mode',
+        async (replica) => {
+            const client = new FixtureDatabaseClient(replica, [{ id: 2 }]);
+            expect(
+                await client.tryHardRead('SELECT 1', [], { race: false }),
+            ).toEqual([{ id: 2 }]);
+            expect(client.preads).toEqual(['SELECT 1']);
+        },
+    );
+
     it('returns replica rows without waiting on the primary', async () => {
         const client = new FixtureDatabaseClient([{ id: 1 }], [{ id: 2 }]);
         await expect(client.tryHardRead('SELECT 1')).resolves.toEqual([
@@ -256,6 +275,16 @@ describe('AbstractDatabaseClient — SQL generation', () => {
         expect(postgres().timestampFromUnixSql()).toBe('to_timestamp(?)');
     });
 
+    it('reads a timestamp column back as unix seconds in each engine', () => {
+        expect(sqlite().unixSecondsSql('`t`')).toBe(
+            "CAST(strftime('%s', `t`) AS INTEGER)",
+        );
+        expect(mysql().unixSecondsSql('`t`')).toBe('UNIX_TIMESTAMP(`t`)');
+        expect(postgres().unixSecondsSql('`t`')).toBe(
+            'EXTRACT(EPOCH FROM `t`)::bigint',
+        );
+    });
+
     it('describes a stored timestamp the way each driver reads it back', () => {
         const seconds = Date.UTC(2026, 9, 11, 8, 5, 9) / 1000;
         expect(sqlite().timestampValue(seconds)).toBe('2026-10-11 08:05:09');

src/backend/clients/database/DatabaseClient.ts

@@ -138,25 +138,27 @@ export class AbstractDatabaseClient extends PuterClient {
 
     /**
      * Like `read()`, but an empty or failed replica read falls back to the
-     * primary, so replication lag can't hide a row that was just written. The
-     * primary read starts alongside the replica one rather than after it.
-     * Without a replica this is a single `read()`.
+     * primary, so replication lag can't hide a row that was just written. By
+     * default the primary read starts alongside the replica one; `race: false`
+     * reads the primary only after the replica returns empty or fails. Without
+     * a replica this is a single `read()`.
      */
     @Span('db.tryHardRead', (query: string) => ({ 'db.statement': query }))
     async tryHardRead(
         query: string,
         params: unknown[] = [],
+        { race = true }: { race?: boolean } = {},
     ): Promise<Record<string, unknown>[]> {
         if (!this.hasReadReplica()) return this.read(query, params);
 
-        const primary = settle(this.pread(query, params));
+        const primary = race ? settle(this.pread(query, params)) : null;
         try {
             const rows = await this.replicaRead(query, params);
             if (rows.length > 0) return rows;
         } catch {
             // replica failed — fall through to primary
         }
-        const result = await primary;
+        const result = await (primary ?? settle(this.pread(query, params)));
         if ('error' in result) throw result.error;
         return result.value;
     }
@@ -386,6 +388,19 @@ export class AbstractDatabaseClient extends PuterClient {
         });
     }
 
+    /**
+     * A timestamp column as unix seconds, computed by the database: the mysql
+     * driver reads a stored UTC timestamp as local time, so parsing it in JS
+     * can be off by the server's UTC offset.
+     */
+    unixSecondsSql(column: string): string {
+        return this.case({
+            postgres: `EXTRACT(EPOCH FROM ${column})::bigint`,
+            mysql: `UNIX_TIMESTAMP(${column})`,
+            otherwise: `CAST(strftime('%s', ${column}) AS INTEGER)`,
+        });
+    }
+
     /**
      * What a read of a timestamp column holding `seconds` returns: sqlite gives
      * back the UTC text it stored, mysql2 and pg a `Date` read in node's time

src/backend/clients/database/MySQLDatabaseClient.ts

@@ -217,7 +217,8 @@ export class MySQLDatabaseClient extends AbstractDatabaseClient {
         return this.configuration === Configuration.REPLICA;
     }
 
-    // No failover: `tryHardRead` already has a primary read in flight.
+    // No failover: `tryHardRead` falls back to the primary on an empty result
+    // or error (raced alongside by default, after the replica with `race: false`).
     protected override async replicaRead(
         query: string,
         params: unknown[],

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 = 92;
+const CURRENT_SCHEMA_VERSION = 95;
 
 /**
  * These suites migrate real files on disk. Idle they finish in well under a
@@ -673,6 +673,38 @@ describe('SqliteDatabaseClient — boot and migrations', { timeout: DISK_MIGRATI
         });
     });
 
+    it('adds kv_share_handles.notify from 0099, off for every existing share', async () => {
+        const dir = mkdtempSync(join(tmpdir(), 'puter-sqlite-notify-'));
+        const path = join(dir, 'puter.sqlite');
+        try {
+            const before = new SqliteDatabaseClient(
+                sqliteConfig({ inMemory: false, path, targetVersion: 94 }),
+            );
+            await before.onServerStart();
+            await before.write(
+                'INSERT INTO `kv_share_handles` (`handle`, `owner_user_id`, ' +
+                    '`grantee_user_id`, `app_uid`, `key_prefix`, `permission`, ' +
+                    '`created_at`) VALUES (?, 1, 1, ?, ?, ?, 0)',
+                ['kvh-before-notify', 'os-global', 'a:', 'kv-share:x'],
+            );
+            before.onServerShutdown();
+
+            const after = new SqliteDatabaseClient(
+                sqliteConfig({ inMemory: false, path }),
+            );
+            await after.onServerStart();
+            await expect(
+                after.read(
+                    'SELECT `notify` FROM `kv_share_handles` WHERE `handle` = ?',
+                    ['kvh-before-notify'],
+                ),
+            ).resolves.toEqual([{ notify: 0 }]);
+            after.onServerShutdown();
+        } finally {
+            rmSync(dir, { recursive: true, force: true });
+        }
+    });
+
     it('indexes notification.created_at for the retention sweep', async () => {
         const rows = await client.read('PRAGMA index_list(`notification`)');
         expect(rows.map((r) => String(r.name))).toContain(
@@ -680,6 +712,18 @@ describe('SqliteDatabaseClient — boot and migrations', { timeout: DISK_MIGRATI
         );
     });
 
+    it('indexes notification.replaced_at per mailbox slice for catch-up', async () => {
+        const columns = await client.read(
+            'PRAGMA index_info(`idx_notification_replaced`)',
+        );
+        expect(columns.map((c) => String(c.name))).toEqual([
+            'user_id',
+            'audience',
+            'app_uid',
+            'replaced_at',
+        ]);
+    });
+
     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

@@ -131,6 +131,9 @@ const AVAILABLE_MIGRATIONS: [number, string[]][] = [
     [89, ['0094_deleted-apps.sql']],
     [90, ['0095_kv-share-handle-levels.sql']],
     [91, ['0096_kv-share-handle-quota-indexes.sql']],
+    [92, ['0097_user-to-user-holder-permission-index.sql']],
+    [93, ['0098_notification-groups.sql']],
+    [94, ['0099_kv-share-handle-notify.sql']],
 ];
 
 export class SqliteDatabaseClient extends AbstractDatabaseClient {

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

@@ -0,0 +1,38 @@
+-- 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/>.
+
+-- Lets a holder's grant check read only the permissions it names. Guarded, so
+-- a replay does nothing.
+
+DROP PROCEDURE IF EXISTS _puter_add_u2u_holder_permission_index;
+DELIMITER //
+CREATE PROCEDURE _puter_add_u2u_holder_permission_index()
+BEGIN
+  IF NOT EXISTS (
+    SELECT 1 FROM INFORMATION_SCHEMA.STATISTICS
+    WHERE TABLE_SCHEMA = DATABASE()
+      AND TABLE_NAME = 'user_to_user_permissions'
+      AND INDEX_NAME = 'idx_user_to_user_permissions_holder_permission'
+  ) THEN
+    ALTER TABLE `user_to_user_permissions` ADD INDEX `idx_user_to_user_permissions_holder_permission` (`holder_user_id`, `permission`);
+  END IF;
+END//
+DELIMITER ;
+
+CALL _puter_add_u2u_holder_permission_index();
+
+DROP PROCEDURE IF EXISTS _puter_add_u2u_holder_permission_index;

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

@@ -0,0 +1,53 @@
+-- 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`.`group_key` and `replaced_at`. See
+-- sqlite/0098_notification-groups.sql for the rationale. The key is a hex
+-- digest, so ascii and compared byte for byte. No per-file applied-state
+-- tracking, so every step is guarded and a replay does nothing.
+
+CALL _puter_add_col('notification', 'group_key', '`group_key` char(64) CHARACTER SET ascii COLLATE ascii_bin DEFAULT NULL');
+CALL _puter_add_col('notification', 'replaced_at', '`replaced_at` bigint DEFAULT NULL');
+
+DROP PROCEDURE IF EXISTS _puter_add_notification_group_indexes;
+DELIMITER //
+CREATE PROCEDURE _puter_add_notification_group_indexes()
+BEGIN
+  IF NOT EXISTS (
+    SELECT 1 FROM INFORMATION_SCHEMA.STATISTICS
+    WHERE TABLE_SCHEMA = DATABASE()
+      AND TABLE_NAME = 'notification'
+      AND INDEX_NAME = 'idx_notification_group'
+  ) THEN
+    ALTER TABLE `notification` ADD INDEX `idx_notification_group`
+      (`user_id`, `app_uid`, `group_key`);
+  END IF;
+  IF NOT EXISTS (
+    SELECT 1 FROM INFORMATION_SCHEMA.STATISTICS
+    WHERE TABLE_SCHEMA = DATABASE()
+      AND TABLE_NAME = 'notification'
+      AND INDEX_NAME = 'idx_notification_replaced'
+  ) THEN
+    ALTER TABLE `notification` ADD INDEX `idx_notification_replaced`
+      (`user_id`, `audience`, `app_uid`, `replaced_at`);
+  END IF;
+END//
+DELIMITER ;
+
+CALL _puter_add_notification_group_indexes();
+
+DROP PROCEDURE IF EXISTS _puter_add_notification_group_indexes;

src/backend/clients/database/migrations/mysql/mysql_mig_53.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/>.
+
+-- Notifications through a share handle. See
+-- sqlite/0099_kv-share-handle-notify.sql for the column. No per-file
+-- applied-state tracking, so it goes through _puter_add_col and a replay does
+-- nothing.
+
+CALL _puter_add_col('kv_share_handles', 'notify', '`notify` tinyint(1) NOT NULL DEFAULT 0');

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

@@ -0,0 +1,21 @@
+-- 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/>.
+
+-- Lets a holder's grant check read only the permissions it names.
+
+CREATE INDEX IF NOT EXISTS idx_user_to_user_permissions_holder_permission
+    ON user_to_user_permissions (holder_user_id, permission);

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

@@ -0,0 +1,29 @@
+-- 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.group_key and replaced_at. See
+-- sqlite/0098_notification-groups.sql for the rationale. Idempotent via IF NOT
+-- EXISTS.
+
+ALTER TABLE notification ADD COLUMN IF NOT EXISTS group_key varchar(64) DEFAULT NULL;
+ALTER TABLE notification ADD COLUMN IF NOT EXISTS replaced_at bigint DEFAULT NULL;
+
+CREATE INDEX IF NOT EXISTS idx_notification_group
+    ON notification (user_id, app_uid, group_key);
+
+CREATE INDEX IF NOT EXISTS idx_notification_replaced
+    ON notification (user_id, audience, app_uid, replaced_at);

src/backend/clients/database/migrations/postgres/postgres_mig_42.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/>.
+
+-- Notifications through a share handle. See
+-- sqlite/0099_kv-share-handle-notify.sql for the column. Idempotent via
+-- IF NOT EXISTS; there is no per-file applied-state tracking.
+
+ALTER TABLE kv_share_handles ADD COLUMN IF NOT EXISTS notify smallint NOT NULL DEFAULT 0;

src/backend/clients/database/migrations/sqlite/0097_user-to-user-holder-permission-index.sql

@@ -0,0 +1,21 @@
+-- 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/>.
+
+-- Lets a holder's grant check read only the permissions it names.
+
+CREATE INDEX IF NOT EXISTS `idx_user_to_user_permissions_holder_permission`
+    ON `user_to_user_permissions` (`holder_user_id`, `permission`);

src/backend/clients/database/migrations/sqlite/0098_notification-groups.sql

@@ -0,0 +1,38 @@
+-- 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/>.
+
+-- What app message groups need from `notification`:
+--
+--   - `group_key`   : a sha256 hex digest of an app message's `group`, so the
+--                     notification a newer one replaces is found by index.
+--                     Null on every other row, and on rows written before
+--                     this, which therefore never match.
+--   - `replaced_at` : epoch milliseconds of the last replacement, null for a
+--                     row never replaced. Live and fetched copies carry it as
+--                     their version, so a client can tell a replacement from a
+--                     copy it already has. Indexed per mailbox slice, so a
+--                     catch-up reads the rows replaced since its cursor
+--                     without scanning the ones that never were.
+
+ALTER TABLE `notification` ADD COLUMN `group_key` TEXT DEFAULT NULL;
+ALTER TABLE `notification` ADD COLUMN `replaced_at` INTEGER DEFAULT NULL;
+
+CREATE INDEX IF NOT EXISTS `idx_notification_group`
+    ON `notification` (`user_id`, `app_uid`, `group_key`);
+
+CREATE INDEX IF NOT EXISTS `idx_notification_replaced`
+    ON `notification` (`user_id`, `audience`, `app_uid`, `replaced_at`);

src/backend/clients/database/migrations/sqlite/0099_kv-share-handle-notify.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/>.
+
+-- Whether the two parties of a share may send each other notifications through
+-- its handle. Off by default, so every existing share reads as not allowing
+-- them.
+
+ALTER TABLE `kv_share_handles`
+    ADD COLUMN `notify` INTEGER NOT NULL DEFAULT 0;

src/backend/clients/event/types.ts

@@ -75,6 +75,15 @@ export type EventMap = {
     serverStart: Record<string, never>;
     serverPrepareShutdown: Record<string, never>;
     serverShutdown: Record<string, never>;
+    /**
+     * Emitted by a host extension that knows this server will restart soon.
+     * Long-lived connections ask their clients to reconnect; nothing is refused
+     * or closed, so a false alarm is harmless.
+     */
+    serverRestartAnnounced: {
+        /** How long until the server stops, when known. */
+        closeInMs?: number;
+    };
 
     // ---- AI ----
     'ai.prompt.validate': {
@@ -208,7 +217,7 @@ export type EventMap = {
          */
         is_temp?: boolean;
         ip?: string | null;
-        source?: 'oidc';
+        source?: 'oidc' | 'team_provision';
         req?: unknown;
         data?: unknown;
         abuse?: unknown;
@@ -268,7 +277,7 @@ export type EventMap = {
         ip?: string | null;
         fingerprint?: string | null;
         reputation?: number | null;
-        source?: 'oidc';
+        source?: 'oidc' | 'team_provision';
         requires_phone_verification: boolean;
         requires_card_verification: boolean;
         accepted: boolean;
@@ -549,9 +558,28 @@ export type EventMap = {
         appUid: string | null;
         value: Record<string, unknown>;
         createdAt: number;
+        /** An earlier notification replaced in place; `createdAt` is when. */
+        replaced?: true;
         /** Events handler runs behind whatever created it. */
         handlerDepth?: number;
     };
+    /**
+     * Every non-silent write or update, only on the node that wrote it. The
+     * value is the listener's own copy of what the socket carries.
+     */
+    'notif.written': {
+        userId: number;
+        uid: string;
+        type: string;
+        audience: string;
+        /** The row's app; null when it names none or an update could not tell. */
+        appUid: string | null;
+        value: Record<string, unknown>;
+        /** An earlier notification rewritten in place. */
+        updated?: true;
+        /** Names this one send, for a receipt asked about it. */
+        sendId: string;
+    };
     /**
      * One notification, addressed at whatever sockets each region holds for the
      * recipient. `outer.*` reaches peer regions and never sibling nodes, so
@@ -560,9 +588,31 @@ export type EventMap = {
      */
     'outer.notif.delivery': {
         userId: number;
-        wire: 'notif.message' | 'notif.unreads' | 'notif.ack';
+        wire: 'notif.message' | 'notif.unreads' | 'notif.ack' | 'notif.removed';
         response: unknown;
     };
+    /**
+     * How one live notification went, on the node that asked for its receipt:
+     * from the desktop's sockets, or with `appUid` the app's own.
+     */
+    'notif.delivery.settled': {
+        sendId?: string;
+        uid: string;
+        userId: number;
+        type: string;
+        /** The app whose own sockets were asked; absent for the desktop's. */
+        appUid?: string;
+        outcome: NotifDeliveryOutcome;
+        /** A socket in this region acknowledges the receipt. */
+        ackCapable: boolean;
+        /** No socket here is an older client that acknowledges nothing. */
+        everySocketAcks: boolean;
+        /** Every node here answered the ask, not just this one. */
+        complete: boolean;
+        /** A peer region holds a socket for the user. */
+        peerRegions: boolean;
+        responders: NotifDeliveryResponder[];
+    };
 
     // ---- Metering ----
     // Recurring charges are pure mechanism here: the metering service knows
@@ -704,6 +754,7 @@ export type EventMap = {
     'outer.gui.item.renamed': GuiEvent;
     'outer.gui.notif.ack': GuiEvent<{ uid: string }>;
     'outer.gui.notif.message': GuiEvent<{ uid: string; notification: unknown }>;
+    'outer.gui.notif.removed': GuiEvent<{ uid: string }>;
     'outer.gui.notif.unreads': GuiEvent<{
         unreads: { uid: string; notification: unknown }[];
     }>;
@@ -711,7 +762,7 @@ export type EventMap = {
     // ---- Subdomains ----
     // `uid` is the row uuid — for `delete` it is the only surviving handle a
     // listener can use to find state keyed to the row after it is gone.
-    'subdomain.delete': { subdomain: string; uid?: string };
+    'subdomain.delete': { subdomain: string; uid?: string; userId: number };
     'subdomain.update': { subdomain: string; uid?: string };
     'site.htmlServed': {
         subdomain: string;
@@ -982,6 +1033,22 @@ export type MatchingEvents<P extends ListenKey> = P extends `${infer Prefix}.*`
     ? Extract<EventKey, `${Prefix}.${string}`>
     : P & EventKey;
 
+/** Acked, not acked, no socket anywhere, or sockets only in a peer region. */
+export type NotifDeliveryOutcome =
+    'received' | 'unreceived' | 'no-socket' | 'remote-only';
+
+/** One socket's receipt for a live notification. */
+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 = {
     from_outside?: boolean;
     /** Set by `emitAndWait` when a listener threw, so a verdict hook can refuse. */

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

@@ -23,7 +23,7 @@
  */
 
 import type { fetch as undiciFetch } from 'undici';
-import { describe, expect, it } from 'vitest';
+import { describe, expect, it, vi } from 'vitest';
 import type { IConfig } from '../../types.js';
 import {
     DispatcherInvokeTransport,
@@ -33,6 +33,8 @@ import {
     EVENTS_ERROR_HEADER,
     EVENTS_HANDLED_HEADER,
     EventsWorkerInvokerClient,
+    INVOKE_CONNECTIONS,
+    outcomeForStatus,
     type WorkerInvokeRequest,
 } from './EventsWorkerInvokerClient.js';
 
@@ -54,14 +56,22 @@ const stubFetch = (
     (async () =>
         new Response(null, { status, headers })) as unknown as FetchImpl;
 
-/** A stub fetch that never answers until the abort signal fires. */
+/**
+ * A stub fetch that never answers until the abort signal fires, then rejects
+ * with the signal's reason the way undici does.
+ */
 const hangingFetch: FetchImpl = ((_url: string, init?: RequestInit) =>
     new Promise((_resolve, reject) => {
         init?.signal?.addEventListener('abort', () =>
-            reject(new Error('This operation was aborted')),
+            reject(init.signal!.reason),
         );
     })) as unknown as FetchImpl;
 
+/** A stub fetch that fails before any answer, as a refused connection does. */
+const refusedFetch: FetchImpl = (async () => {
+    throw new TypeError('fetch failed');
+}) as unknown as FetchImpl;
+
 /** A stub fetch that records the URL it was called with. */
 const capturingFetch = (
     calls: string[],
@@ -141,13 +151,39 @@ describe('DispatcherInvokeTransport', () => {
         });
     });
 
-    it('answers null with an error when the request times out', async () => {
+    it('answers null and says so when the request times out', async () => {
         const transport = new DispatcherInvokeTransport('http://dispatcher', 's', {
             fetchImpl: hangingFetch,
         });
         const result = await transport.send({ ...CALL, timeoutMs: 10 });
         expect(result.status).toBeNull();
-        expect(result.error).toMatch(/abort/i);
+        expect(result.timedOut).toBe(true);
+    });
+
+    it('answers null without a timeout when the request fails outright', async () => {
+        const transport = new DispatcherInvokeTransport('http://dispatcher', 's', {
+            fetchImpl: refusedFetch,
+        });
+        expect(await transport.send(CALL)).toEqual({
+            status: null,
+            error: 'fetch failed',
+        });
+    });
+
+    it('reads a retry-after in seconds, and ignores a date', async () => {
+        const answer = (value: string) =>
+            new DispatcherInvokeTransport('http://dispatcher', 's', {
+                fetchImpl: stubFetch(500, {
+                    [EVENTS_HANDLED_HEADER]: '1',
+                    [EVENTS_ERROR_HEADER]: 'platform-error',
+                    'retry-after': value,
+                }),
+            }).send(CALL);
+
+        expect((await answer('30')).retryAfterMs).toBe(30_000);
+        expect(
+            (await answer('Wed, 21 Oct 2015 07:28:00 GMT')).retryAfterMs,
+        ).toBeUndefined();
     });
 
     it('surfaces the runtime`s own error header alongside its status', async () => {
@@ -176,6 +212,97 @@ describe('DispatcherInvokeTransport', () => {
     });
 });
 
+describe('DispatcherInvokeTransport with every connection busy', () => {
+    /** A fetch that answers 200 to one call at a time, when told to. */
+    const heldFetch = () => {
+        const held: Array<{ answer: () => void; signal: AbortSignal }> = [];
+        const fetchImpl = ((_url: string, init: RequestInit) =>
+            new Promise((resolve, reject) => {
+                const signal = init.signal!;
+                signal.addEventListener('abort', () => reject(signal.reason));
+                held.push({
+                    signal,
+                    answer: () =>
+                        resolve(
+                            new Response(null, {
+                                status: 200,
+                                headers: { [EVENTS_HANDLED_HEADER]: '1' },
+                            }),
+                        ),
+                });
+            })) as unknown as FetchImpl;
+        return { fetchImpl, held };
+    };
+
+    /** Every connection taken by a call nobody has answered yet. */
+    const saturated = async () => {
+        const { fetchImpl, held } = heldFetch();
+        const transport = new DispatcherInvokeTransport(
+            'http://dispatcher',
+            's',
+            { fetchImpl },
+        );
+        const busy = Array.from({ length: INVOKE_CONNECTIONS }, () =>
+            transport.send(CALL),
+        );
+        await vi.waitFor(() => expect(held).toHaveLength(INVOKE_CONNECTIONS));
+        const answerAll = async () => {
+            for (const call of held) call.answer();
+            await Promise.all(busy);
+        };
+        return { transport, held, answerAll };
+    };
+
+    it('waits for a free connection, then gives the run its whole timeout', async () => {
+        const { transport, held, answerAll } = await saturated();
+
+        const waiting = transport.send({ ...CALL, timeoutMs: 400 });
+        await new Promise((resolve) => setTimeout(resolve, 150));
+        expect(held).toHaveLength(INVOKE_CONNECTIONS);
+
+        held[0].answer();
+        await vi.waitFor(() =>
+            expect(held).toHaveLength(INVOKE_CONNECTIONS + 1),
+        );
+        // Past 400 ms from when the call was made, not from when it got its
+        // connection.
+        await new Promise((resolve) => setTimeout(resolve, 300));
+        expect(held[INVOKE_CONNECTIONS].signal.aborted).toBe(false);
+
+        await answerAll();
+        await expect(waiting).resolves.toMatchObject({ status: 200 });
+    });
+
+    it('fails a call that never got a connection as Puter`s, not the handler`s', async () => {
+        const { transport, held, answerAll } = await saturated();
+
+        await expect(
+            transport.send({ ...CALL, timeoutMs: 40 }),
+        ).resolves.toEqual({
+            status: null,
+            error: 'no free connection to the events dispatcher',
+        });
+
+        const client = new EventsWorkerInvokerClient({
+            events: { invokeTimeoutMs: 40 },
+        } as unknown as IConfig);
+        client.setTransport(transport);
+        await expect(client.invoke(REQUEST)).resolves.toMatchObject({
+            outcome: 'unavailable',
+        });
+        expect(held).toHaveLength(INVOKE_CONNECTIONS);
+
+        // The slots come back once the calls holding them are answered.
+        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 });
+    });
+});
+
 const REQUEST: WorkerInvokeRequest = {
     script: 'evw-test',
     appUid: 'app-test',
@@ -275,7 +402,7 @@ describe('EventsWorkerInvokerClient deploy-on-miss', () => {
 
         expect(calls).toHaveLength(1);
         expect(result).toEqual({
-            outcome: 'retriable',
+            outcome: 'unavailable',
             status: null,
             error: 'deploy: stale',
         });
@@ -300,7 +427,7 @@ describe('EventsWorkerInvokerClient deploy-on-miss', () => {
         expect(handlerCalls).toBe(1);
         // The first send plus the one retry — never a third.
         expect(calls).toHaveLength(2);
-        expect(result.outcome).toBe('retriable');
+        expect(result.outcome).toBe('unavailable');
         expect(result.status).toBeNull();
     });
 
@@ -317,7 +444,7 @@ describe('EventsWorkerInvokerClient deploy-on-miss', () => {
 
         expect(calls).toHaveLength(1);
         expect(result).toEqual({
-            outcome: 'retriable',
+            outcome: 'unavailable',
             status: null,
             error: 'dispatcher: missing (404)',
         });
@@ -342,7 +469,7 @@ describe('EventsWorkerInvokerClient deploy-on-miss', () => {
 
         expect(handlerCalled).toBe(false);
         expect(result).toEqual({
-            outcome: 'retriable',
+            outcome: 'unavailable',
             status: null,
             error: 'dispatcher: forbidden (403)',
         });
@@ -402,9 +529,205 @@ describe('EventsWorkerInvokerClient deploy-on-miss', () => {
         expect(calls).toHaveLength(2);
         expect(deployCalls).toHaveLength(0);
         expect(result).toEqual({
-            outcome: 'retriable',
+            outcome: 'unavailable',
             status: null,
             error: 'dispatcher: deploy-timeout (503)',
         });
     });
+
+    describe('a script still bound to a rotated key', () => {
+        /** Answers `bad-key` until it sees the deployed header, then settles. */
+        const badKeyUntilDeployedFetch = (
+            headersSeen: Array<Record<string, string>>,
+        ): FetchImpl =>
+            (async (_url: string, init?: RequestInit) => {
+                const headers = (init?.headers ?? {}) as Record<string, string>;
+                headersSeen.push(headers);
+                return headers[EVENTS_DEPLOYED_HEADER] === '1'
+                    ? new Response(null, {
+                          status: 200,
+                          headers: { [EVENTS_HANDLED_HEADER]: '1' },
+                      })
+                    : new Response(null, {
+                          status: 500,
+                          headers: {
+                              [EVENTS_HANDLED_HEADER]: '1',
+                              [EVENTS_ERROR_HEADER]: 'bad-key',
+                          },
+                      });
+            }) as unknown as FetchImpl;
+
+        const clientWith = (fetchImpl: FetchImpl) => {
+            const client = makeClient();
+            client.setTransport(
+                new DispatcherInvokeTransport('http://dispatcher', 's', {
+                    fetchImpl,
+                }),
+            );
+            return client;
+        };
+
+        it('is redeployed, then retried once with the deployed header', async () => {
+            const headersSeen: Array<Record<string, string>> = [];
+            const client = clientWith(badKeyUntilDeployedFetch(headersSeen));
+            const deploys: Array<[string, string]> = [];
+            client.setMissHandler(async (appUid, script) => {
+                deploys.push([appUid, script]);
+                return 'deployed';
+            });
+
+            const result = await client.invoke(REQUEST);
+
+            expect(deploys).toEqual([[REQUEST.appUid, REQUEST.script]]);
+            expect(headersSeen).toHaveLength(2);
+            expect(headersSeen[1][EVENTS_DEPLOYED_HEADER]).toBe('1');
+            expect(result).toEqual({ outcome: 'settled', status: 200 });
+        });
+
+        it('backs off, uncounted, when the redeploy is throttled', async () => {
+            const headersSeen: Array<Record<string, string>> = [];
+            const client = clientWith(badKeyUntilDeployedFetch(headersSeen));
+            client.setMissHandler(async () => 'throttled');
+
+            const result = await client.invoke(REQUEST);
+
+            expect(headersSeen).toHaveLength(1);
+            expect(result).toEqual({
+                outcome: 'unavailable',
+                status: null,
+                error: 'deploy: throttled',
+            });
+        });
+
+        it('stops after the one retry when the old key is still being served', async () => {
+            const calls: unknown[] = [];
+            const client = clientWith((async () => {
+                calls.push(null);
+                return new Response(null, {
+                    status: 500,
+                    headers: {
+                        [EVENTS_HANDLED_HEADER]: '1',
+                        [EVENTS_ERROR_HEADER]: 'bad-key',
+                    },
+                });
+            }) as unknown as FetchImpl);
+            let deploys = 0;
+            client.setMissHandler(async () => {
+                deploys++;
+                return 'deployed';
+            });
+
+            const result = await client.invoke(REQUEST);
+
+            expect(deploys).toBe(1);
+            expect(calls).toHaveLength(2);
+            expect(result.outcome).toBe('unavailable');
+        });
+
+        it('deploys nothing for a handler`s own failure', async () => {
+            const client = clientWith(
+                stubFetch(500, {
+                    [EVENTS_HANDLED_HEADER]: '1',
+                    [EVENTS_ERROR_HEADER]: 'handler-threw',
+                }),
+            );
+            let deploys = 0;
+            client.setMissHandler(async () => {
+                deploys++;
+                return 'deployed';
+            });
+
+            expect((await client.invoke(REQUEST)).outcome).toBe('retriable');
+            expect(deploys).toBe(0);
+        });
+    });
+
+    it('reports a deploy that was throttled as Puter`s failure', async () => {
+        const client = makeClient();
+        client.setTransport(
+            new DispatcherInvokeTransport('http://dispatcher', 's', {
+                fetchImpl: alwaysMissingFetch([]),
+            }),
+        );
+        client.setMissHandler(async () => 'throttled');
+
+        expect((await client.invoke(REQUEST)).outcome).toBe('unavailable');
+    });
+});
+
+describe('whose failure an invocation was', () => {
+    const invokeWith = (fetchImpl: FetchImpl, timeoutMs?: number) => {
+        const client = new EventsWorkerInvokerClient({
+            events: timeoutMs ? { invokeTimeoutMs: timeoutMs } : {},
+        } as unknown as IConfig);
+        client.setTransport(
+            new DispatcherInvokeTransport('http://dispatcher', 's', {
+                fetchImpl,
+            }),
+        );
+        return client.invoke(REQUEST);
+    };
+
+    it('counts a run past the timeout against the handler', async () => {
+        expect((await invokeWith(hangingFetch, 10)).outcome).toBe('retriable');
+    });
+
+    it('puts a request that never got an answer on Puter', async () => {
+        expect((await invokeWith(refusedFetch)).outcome).toBe('unavailable');
+    });
+
+    it('puts an unmarked 5xx, 429 or 4xx on Puter', async () => {
+        for (const status of [500, 502, 429, 404]) {
+            const result = await invokeWith(stubFetch(status));
+            expect(result).toEqual({
+                outcome: 'unavailable',
+                status,
+                error: `unmarked ${status}`,
+            });
+        }
+    });
+
+    it('puts a handler failed by a Puter API call on Puter, with its wait', async () => {
+        const result = await invokeWith(
+            stubFetch(500, {
+                [EVENTS_HANDLED_HEADER]: '1',
+                [EVENTS_ERROR_HEADER]: 'platform-error',
+                'retry-after': '20',
+            }),
+        );
+        expect(result).toEqual({
+            outcome: 'unavailable',
+            status: 500,
+            error: 'platform-error',
+            retryAfterMs: 20_000,
+        });
+    });
+
+    it('answers unavailable with no dispatcher configured', async () => {
+        const result = await makeClient().invoke(REQUEST);
+        expect(result.outcome).toBe('unavailable');
+    });
+});
+
+describe('outcomeForStatus', () => {
+    it.each([
+        [200, true, undefined, 'settled'],
+        [204, false, undefined, 'settled'],
+        [400, true, 'handler-terminal', 'terminal'],
+        [404, true, 'unknown-handler', 'terminal'],
+        [500, true, 'handler-threw', 'retriable'],
+        [500, true, 'handler-broken', 'retriable'],
+        [429, true, undefined, 'retriable'],
+        [500, true, 'bad-key', 'unavailable'],
+        [500, true, 'no-token', 'unavailable'],
+        [500, true, 'platform-error', 'unavailable'],
+        [500, false, undefined, 'unavailable'],
+        [429, false, undefined, 'unavailable'],
+        [403, false, undefined, 'unavailable'],
+    ] as const)(
+        'reads %i (handled: %s, %s) as %s',
+        (status, handled, errorCode, expected) => {
+            expect(outcomeForStatus(status, handled, errorCode)).toBe(expected);
+        },
+    );
 });

src/backend/clients/events/EventsWorkerInvokerClient.ts

@@ -68,6 +68,23 @@ export const EVENTS_HANDLED_HEADER = 'x-puter-events-handled';
 /** Machine-readable reason on the runtime's own failure answers. */
 export const EVENTS_ERROR_HEADER = 'x-puter-events-error';
 
+/**
+ * The runtime's answer to a key it does not hold: the script was deployed under
+ * a secret that has since rotated, and redeploying it binds the current key.
+ */
+const BAD_KEY_ERROR = 'bad-key';
+
+/**
+ * Runtime failure answers that are Puter's fault rather than the handler's: a
+ * key the script no longer matches, no token to run as, or a handler that
+ * failed because a Puter API call it made did.
+ */
+const PLATFORM_ERROR_CODES = new Set([
+    BAD_KEY_ERROR,
+    'no-token',
+    'platform-error',
+]);
+
 /**
  * Set on the retry after this backend deploys a missing script itself, so the
  * dispatcher skips its own deploy-on-miss callback and negative cache and goes
@@ -106,12 +123,19 @@ export const EVENTS_INVOKE_TIMEOUT_MS = 30_000;
 
 /**
  * Connections held open to the dispatcher, so a busy fleet is not
- * re-handshaking. The 30s invoke abort starts when a request is queued, not
- * when it gets a connection, so a saturated pool shows up as timeouts.
+ * re-handshaking. Also how many calls one transport makes at once: a call past
+ * that waits for a free one before its invoke timeout starts.
  */
-const INVOKE_CONNECTIONS = 256;
+export const INVOKE_CONNECTIONS = 256;
 const INVOKE_KEEP_ALIVE_MS = 30_000;
 
+/**
+ * A call waits at most this share of its invoke timeout for a connection, so
+ * the wait and the run together stay inside the worker lease (twice the
+ * timeout). Past it the call fails as Puter's, not the handler's.
+ */
+const CONNECTION_WAIT_SHARE = 0.5;
+
 /** One invocation, as the events service hands it over. */
 export interface WorkerInvokeRequest {
     /** Script the app's current handler set deploys as. */
@@ -139,27 +163,38 @@ export interface EventsInvokeCall {
     deployed?: boolean;
 }
 
+/** What one attempt at delivering an invocation came back with. */
+export interface EventsInvokeAnswer {
+    /** `null` when no answer came back. */
+    status: number | null;
+    /** Set only when the answer provably came from the script. */
+    handled?: boolean;
+    error?: string;
+    /** Set only by the dispatcher transport, naming its own failure. */
+    dispatchReason?: string;
+    /** No answer within the invoke timeout. */
+    timedOut?: boolean;
+    /** From a `retry-after` header in seconds. */
+    retryAfterMs?: number;
+}
+
 /**
- * Delivers an invocation. `status` null means nothing ran (retriable);
- * `handled` is set only when the answer provably came from the script, so an
- * unmarked 4xx is not a handler's refusal.
+ * Delivers an invocation. `handled` is set only when the answer provably came
+ * from the script, so an unmarked 4xx is not a handler's refusal.
  */
 export interface EventsInvokeTransport {
-    send(call: EventsInvokeCall): Promise<{
-        status: number | null;
-        handled?: boolean;
-        error?: string;
-        /** Set only by the dispatcher transport, naming its own failure. */
-        dispatchReason?: string;
-    }>;
+    send(call: EventsInvokeCall): Promise<EventsInvokeAnswer>;
 }
 
 /**
  * `settled`: handler accepted (2xx). `terminal`: handler refused (marked 4xx),
- * not retried. `retriable`: no handler answer (5xx, 429, timeout, transport
- * failure, unmarked 4xx).
+ * not retried. `retriable`: the handler failed or ran past the timeout.
+ * `unavailable`: Puter could not start or finish the run (transport, dispatch
+ * and deploy failures, unmarked answers, a Puter API failure inside the
+ * handler); retried like `retriable` but never the handler's fault.
  */
-export type WorkerInvokeOutcome = 'settled' | 'terminal' | 'retriable';
+export type WorkerInvokeOutcome =
+    'settled' | 'terminal' | 'retriable' | 'unavailable';
 
 export interface WorkerInvokeResult {
     outcome: WorkerInvokeOutcome;
@@ -167,6 +202,8 @@ export interface WorkerInvokeResult {
     status: number | null;
     /** Why it could not answer, when nothing did. */
     error?: string;
+    /** How long the answer asked to be left alone. */
+    retryAfterMs?: number;
 }
 
 const NO_TRANSPORT =
@@ -187,8 +224,8 @@ export class EventsWorkerInvokerClient extends PuterClient {
     /**
      * Deploys a script the dispatcher reports missing, in place of the
      * rehydrate callback — for the case where that callback lands on a backend
-     * other than this one. Set once; `invoke()` calls it at most once per
-     * delivery and never loops.
+     * other than this one — or one still bound to a rotated key. Set once;
+     * `invoke()` calls it at most once per delivery and never loops.
      */
     setMissHandler(handler: WorkerMissHandler): void {
         this.#missHandler = handler;
@@ -202,7 +239,11 @@ export class EventsWorkerInvokerClient extends PuterClient {
     async invoke(request: WorkerInvokeRequest): Promise<WorkerInvokeResult> {
         const transport = this.#pickTransport();
         if (!transport)
-            return { outcome: 'retriable', status: null, error: NO_TRANSPORT };
+            return {
+                outcome: 'unavailable',
+                status: null,
+                error: NO_TRANSPORT,
+            };
 
         const call: EventsInvokeCall = {
             script: request.script,
@@ -218,48 +259,50 @@ export class EventsWorkerInvokerClient extends PuterClient {
         };
 
         let result = await transport.send(call);
-        if (result.status === null && result.dispatchReason) {
-            if (
-                this.#missHandler &&
-                SELF_DEPLOYABLE_MISS_REASONS.has(result.dispatchReason)
-            ) {
-                const outcome = await this.#missHandler(
-                    request.appUid,
-                    request.script,
-                );
-                if (outcome !== 'deployed')
-                    return {
-                        outcome: 'retriable',
-                        status: null,
-                        error: `deploy: ${outcome}`,
-                    };
-                result = await transport.send({ ...call, deployed: true });
-            } else if (
-                ALREADY_DEPLOYED_MISS_REASONS.has(result.dispatchReason)
-            ) {
-                // No deploy to trigger — just give propagation the one retry
-                // it usually needs, without spending an upload on it.
-                result = await transport.send({ ...call, deployed: true });
-            }
+        if (this.#missHandler && selfDeployable(result)) {
+            const outcome = await this.#missHandler(
+                request.appUid,
+                request.script,
+            );
+            if (outcome !== 'deployed')
+                return {
+                    outcome: 'unavailable',
+                    status: null,
+                    error: `deploy: ${outcome}`,
+                };
+            result = await transport.send({ ...call, deployed: true });
+        } else if (
+            result.status === null &&
+            result.dispatchReason &&
+            ALREADY_DEPLOYED_MISS_REASONS.has(result.dispatchReason)
+        ) {
+            // No deploy to trigger — just give propagation the one retry
+            // it usually needs, without spending an upload on it.
+            result = await transport.send({ ...call, deployed: true });
         }
 
-        const { status, handled, error } = result;
+        const { status, handled, error, timedOut, retryAfterMs } = result;
+        // Past the timeout the handler was most likely still running, which
+        // is its own doing; any other missing answer never reached it.
         if (status === null)
-            return { outcome: 'retriable', status: null, error };
+            return {
+                outcome: timedOut ? 'retriable' : 'unavailable',
+                status: null,
+                error,
+            };
 
-        const outcome = outcomeForStatus(status, handled === true);
-        // An unmarked 4xx (429 aside — that one is always retriable) is not
-        // the handler's own answer; say so even when the transport did not,
-        // so the reason a delivery kept retrying shows up in the log rather
-        // than reading as an unexplained retry.
-        const unmarkedFourxx =
-            status !== 429 && status >= 400 && status < 500 && !handled;
+        const outcome = outcomeForStatus(status, handled === true, error);
+        // An unmarked failure is not the handler's own answer; say so even
+        // when the transport did not, so the reason a delivery kept retrying
+        // shows up in the log rather than reading as an unexplained retry.
+        const unmarked = status >= 300 && !handled;
         const reportedError =
-            error ?? (unmarkedFourxx ? 'unmarked 4xx' : undefined);
+            error ?? (unmarked ? `unmarked ${status}` : undefined);
         return {
             outcome,
             status,
             ...(reportedError ? { error: reportedError } : {}),
+            ...(retryAfterMs ? { retryAfterMs } : {}),
         };
     }
 
@@ -291,6 +334,10 @@ export class DispatcherInvokeTransport implements EventsInvokeTransport {
     readonly #secret: string;
     readonly #fetchImpl: typeof undiciFetch;
     #agent: Agent | null = null;
+    /** Calls holding a connection slot. */
+    #active = 0;
+    /** Calls waiting for one, longest-waiting first. */
+    readonly #waiting = new Set<() => void>();
 
     constructor(
         dispatcherUrl: string,
@@ -307,12 +354,14 @@ export class DispatcherInvokeTransport implements EventsInvokeTransport {
         this.#agent = null;
     }
 
-    async send(call: EventsInvokeCall): Promise<{
-        status: number | null;
-        handled?: boolean;
-        error?: string;
-        dispatchReason?: string;
-    }> {
+    async send(call: EventsInvokeCall): Promise<EventsInvokeAnswer> {
+        // No `timedOut`: the handler never got this call, so the wait is not
+        // its failure.
+        if (!(await this.#acquire(call.timeoutMs * CONNECTION_WAIT_SHARE)))
+            return {
+                status: null,
+                error: 'no free connection to the events dispatcher',
+            };
         try {
             // `new URL(path, base)` resolves an absolute path against the
             // base's origin, dropping any path prefix `base` already carries.
@@ -347,21 +396,45 @@ export class DispatcherInvokeTransport implements EventsInvokeTransport {
                     dispatchReason: dispatchError,
                 };
 
-            const handled = response.headers.get(EVENTS_HANDLED_HEADER) === '1';
-            const errorHeader = response.headers.get(EVENTS_ERROR_HEADER);
-            return {
-                status: response.status,
-                handled,
-                ...(errorHeader ? { error: errorHeader } : {}),
-            };
+            return answerFrom(response);
         } catch (err) {
-            return {
-                status: null,
-                error: err instanceof Error ? err.message : String(err),
-            };
+            return failedAnswer(err);
+        } finally {
+            this.#release();
         }
     }
 
+    /** A connection slot, or false once `waitMs` passes without one. */
+    #acquire(waitMs: number): Promise<boolean> {
+        if (this.#active < INVOKE_CONNECTIONS) {
+            this.#active++;
+            return Promise.resolve(true);
+        }
+        return new Promise((resolve) => {
+            const granted = () => {
+                clearTimeout(timer);
+                resolve(true);
+            };
+            const timer = setTimeout(() => {
+                this.#waiting.delete(granted);
+                resolve(false);
+            }, waitMs);
+            timer.unref?.();
+            this.#waiting.add(granted);
+        });
+    }
+
+    /** Hand the slot to the longest waiter, or give it back. */
+    #release(): void {
+        const next = this.#waiting.values().next().value;
+        if (next) {
+            this.#waiting.delete(next);
+            next();
+            return;
+        }
+        this.#active--;
+    }
+
     /** One pool per process, built on first use and closed with the server. */
     #dispatcherFor(): Agent {
         this.#agent ??= new Agent({
@@ -373,18 +446,61 @@ export class DispatcherInvokeTransport implements EventsInvokeTransport {
     }
 }
 
+/** Whether deploying the script is what fixes this answer. */
+const selfDeployable = (result: EventsInvokeAnswer): boolean =>
+    result.status === null
+        ? result.dispatchReason !== undefined &&
+          SELF_DEPLOYABLE_MISS_REASONS.has(result.dispatchReason)
+        : result.handled === true && result.error === BAD_KEY_ERROR;
+
+/** What a script's answer says, read the same way by every transport. */
+export const answerFrom = (response: {
+    status: number;
+    headers: { get(name: string): string | null };
+}): EventsInvokeAnswer => {
+    const errorHeader = response.headers.get(EVENTS_ERROR_HEADER);
+    const retryAfterMs = parseRetryAfterMs(response.headers.get('retry-after'));
+    return {
+        status: response.status,
+        handled: response.headers.get(EVENTS_HANDLED_HEADER) === '1',
+        ...(errorHeader ? { error: errorHeader } : {}),
+        ...(retryAfterMs ? { retryAfterMs } : {}),
+    };
+};
+
+/** An attempt that threw before any answer came back. */
+export const failedAnswer = (err: unknown): EventsInvokeAnswer => ({
+    status: null,
+    error: err instanceof Error ? err.message : String(err),
+    // What `AbortSignal.timeout` rejects with.
+    ...((err as { name?: unknown } | null)?.name === 'TimeoutError'
+        ? { timedOut: true }
+        : {}),
+});
+
+/** Whole seconds only; an HTTP-date form reads as absent. */
+const parseRetryAfterMs = (value: string | null): number => {
+    const seconds = Number(value);
+    return value && Number.isFinite(seconds) && seconds > 0
+        ? seconds * 1000
+        : 0;
+};
+
 /**
- * 2xx took it regardless. 429 is always "not now". Any other 4xx is a refusal
- * only when `handled` says the answer is provably the script's own — an
- * unmarked 4xx came from something between here and the handler.
+ * 2xx took it regardless. Anything else not marked as the script's own answer
+ * came from something between here and the handler. A marked answer is a
+ * refusal when it is a 4xx other than 429, Puter's failure when the runtime
+ * names one, and the handler's failure otherwise.
  */
 export const outcomeForStatus = (
     status: number,
     handled: boolean,
+    errorCode?: string,
 ): WorkerInvokeOutcome => {
     if (status >= 200 && status < 300) return 'settled';
+    if (!handled) return 'unavailable';
+    if (errorCode && PLATFORM_ERROR_CODES.has(errorCode)) return 'unavailable';
     if (status === 429) return 'retriable';
-    if (status >= 400 && status < 500)
-        return handled ? 'terminal' : 'retriable';
+    if (status >= 400 && status < 500) return 'terminal';
     return 'retriable';
 };

src/backend/controllers/auth/AuthController.elevation.http.test.ts

@@ -0,0 +1,85 @@
+/*
+ * 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/>.
+ */
+
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+import { setupPuterTestEnv, type PuterTestEnv } from '../../testUtil.js';
+
+describe('auth elevation cookies over HTTP', () => {
+    let env: PuterTestEnv;
+
+    beforeAll(async () => {
+        env = await setupPuterTestEnv();
+    }, 120_000);
+
+    afterAll(async () => {
+        await env?.shutdown();
+    });
+
+    it.each(['bearer', 'cookie'])(
+        'API host returns a usable token without setting cookies (%s auth)',
+        async (credential) => {
+            const { token, password, username } = env.users.user;
+            const res = await fetch(new URL('/auth/elevate', env.apiOrigin), {
+                method: 'POST',
+                headers: {
+                    'content-type': 'application/json',
+                    ...(credential === 'cookie'
+                        ? { cookie: `puter_auth_token=${token}` }
+                        : { authorization: `Bearer ${token}` }),
+                },
+                body: JSON.stringify({ password }),
+            });
+            expect(res.status).toBe(200);
+            expect(res.headers.get('set-cookie')).toBeNull();
+            const body = (await res.json()) as {
+                elevated: boolean;
+                token: string;
+            };
+            expect(body.elevated).toBe(true);
+            expect(typeof body.token).toBe('string');
+            const user = await env.server.stores.user.getByUsername(username);
+            const { verifyStepUpSession } =
+                await import('../../core/http/middleware/stepUpSession.js');
+            expect(
+                verifyStepUpSession(
+                    {
+                        headers: { 'x-puter-elevation': body.token },
+                        actor: { user: { uuid: user!.uuid } },
+                    } as never,
+                    { tokenService: env.server.services.token },
+                ),
+            ).toBe(true);
+        },
+    );
+
+    it('GUI host sets the elevation cookie and omits the raw token for cookie auth', async () => {
+        const { token, password } = env.users.user;
+        const res = await fetch(new URL('/auth/elevate', env.origin), {
+            method: 'POST',
+            headers: {
+                'content-type': 'application/json',
+                cookie: `puter_auth_token=${token}`,
+            },
+            body: JSON.stringify({ password }),
+        });
+        expect(res.status).toBe(200);
+        expect(res.headers.get('set-cookie')).toContain('puter_elevated=');
+        expect(await res.json()).toEqual({ elevated: true });
+    });
+});

src/backend/controllers/auth/AuthController.test.ts

@@ -42,6 +42,10 @@ import {
     adminOnlyGate,
     requireUserActorGate,
 } from '../../core/http/middleware/gates.js';
+import {
+    configureRateLimit,
+    listConfiguredRateLimitBackends,
+} from '../../core/http/middleware/rateLimit.js';
 import {
     ROUTES_METADATA_KEY,
     type CollectedRoute,
@@ -50,7 +54,10 @@ import {
 import { PuterServer } from '../../server.js';
 import { createSecret as otpCreateSecret } from '../../services/auth/OTPUtil.js';
 import { kvSharePermission } from '../../services/kvShare/kvShares.js';
-import { FULL_API_ACCESS } from '../../services/permission/consts.js';
+import {
+    FULL_API_ACCESS,
+    NOTIFICATIONS_PUSH_PERMISSION,
+} from '../../services/permission/consts.js';
 import { setupTestServer } from '../../testUtil.js';
 import { resetCardVerificationStatusCache } from '../../util/cardFallback.js';
 import { FS_READ_LIMIT } from '../fs/limits.js';
@@ -1750,6 +1757,40 @@ describe('AuthController.handleLoginOtp + handleLoginRecoveryCode', () => {
         ).rejects.toMatchObject({ statusCode: 400 });
     });
 
+    it('refuses the sign-in while the used-token store is down', async () => {
+        const { user, secret, otpToken } = await startOtpLogin();
+        const token = await otpToken();
+
+        const { default: backend } = listConfiguredRateLimitBackends();
+        configureRateLimit({
+            default: 'redis',
+            redis: {
+                multi: () => {
+                    throw new Error('store down');
+                },
+            },
+        });
+        const logged = vi.spyOn(console, 'error').mockImplementation(() => {});
+        const res = makeRes();
+        try {
+            await expect(
+                controller.handleLoginOtp(
+                    makeReq({ token, code: liveTotp(user.username, secret) }),
+                    res,
+                ),
+            ).rejects.toThrow('store down');
+        } finally {
+            logged.mockRestore();
+            configureRateLimit({
+                default: backend,
+                redis: server.clients.redis,
+                kv: server.stores.kv,
+                metering: server.services.metering,
+            });
+        }
+        expect(res.body).toBeUndefined();
+    });
+
     it('a wrong code leaves the token usable for a retry', async () => {
         const { user, secret, otpToken } = await startOtpLogin();
         const token = await otpToken();
@@ -2179,6 +2220,78 @@ describe('AuthController grant flows', () => {
         ).toContain(permission);
     });
 
+    it('grant-user-app: grants and revokes notifications:push for an app', async () => {
+        const app = await server.stores.app.create(
+            {
+                name: `tgp-${uuidv4()}`,
+                title: 'TestGrantPushApp',
+                index_url: 'https://example.test/index.html',
+            },
+            { ownerUserId: issuer.id },
+        );
+        const user = await server.stores.user.getById(issuer.id);
+        const appActor = makeActor({
+            user: user!,
+            app: { uid: app.uid, id: app.id },
+        });
+        const hasPush = () =>
+            server.services.permission.check(
+                appActor,
+                NOTIFICATIONS_PUSH_PERMISSION,
+            );
+        expect(await hasPush()).toBe(false);
+
+        // Anything past the bare permission names nothing a prompt describes.
+        await expect(
+            inCtx(issuerActor, () =>
+                controller.handleGrantUserApp(
+                    makeReq(
+                        {
+                            app_uid: app.uid,
+                            permission: `${NOTIFICATIONS_PUSH_PERMISSION}:extra`,
+                        },
+                        { actor: issuerActor },
+                    ),
+                    makeRes(),
+                ),
+            ),
+        ).rejects.toMatchObject({
+            statusCode: 400,
+            legacyCode: 'permission_not_grantable',
+        });
+        expect(await hasPush()).toBe(false);
+
+        const res = makeRes();
+        await inCtx(issuerActor, () =>
+            controller.handleGrantUserApp(
+                makeReq(
+                    {
+                        app_uid: app.uid,
+                        permission: NOTIFICATIONS_PUSH_PERMISSION,
+                    },
+                    { actor: issuerActor },
+                ),
+                res,
+            ),
+        );
+        expect(res.body).toEqual({});
+        expect(await hasPush()).toBe(true);
+
+        await inCtx(issuerActor, () =>
+            controller.handleRevokeUserApp(
+                makeReq(
+                    {
+                        app_uid: app.uid,
+                        permission: NOTIFICATIONS_PUSH_PERMISSION,
+                    },
+                    { actor: issuerActor },
+                ),
+                makeRes(),
+            ),
+        );
+        expect(await hasPush()).toBe(false);
+    });
+
     it('grant-user-app: resolves `origin` to the app when app_uid is omitted', async () => {
         // The GUI permission dialog and puter.perms.grantOrigin() identify
         // third-party sites by origin rather than app uid.
@@ -7612,6 +7725,46 @@ describe('AuthController permission revokes', () => {
         );
         expect(res.body).toEqual({});
     });
+
+    it('revoke-user-user: refuses a key-value share grant and leaves it standing', async () => {
+        const { actor: ownerActor, user: owner } = await makeUserAndActor();
+        const { user: holder } = await makeUserAndActor();
+        const permissions = ['kv-share', 'kv-share-read', 'kv-share-write'].map(
+            (root) => `${root}:${owner.uuid}:os-global:notes:${uuidv4()}`,
+        );
+        for (const permission of permissions)
+            await server.stores.permission.upsertUserUserPerm(
+                holder.id,
+                owner.id,
+                permission,
+                {},
+            );
+
+        for (const permission of permissions)
+            await expect(
+                inCtx(ownerActor, () =>
+                    controller.handleRevokeUserUser(
+                        makeReq(
+                            { target_username: holder.username, permission },
+                            { actor: ownerActor },
+                        ),
+                        makeRes(),
+                    ),
+                ),
+            ).rejects.toMatchObject({
+                statusCode: 400,
+                message: expect.stringContaining('puter.kv.unshare()'),
+            });
+        expect(
+            (
+                await server.stores.permission.findUserUserPermsByIssuer(
+                    holder.id,
+                    owner.id,
+                    permissions,
+                )
+            ).sort(),
+        ).toEqual([...permissions].sort());
+    });
 });
 
 // ── Permission checks + listing ────────────────────────────────────

src/backend/controllers/auth/AuthController.ts

@@ -3304,6 +3304,14 @@ export class AuthController extends PuterController {
                 { legacyCode: 'bad_request' },
             );
         }
+        // Only unsharing retires the handle along with its grant; withdrawing
+        // the grant alone would leave the share listed and dead.
+        if (typeof permission === 'string' && isKvSharePermission(permission))
+            throw new HttpError(
+                400,
+                'Stop a key-value share with `puter.kv.unshare()` (`DELETE /kv/shares/:handle`)',
+                { legacyCode: 'bad_request' },
+            );
         await this.services.permission.revokeUserUserPermission(
             req.actor!,
             target_username,
@@ -3810,8 +3818,9 @@ export class AuthController extends PuterController {
 
         let app = await this.stores.app.getByUid(app_uid);
         if (!app && resolvedFromOrigin) {
-            // Hosted-subdomain origins get the site owner stamped as the
-            // app's creator at bootstrap; external origins stay unowned.
+            // Hosted-subdomain and custom-domain origins get the site owner
+            // stamped as the app's creator at bootstrap; external origins
+            // stay unowned.
             // Canonical origin only, so alternate hosts share one row.
             const canonicalOrigin =
                 this.services.auth.canonicalizeOrigin(origin);
@@ -3827,9 +3836,10 @@ export class AuthController extends PuterController {
             // An origin's uid is a deterministic uuidv5, so a deleted app
             // reappears here under the identical uid. Withdraw any cross-app
             // data grants left pointing at it before this new row can inherit
-            // consent the user gave its predecessor. Only *this* path can reuse
-            // a uid: `AppStore.create` mints a random uuid4, which no deleted
-            // app can ever hold again.
+            // consent the user gave its predecessor. Only `createFromOrigin`
+            // reuses a uid, here or wherever else an origin app is bootstrapped:
+            // `AppStore.create` mints a random uuid4, which no deleted app can
+            // ever hold again.
             //
             // Called directly rather than through `app.changed`: the token is
             // issued below, so this has to be able to stop that, and
@@ -3840,6 +3850,9 @@ export class AuthController extends PuterController {
                 app_uid,
                 'uid reused by a new app',
             );
+            // Key-value shares the predecessor left read as gone already,
+            // being older than this row; this only cleans them up.
+            this.services.kvShare.retireSharesOlderThanApp(app);
         }
         if (!app) {
             throw new HttpError(404, `App ${app_uid} does not exist`, {
@@ -4275,7 +4288,27 @@ export class AuthController extends PuterController {
             );
         }
 
-        this.#requireAccountTwoFactor(user, req.body?.code);
+        const code = req.body?.code;
+        if (
+            user.otp_enabled &&
+            typeof code === 'string' &&
+            /^[A-Z0-9]{8}$/.test(code)
+        ) {
+            await this.#assertSecondFactorAttemptsRemain(user.uuid);
+            const consumed = await this.stores.user.consumeOtpRecoveryCode(
+                user.id,
+                hashRecoveryCode(code),
+            );
+            if (!consumed) {
+                await this.#recordSecondFactorFailure(user.uuid);
+                throw new HttpError(401, 'Incorrect code.', {
+                    legacyCode: 'code_mismatch',
+                    fields: { factor: 'otp' },
+                });
+            }
+        } else {
+            this.#requireAccountTwoFactor(user, code);
+        }
 
         await this.stores.user.update(user.id, {
             otp_enabled: false,
@@ -4485,11 +4518,14 @@ export class AuthController extends PuterController {
         }
 
         const token = signStepUpToken(this.services.token, user as never);
-        res.cookie(
-            STEP_UP_COOKIE_NAME,
-            token,
-            stepUpCookieOptions(this.config),
-        );
+        const isApiHost = req.subdomains?.at(-1) === 'api';
+        if (!isApiHost) {
+            res.cookie(
+                STEP_UP_COOKIE_NAME,
+                token,
+                stepUpCookieOptions(this.config),
+            );
+        }
 
         // A browser reads its elevation back from the httpOnly cookie and never
         // needs the raw value; handing it to page JS would put the second factor
@@ -4498,7 +4534,9 @@ export class AuthController extends PuterController {
         // password/TOTP — this only avoids needless exposure, it isn't a gate.
         const cookieName = this.config.cookie_name ?? 'puter_token';
         const usedSessionCookie =
-            !!req.token && req.token === req.cookies?.[cookieName];
+            !isApiHost &&
+            !!req.token &&
+            req.token === req.cookies?.[cookieName];
         res.json(
             usedSessionCookie ? { elevated: true } : { elevated: true, token },
         );
@@ -4611,13 +4649,19 @@ export class AuthController extends PuterController {
         await checkRateLimit(`${scope}:${userUid}`, limit, window);
     }
 
-    /** An `otp-login` JWT completes one sign-in; a second redemption is refused. */
+    /**
+     * An `otp-login` JWT completes one sign-in; a second redemption is refused.
+     * Fails closed: while the store can't say whether the token was used, the
+     * sign-in is refused rather than letting a captured token replay.
+     */
     async #consumeOtpLoginToken(token: string): Promise<void> {
         const digest = crypto.createHash('sha256').update(token).digest('hex');
         const firstUse = await checkRateLimit(
             `login-otp-token-used:${digest}`,
             1,
             OTP_LOGIN_TOKEN_USED_WINDOW_MS,
+            undefined,
+            { failOpen: false },
         );
         if (!firstUse) {
             throw new HttpError(400, 'Invalid token.', {

src/backend/controllers/auth/recoveryDisable2fa.http.test.ts

@@ -0,0 +1,89 @@
+import { v4 as uuidv4 } from 'uuid';
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+import { hashRecoveryCode } from '../../services/auth/OTPUtil.js';
+import {
+    createTestUser,
+    setupPuterTestEnv,
+    type PuterTestEnv,
+} from '../../testUtil.js';
+
+describe('2FA after signing in with a recovery code', () => {
+    let env: PuterTestEnv;
+    const password = 'lost-authenticator-password';
+
+    beforeAll(async () => {
+        env = await setupPuterTestEnv();
+    }, 120_000);
+    afterAll(async () => {
+        await env?.shutdown();
+    });
+
+    const post = (
+        path: string,
+        body: Record<string, unknown>,
+        cookie?: string,
+    ) =>
+        fetch(new URL(path, env.origin), {
+            method: 'POST',
+            headers: {
+                'content-type': 'application/json',
+                ...(cookie ? { cookie } : {}),
+            },
+            body: JSON.stringify(body),
+        });
+
+    it('allows an unused recovery code to disable 2FA after password revalidation', async () => {
+        const username = `lost2fa_${uuidv4().slice(0, 8)}`;
+        await createTestUser(env.server, { username, password });
+        const user = (await env.server.stores.user.getByUsername(username))!;
+        await env.server.stores.user.update(user.id, {
+            email: `${username}@example.com`,
+            email_confirmed: true,
+            otp_enabled: true,
+            otp_secret: 'TESTSECRETBASE32',
+            otp_recovery_codes: ['RECOVER1', 'RECOVER2', 'RECOVER3']
+                .map(hashRecoveryCode)
+                .join(','),
+        });
+
+        // Sign in with a recovery code: works, and yields a web session.
+        const login = await post('/login', { username, password });
+        expect(login.status).toBe(202);
+        const { otp_jwt_token } = await login.json();
+        const recovered = await post('/login/recovery-code', {
+            token: otp_jwt_token,
+            code: 'RECOVER1',
+        });
+        expect((await recovered.json()).next_step).toBe('complete');
+        const cookie = recovered.headers
+            .getSetCookie()
+            .find((value) => value.startsWith('puter_auth_token='))!
+            .split(';')[0]!;
+
+        const reused = await post(
+            '/user-protected/disable-2fa',
+            { password, code: 'RECOVER1' },
+            cookie,
+        );
+        expect(reused.status).toBe(401);
+        expect(
+            (await env.server.stores.user.getById(user.id, { force: true }))!
+                .otp_enabled,
+        ).toBeTruthy();
+
+        const disable = await post(
+            '/user-protected/disable-2fa',
+            { password, code: 'RECOVER2' },
+            cookie,
+        );
+        expect(disable.status).toBe(200);
+        expect(await disable.json()).toMatchObject({ success: true });
+
+        const after = await env.server.stores.user.getById(user.id, {
+            force: true,
+        });
+        expect(after!.otp_enabled).toBeFalsy();
+        expect(after!.otp_secret).toBeNull();
+        expect(after!.otp_recovery_codes).toBeNull();
+    });
+});

src/backend/controllers/drivers/DriverController.concurrent.test.ts

@@ -21,7 +21,7 @@
 import { EventEmitter } from 'node:events';
 import type { Request, RequestHandler, Response } from 'express';
 import { beforeEach, describe, expect, it } from 'vitest';
-import { runWithContext } from '../../core/context.js';
+import { Context, runWithContext } from '../../core/context.js';
 import { isHttpError } from '../../core/http/HttpError.js';
 import { configureRateLimit } from '../../core/http/middleware/rateLimit.js';
 import { DriverController } from './DriverController.js';
@@ -278,6 +278,86 @@ describe('DriverController — concurrent acquire/release', () => {
         expect(res2.body).toMatchObject({ success: true, result: 'pong' });
     });
 
+    // A driver that keeps working after the caller hangs up (async video
+    // polling) must keep counting against the cap until it settles.
+    it('holds the slot while the driver still works after a disconnect', async () => {
+        let finish = () => {};
+        const driver = {
+            ...makeSyntheticDriver(),
+            ping: () =>
+                new Promise<string>((resolve) => {
+                    finish = () => resolve('pong');
+                }),
+        };
+        const handler = captureCallHandler(buildController(driver));
+        const req = () =>
+            makeReq({ interface: 'test-iface', method: 'ping' }, 'working');
+
+        const res1 = new StubRes();
+        const first = callInScope(handler, req(), res1 as unknown as Response);
+        await new Promise((r) => setImmediate(r));
+        res1.emit('close');
+        await new Promise((r) => setImmediate(r));
+
+        await expect(
+            callInScope(handler, req(), new StubRes() as unknown as Response),
+        ).rejects.toSatisfy(
+            (e) =>
+                isHttpError(e) &&
+                (e as { statusCode: number }).statusCode === 429,
+        );
+
+        finish();
+        await first;
+        await new Promise((r) => setImmediate(r));
+        const res2 = new StubRes();
+        const second = callInScope(handler, req(), res2 as unknown as Response);
+        await new Promise((r) => setImmediate(r));
+        finish();
+        await second;
+        res2.emit('finish');
+        expect(res2.body).toMatchObject({ success: true, result: 'pong' });
+    });
+
+    it('holds the slot for work a driver keeps past its response', async () => {
+        let settleWork = () => {};
+        const driver = {
+            ...makeSyntheticDriver(),
+            ping: async () => {
+                Context.get('keepDriverSlot')?.(
+                    new Promise<void>((resolve) => {
+                        settleWork = resolve;
+                    }),
+                );
+                return 'pong';
+            },
+        };
+        const handler = captureCallHandler(buildController(driver));
+        const req = () =>
+            makeReq({ interface: 'test-iface', method: 'ping' }, 'kept');
+
+        const res1 = new StubRes();
+        await callInScope(handler, req(), res1 as unknown as Response);
+        res1.emit('finish');
+        await new Promise((r) => setImmediate(r));
+
+        await expect(
+            callInScope(handler, req(), new StubRes() as unknown as Response),
+        ).rejects.toSatisfy(
+            (e) =>
+                isHttpError(e) &&
+                (e as { statusCode: number }).statusCode === 429,
+        );
+
+        settleWork();
+        await new Promise((r) => setImmediate(r));
+        const res2 = new StubRes();
+        await callInScope(handler, req(), res2 as unknown as Response);
+        res2.emit('finish');
+        settleWork();
+        expect(res2.body).toMatchObject({ success: true, result: 'pong' });
+    });
+
     it('does not attach release listeners when the driver declares no concurrent config', async () => {
         // With no spec there is nothing to release, so the gate must not
         // wire `finish`/`close` release listeners. The client-disconnect

src/backend/controllers/drivers/DriverController.ts

@@ -50,6 +50,7 @@ import { PermissionUtil } from '../../services/permission/permissionUtil.js';
 import type { WithLifecycle } from '../../types';
 import { withSpan } from '../../util/span.js';
 import { PuterController } from '../types.js';
+import { CallSlot } from './callSlot.js';
 
 type DriverInstance = WithLifecycle & Record<string, unknown>;
 
@@ -259,6 +260,17 @@ export class DriverController extends PuterController {
     // -- Handlers ----------------------------------------------------
 
     #handleCall = async (req: Request, res: Response): Promise<void> => {
+        const slot = new CallSlot();
+        const call = this.#call(req, res, slot);
+        slot.keep(call);
+        await call;
+    };
+
+    #call = async (
+        req: Request,
+        res: Response,
+        slot: CallSlot,
+    ): Promise<void> => {
         const {
             interface: ifaceName,
             method,
@@ -395,10 +407,9 @@ export class DriverController extends PuterController {
 
         // Per-method rate-limit and concurrent specs both live on the
         // driver's resolved meta. Rate-limit is single-shot; concurrent
-        // acquires a slot that must be released when the response is done
-        // — we hook `res.finish` / `res.close` for that so streamed
-        // responses hold their slot until the stream drains, and aborted
-        // requests still give the slot back.
+        // acquires a slot held until the response is done and the call's
+        // work has settled, so streamed responses hold it until the stream
+        // drains and work that continues after a disconnect still counts.
         const rateLimitSpec = resolvePerMethod(driverMeta?.rateLimit, method);
         if (
             !(await checkDriverRateLimit(req, ifaceName, method, rateLimitSpec))
@@ -430,18 +441,8 @@ export class DriverController extends PuterController {
                     legacyCode: 'too_many_requests',
                 });
             }
-            let released = false;
-            const release = () => {
-                if (released) return;
-                released = true;
-                void handle.release();
-            };
-            // If the handler throws before responding, the express error
-            // handler will eventually send a response — `finish` fires then,
-            // so we still release. `close` covers client aborts.
-            res.once('finish', release);
-            res.once('close', release);
-            if (res.destroyed || res.writableFinished) release();
+            slot.attach(handle, res);
+            Context.set('keepDriverSlot', (work) => slot.keep(work));
         }
 
         // Stash the requested driver name in Context so multi-provider

src/backend/controllers/drivers/callSlot.test.ts

@@ -0,0 +1,73 @@
+/*
+ * 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/>.
+ */
+
+import { EventEmitter } from 'node:events';
+import type { Response } from 'express';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { CallSlot } from './callSlot.js';
+
+const handle = () => ({
+    release: vi.fn(() => Promise.resolve()),
+    renew: vi.fn(() => Promise.resolve()),
+});
+
+const deferred = () => {
+    let resolve = () => {};
+    const promise = new Promise<void>((r) => {
+        resolve = r;
+    });
+    return { promise, resolve };
+};
+
+afterEach(() => {
+    vi.useRealTimers();
+});
+
+describe('CallSlot', () => {
+    it('renews a slot held by a long call and stops once it is released', async () => {
+        vi.useFakeTimers();
+        const slot = new CallSlot();
+        const slotHandle = handle();
+        const res = new EventEmitter();
+        const call = deferred();
+        slot.keep(call.promise);
+        slot.attach(slotHandle, res as unknown as Response);
+
+        res.emit('close');
+        await vi.advanceTimersByTimeAsync(25 * 60 * 1000);
+        expect(slotHandle.renew).toHaveBeenCalledTimes(2);
+        expect(slotHandle.release).not.toHaveBeenCalled();
+
+        call.resolve();
+        await vi.advanceTimersByTimeAsync(0);
+        expect(slotHandle.release).toHaveBeenCalledOnce();
+        await vi.advanceTimersByTimeAsync(25 * 60 * 1000);
+        expect(slotHandle.renew).toHaveBeenCalledTimes(2);
+    });
+
+    it('releases once the response is done if no work is outstanding', async () => {
+        const slot = new CallSlot();
+        const slotHandle = handle();
+        const res = new EventEmitter();
+        slot.attach(slotHandle, res as unknown as Response);
+        res.emit('finish');
+        expect(slotHandle.release).toHaveBeenCalledOnce();
+        expect(slotHandle.renew).not.toHaveBeenCalled();
+    });
+});

src/backend/controllers/drivers/callSlot.ts

@@ -0,0 +1,80 @@
+/*
+ * 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/>.
+ */
+
+import type { Response } from 'express';
+
+// Under the concurrency store's one-hour orphan TTL.
+const SLOT_RENEW_MS = 10 * 60 * 1000;
+
+interface SlotHandle {
+    release(): Promise<void>;
+    renew?(): Promise<void>;
+}
+
+/**
+ * A driver call's concurrency slot, held until the response is done and the
+ * call's work has settled, including work a driver carries on after the caller
+ * hung up or was answered.
+ */
+export class CallSlot {
+    #handle?: SlotHandle;
+    #work = new Set<Promise<unknown>>();
+    #responded = false;
+    #released = false;
+    #renew?: NodeJS.Timeout;
+
+    attach(handle: SlotHandle, res: Response): void {
+        this.#handle = handle;
+        const responded = () => {
+            this.#responded = true;
+            this.#maybeRelease();
+        };
+        res.once('finish', responded);
+        res.once('close', responded);
+        if (res.destroyed || res.writableFinished) responded();
+        if (!this.#released && this.#work.size > 0) this.#startRenewing();
+    }
+
+    keep(work: Promise<unknown>): void {
+        if (this.#released) return;
+        this.#work.add(work);
+        if (this.#handle) this.#startRenewing();
+        const settled = () => {
+            this.#work.delete(work);
+            this.#maybeRelease();
+        };
+        work.then(settled, settled);
+    }
+
+    #startRenewing(): void {
+        if (this.#renew) return;
+        this.#renew = setInterval(() => {
+            void this.#handle?.renew?.();
+        }, SLOT_RENEW_MS);
+        this.#renew.unref?.();
+    }
+
+    #maybeRelease(): void {
+        if (this.#released || !this.#handle) return;
+        if (!this.#responded || this.#work.size > 0) return;
+        this.#released = true;
+        clearInterval(this.#renew);
+        void this.#handle.release();
+    }
+}

src/backend/controllers/events/EventsController.ts

@@ -104,6 +104,24 @@ export class EventsController extends PuterController {
         });
     }
 
+    /**
+     * POST /events/subscriptions/update — replace one subscription's `context`
+     * in place. An id the caller does not hold reads as absent.
+     */
+    @Post('/subscriptions/update', {
+        subdomain: 'api',
+        requireAuth: true,
+        allowAccessToken: true,
+    })
+    async update(req: Request, res: Response): Promise<void> {
+        const actor = this.#requireActor(req);
+        const { sub } = await this.services.events.updateDurable(
+            actor,
+            bodyRecord(req),
+        );
+        res.json(sub);
+    }
+
     /**
      * GET /events/fetch — what the caller missed, one page at a time.
      *

src/backend/controllers/events/limits.ts

@@ -93,6 +93,18 @@ export interface TieredQuota {
  */
 export const EVENTS_SESSION_SUBSCRIPTIONS_PER_SOCKET = 50;
 
+/**
+ * Live subscriptions one user may hold through a share handle someone else
+ * minted for them, across all of their connections.
+ *
+ * Those rows sit in the owner's keyspace, where each one costs a filter
+ * evaluation on the owner's writes. The count also takes in connections that
+ * dropped and haven't been reaped yet, so the cap sits far above what
+ * reconnects leave behind. The owner's own rows through the handle don't
+ * count.
+ */
+export const EVENTS_SESSION_SUBSCRIPTIONS_PER_KV_HANDLE = 1000;
+
 /**
  * Durable subscriptions one account may hold, across every app.
  *
@@ -125,6 +137,13 @@ export const EVENTS_DURABLE_SUBSCRIPTIONS_MAX =
  */
 export const SUSPENDED_ROW_TTL_DAYS = 30;
 
+/**
+ * Subscriptions stopped by a revoked grant that one account keeps for `list`.
+ * They hold no quota slot, so past this the oldest are deleted when the account
+ * subscribes again, keeping its rows bounded.
+ */
+export const EVENTS_REVOKED_SUBSCRIPTIONS_KEPT = 500;
+
 /**
  * Subscribe calls per minute, per user.
  *
@@ -155,6 +174,13 @@ export const EVENTS_LIST_LIMIT = userWindow('events:list', 120);
  */
 export const EVENTS_ACK_LIMIT = userWindow('events:ack', 600);
 
+/**
+ * How long a connected client holds a queued delivery before the events worker
+ * may take it. A client that has no handler for it, or whose handler fails,
+ * declines it at once; this only bounds one that never answers.
+ */
+export const EVENTS_SOCKET_LEASE_MS = 15_000;
+
 /**
  * Share-handle mint + revoke calls per minute, per user.
  *
@@ -197,17 +223,35 @@ export const EVENTS_KV_HANDLES_PER_APP = tiered(10_000, 2_000, 0);
 export const EVENTS_KV_HANDLES_PER_HOLDER = 256;
 
 /**
- * Recipients one account may share with, per minute and per hour. A batch
- * spends one per recipient, on top of the per-call mint budget.
+ * Recipients one account may share with, per minute and per hour. A call spends
+ * one per recipient that doesn't already hold the share, on top of the per-call
+ * mint budget.
  */
 export const KV_SHARE_GRANT_LIMITS = [
     userWindow('kvShare:grants:minute', 300),
     userWindow('kvShare:grants:hour', 2_000, 60 * 60_000),
 ] as const;
 
+/**
+ * Recipients one account may name in share calls per minute, existing shares
+ * included. Each one is looked up before the call knows whether it changes
+ * anything, so a client that shares again on every load is bounded here.
+ */
+export const KV_SHARE_LOOKUP_LIMIT = userWindow('kvShare:lookups', 1_200);
+
 /** Recipients one `POST /kv/shares` call may name. */
 export const KV_SHARE_BATCH_MAX = 50;
 
+/**
+ * Notifications one party of a share may send the other through share handles,
+ * per minute and per day, in one app. Keeps one share from spending the
+ * recipient's whole notification allowance.
+ */
+export const KV_SHARE_NOTIFY_LIMITS = [
+    userWindow('kvShare:notify:minute', 30),
+    userWindow('kvShare:notify:day', 500, 24 * 60 * 60_000),
+] as const;
+
 // -- Handler surface -------------------------------------------------
 
 /**
@@ -304,8 +348,11 @@ export const EVENTS_KV_MATCHED_SUBSCRIPTIONS_PER_EVENT = tiered(512, 128, 128);
  */
 export const EVENTS_KV_FILTER_EVALUATIONS_PER_EVENT = tiered(2048, 512, 512);
 
-/** Omit all inline KV values when the matched audience exceeds this count. */
-export const EVENTS_KV_VALUE_OMIT_MATCHED_SUBSCRIPTIONS = 128;
+/**
+ * Deliveries of one key-value change that carry its value inline, in the order
+ * the fan-out serves them. Later ones carry the key alone.
+ */
+export const EVENTS_KV_VALUE_DELIVERIES_PER_EVENT = 128;
 
 /**
  * Largest inline KV value in serialized bytes. Larger values are omitted;
@@ -397,7 +444,9 @@ export const EVENTS_REGION_PENDING_CEILING = 1_000_000;
 // a handler that answers "no" is not. Retrying on a fixed cadence turns one
 // broken deploy into a permanent load on whatever is failing, so the wait
 // doubles per attempt up to a ceiling, and a run of failures stops the
-// subscription rather than retrying it forever.
+// subscription rather than retrying it forever. A run Puter could not start or
+// finish backs off the same way but is not the handler's failure, so it never
+// counts toward that run.
 
 /** Wait before the first retry of a delivery a handler could not take. */
 export const EVENTS_RETRY_BASE_MS = 2_000;
@@ -406,7 +455,7 @@ export const EVENTS_RETRY_BASE_MS = 2_000;
 export const EVENTS_RETRY_MAX_MS = 5 * 60 * 1000;
 
 /**
- * Failures in a row before a subscription is suspended. Counted per
+ * Handler failures in a row before a subscription is suspended. Counted per
  * subscription and reset by the first delivery a handler takes, so an
  * occasional failure never accumulates into one.
  */

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

@@ -49,6 +49,8 @@ type Layers = ConstructorParameters<typeof EventsWorkerDeployer>[0];
 const makeLayers = (owners: Record<string, Owner | null>) => {
     const redis = new MockRedis.Cluster(['redis://localhost:7001']);
     const created: string[] = [];
+    /** Apps whose handler sources were read, once per read. */
+    const sourceReads: string[] = [];
     const layers = {
         config: {
             events: { workerRuntime: true, internalSecret: 'sekret' },
@@ -60,16 +62,20 @@ const makeLayers = (owners: Record<string, Owner | null>) => {
         clients: { redis },
         stores: {
             eventHandler: {
-                allForApp: async (appUid: string) => [
-                    {
-                        appUid,
-                        name: 'h',
-                        source: 'async () => {}',
-                        sourceHash: SOURCE_HASH,
-                        createdAt: 0,
-                        updatedAt: 0,
-                    },
-                ],
+                setForApp: async () => [{ name: 'h', sourceHash: SOURCE_HASH }],
+                allForApp: async (appUid: string) => {
+                    sourceReads.push(appUid);
+                    return [
+                        {
+                            appUid,
+                            name: 'h',
+                            source: 'async () => {}',
+                            sourceHash: SOURCE_HASH,
+                            createdAt: 0,
+                            updatedAt: 0,
+                        },
+                    ];
+                },
             },
             app: {
                 getByUid: async (appUid: string) => {
@@ -104,7 +110,12 @@ const makeLayers = (owners: Record<string, Owner | null>) => {
             },
         },
     };
-    return { layers: layers as unknown as Layers, created, redis };
+    return {
+        layers: layers as unknown as Layers,
+        created,
+        redis,
+        sourceReads,
+    };
 };
 
 describe('EventsWorkerDeployer.ensure', () => {
@@ -127,8 +138,10 @@ describe('EventsWorkerDeployer.ensure', () => {
         expect(b).toBe('no-owner');
     });
 
-    it('refuses once the app has deployed past the hourly cap', async () => {
-        const { layers, redis } = makeLayers({ 'app-c': { ownerUserId: 3 } });
+    it('refuses once the app has deployed past the hourly cap, before reading or building any source', async () => {
+        const { layers, redis, sourceReads, created } = makeLayers({
+            'app-c': { ownerUserId: 3 },
+        });
         const deployer = new EventsWorkerDeployer(layers);
         const hour = new Date().toISOString().slice(0, 13);
         await redis.set(
@@ -137,6 +150,24 @@ describe('EventsWorkerDeployer.ensure', () => {
         );
 
         expect(await deployer.ensure('app-c', SCRIPT)).toBe('throttled');
+        expect(sourceReads).toEqual([]);
+        expect(created).toEqual([]);
+    });
+
+    it('answers a stale script without spending the hourly cap', async () => {
+        const { layers, redis, sourceReads } = makeLayers({
+            'app-e': { ownerUserId: 5 },
+        });
+        const deployer = new EventsWorkerDeployer(layers);
+        const stale = eventsWorkerScript(
+            handlerSetHash([{ name: 'h', sourceHash: 'b'.repeat(64) }]),
+            '',
+        );
+
+        expect(await deployer.ensure('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('deploys normally under the cap', async () => {

src/backend/controllers/events/workerDeploy.ts

@@ -26,10 +26,14 @@ import {
     INTERNAL_ADMISSION_BYPASS,
     INTERNAL_DEPLOY_TARGET,
 } from '../../drivers/workers/WorkerDriver.js';
-import type { EventsInvokeCall } from '../../clients/events/EventsWorkerInvokerClient.js';
+import type {
+    EventsInvokeAnswer,
+    EventsInvokeCall,
+} from '../../clients/events/EventsWorkerInvokerClient.js';
 import {
-    EVENTS_HANDLED_HEADER,
     EVENTS_INVOKE_PATH,
+    answerFrom,
+    failedAnswer,
 } from '../../clients/events/EventsWorkerInvokerClient.js';
 import type { puterServices } from '../../services/index.js';
 import {
@@ -37,7 +41,10 @@ import {
     eventsWorkerScope,
     eventsWorkerScript,
 } from '../../services/events/workerRuntime.js';
-import { generateEventsWorkerSource } from '../../services/events/workerSource.js';
+import {
+    generateEventsWorkerSource,
+    handlerSetHash,
+} from '../../services/events/workerSource.js';
 import type { puterStores } from '../../stores/index.js';
 import type { IConfig, LayerInstances } from '../../types.js';
 import { EVENTS_WORKER_DEPLOYS_PER_HOUR } from './limits.js';
@@ -113,20 +120,24 @@ export class EventsWorkerDeployer {
         script: string,
     ): Promise<EventsDeployOutcome> {
         const { stores, drivers } = this.#layers;
+        const scope = eventsWorkerScope(this.#layers.config);
 
-        const handlers = await stores.eventHandler.allForApp(appUid);
-        if (handlers.length === 0) return 'no-handlers';
-
-        const generated = generateEventsWorkerSource(handlers);
+        // 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);
+        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(
-                generated.setHash,
-                eventsWorkerScope(this.#layers.config),
-            ) !== script
-        )
+        if (eventsWorkerScript(handlerSetHash(set), scope) !== script)
+            return 'stale';
+
+        if (await this.#tooManyDeploysThisHour(appUid)) return 'throttled';
+
+        const handlers = await stores.eventHandler.allForApp(appUid);
+        const generated = generateEventsWorkerSource(handlers);
+        // The set can move between the two reads.
+        if (eventsWorkerScript(generated.setHash, scope) !== script)
             return 'stale';
         if (generated.tooLarge) {
             console.error(
@@ -140,8 +151,6 @@ export class EventsWorkerDeployer {
                 generated.broken.join(', '),
             );
 
-        if (await this.#tooManyDeploysThisHour(appUid)) return 'throttled';
-
         const owner = await this.#owner(appUid);
         if (!owner) return 'no-owner';
 
@@ -289,11 +298,7 @@ export class LocalEventsInvokeTransport {
         this.#deployer = deployer;
     }
 
-    async send(call: EventsInvokeCall): Promise<{
-        status: number | null;
-        handled?: boolean;
-        error?: string;
-    }> {
+    async send(call: EventsInvokeCall): Promise<EventsInvokeAnswer> {
         const request = (): Request =>
             new Request(
                 `http://${call.script}.workers.puter.localhost${EVENTS_INVOKE_PATH}`,
@@ -323,10 +328,7 @@ export class LocalEventsInvokeTransport {
                 return { status: null, error: 'script not resident' };
             return retried;
         } catch (err) {
-            return {
-                status: null,
-                error: err instanceof Error ? err.message : String(err),
-            };
+            return failedAnswer(err);
         }
     }
 
@@ -337,7 +339,7 @@ export class LocalEventsInvokeTransport {
     async #dispatch(
         request: Request,
         timeoutMs: number,
-    ): Promise<{ status: number; handled: boolean } | null> {
+    ): Promise<EventsInvokeAnswer | null> {
         let timer: ReturnType<typeof setTimeout> | undefined;
         const timeout = new Promise<'timeout'>((resolve) => {
             timer = setTimeout(() => resolve('timeout'), timeoutMs);
@@ -348,12 +350,10 @@ export class LocalEventsInvokeTransport {
                 this.#services.localworkerservice.dispatchEventsWorker(request),
                 timeout,
             ]);
-            if (response === 'timeout') throw new Error('invocation timed out');
+            if (response === 'timeout')
+                throw new DOMException('invocation timed out', 'TimeoutError');
             if (response === null) return null;
-            return {
-                status: response.status,
-                handled: response.headers.get(EVENTS_HANDLED_HEADER) === '1',
-            };
+            return answerFrom(response);
         } finally {
             clearTimeout(timer);
         }

src/backend/controllers/fs/FSController.recursiveOffset.http.test.ts

@@ -0,0 +1,80 @@
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+import { setupPuterTestEnv, type PuterTestEnv } from '../../testUtil.js';
+
+describe('recursive readdir with offset', () => {
+    let env: PuterTestEnv;
+
+    beforeAll(async () => {
+        env = await setupPuterTestEnv();
+    }, 120_000);
+
+    afterAll(async () => {
+        await env?.shutdown();
+    });
+
+    const post = async (path: string, token: string, body: unknown) =>
+        fetch(new URL(path, env.apiOrigin), {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                Authorization: `Bearer ${token}`,
+            },
+            body: JSON.stringify(body),
+        });
+
+    it('skips entries before applying the recursive page limit', async () => {
+        const { username, token } = env.users.user;
+        const base = `/${username}/Documents/rec-offset`;
+        for (const path of [base, `${base}/a`, `${base}/b`, `${base}/c`]) {
+            expect((await post('/fs/mkdir', token, { path })).status).toBe(200);
+        }
+
+        const list = async (body: Record<string, unknown>) => {
+            const response = await post('/fs/readdir', token, {
+                path: base,
+                recursive: true,
+                ...body,
+            });
+            expect(response.status).toBe(200);
+            const page = (await response.json()) as {
+                items: Array<{ name: string }>;
+            };
+            return page.items.map((item) => item.name);
+        };
+
+        expect(await list({ limit: 3 })).toEqual(['a', 'b', 'c']);
+        // Non-recursive honours offset.
+        const flat = await post('/fs/readdir', token, {
+            path: base,
+            limit: 1,
+            offset: 2,
+        });
+        expect(
+            ((await flat.json()) as Array<{ name: string }>).map((e) => e.name),
+        ).toEqual(['c']);
+        expect(await list({ limit: 1, offset: 2 })).toEqual(['c']);
+        expect(await list({ offset: 2 })).toEqual(['c']);
+        expect(await list({ offset: 20 })).toEqual([]);
+        expect(await list({ limit: 1, offset: 1, sortOrder: 'desc' })).toEqual([
+            'b',
+        ]);
+        const first = await post('/fs/readdir', token, {
+            path: base,
+            recursive: true,
+            limit: 1,
+            offset: 1,
+        });
+        const page = await first.json();
+        expect(page.items.map((item: { name: string }) => item.name)).toEqual([
+            'b',
+        ]);
+        expect(page.cursor).toBeTypeOf('string');
+        expect(await list({ limit: 1, cursor: page.cursor })).toEqual(['c']);
+        // A cursor wins over offset, and an invalid offset is ignored, as
+        // recursive listings did before they honoured offset.
+        expect(
+            await list({ limit: 1, cursor: page.cursor, offset: 1 }),
+        ).toEqual(['c']);
+        expect(await list({ limit: 1, offset: -1 })).toEqual(['a']);
+    });
+});

src/backend/controllers/fs/FSController.ts

@@ -1335,6 +1335,7 @@ export class FSController extends PuterController {
                 parent.path,
                 {
                     limit,
+                    offset,
                     cursor:
                         typeof body.cursor === 'string'
                             ? body.cursor

src/backend/controllers/fs/LegacyFSController.appAcl.http.test.ts

@@ -0,0 +1,114 @@
+import { v4 as uuidv4 } from 'uuid';
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+import { makeActor } from '../../core/actor.js';
+import { setupPuterTestEnv, type PuterTestEnv } from '../../testUtil.js';
+
+describe('/auth/check-app-acl', () => {
+    let env: PuterTestEnv;
+    beforeAll(async () => {
+        env = await setupPuterTestEnv();
+    }, 120_000);
+    afterAll(async () => {
+        await env?.shutdown();
+    });
+
+    const post = (path: string, body: unknown, token: string) =>
+        fetch(new URL(path, env.apiOrigin), {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                Authorization: `Bearer ${token}`,
+            },
+            body: JSON.stringify(body),
+        });
+
+    const makeDirAndApp = async () => {
+        const { username, token } = env.users.user;
+        const server = env.server;
+        const user = (await server.stores.user.getByUsername(username))!;
+        const path = `/${username}/Documents/cacl-${uuidv4()}`;
+        expect((await post('/fs/mkdir', { path }, token)).status).toBe(200);
+        const entry = (await server.stores.fsEntry.getEntryByPath(path))!;
+
+        const app = await (
+            server.stores.app.create as unknown as (
+                f: Record<string, unknown>,
+                o: { ownerUserId: number },
+            ) => Promise<{ uid: string; id: number }>
+        )(
+            {
+                name: `cacl-${uuidv4()}`,
+                title: 'Check app acl',
+                index_url: `https://cacl-${uuidv4()}.test/`,
+            },
+            { ownerUserId: user.id },
+        );
+        return { user, path, entry, app };
+    };
+
+    it('allows a granted file without poisoning the app permission cache', async () => {
+        const { token } = env.users.user;
+        const server = env.server;
+        const { user, path, entry, app } = await makeDirAndApp();
+
+        const grant = await post(
+            '/auth/grant-user-app',
+            { app_uid: app.uid, permission: `fs:${entry.uuid}:read` },
+            token,
+        );
+        expect(grant.status).toBe(200);
+
+        const res = await post(
+            '/auth/check-app-acl',
+            { subject: { path }, app: app.uid, mode: 'read' },
+            token,
+        );
+        expect(res.status).toBe(200);
+        expect(await res.json()).toEqual({ allowed: true });
+
+        const asApp = makeActor({ user, app: { uid: app.uid, id: app.id } });
+        const descriptor = () => server.services.acl.fsDescriptor(path);
+        expect(
+            await server.services.acl.check(asApp, descriptor(), 'read'),
+        ).toBe(true);
+    });
+
+    it('denies an app with no grant', async () => {
+        const { path, app } = await makeDirAndApp();
+        const res = await post(
+            '/auth/check-app-acl',
+            { subject: { path }, app: app.uid, mode: 'read' },
+            env.users.user.token,
+        );
+        expect(res.status).toBe(200);
+        expect(await res.json()).toEqual({ allowed: false });
+    });
+
+    it('refuses app and access tokens', async () => {
+        const { token, apiToken } = env.users.user;
+        const { path, entry, app } = await makeDirAndApp();
+        const grant = await post(
+            '/auth/grant-user-app',
+            { app_uid: app.uid, permission: `fs:${entry.uuid}:read` },
+            token,
+        );
+        expect(grant.status).toBe(200);
+
+        const minted = await post(
+            '/auth/get-user-app-token',
+            { app_uid: app.uid },
+            token,
+        );
+        expect(minted.status).toBe(200);
+        const appToken = ((await minted.json()) as { token: string }).token;
+
+        for (const credential of [appToken, apiToken]) {
+            const res = await post(
+                '/auth/check-app-acl',
+                { subject: { path }, app: app.uid, mode: 'read' },
+                credential,
+            );
+            expect(res.status).toBe(403);
+        }
+    });
+});

src/backend/controllers/fs/LegacyFSController.copyAndListing.http.test.ts

@@ -0,0 +1,204 @@
+/*
+ * 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/>.
+ */
+
+import { randomUUID } from 'node:crypto';
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+import { setupPuterTestEnv, type PuterTestEnv } from '../../testUtil.js';
+
+let env: PuterTestEnv;
+
+beforeAll(async () => {
+    env = await setupPuterTestEnv();
+}, 120_000);
+
+afterAll(async () => {
+    await env?.shutdown();
+});
+
+const post = (path: string, body: unknown) =>
+    fetch(new URL(path, env.apiOrigin), {
+        method: 'POST',
+        headers: {
+            'Content-Type': 'application/json',
+            Authorization: `Bearer ${env.users.user.token}`,
+        },
+        body: JSON.stringify(body),
+    });
+
+const write = (path: string, content: string) =>
+    post('/fs/write', {
+        fileMetadata: { path, size: content.length, contentType: 'text/plain' },
+        fileContent: content,
+    });
+
+const read = async (path: string) => {
+    const url = new URL('/read', env.apiOrigin);
+    url.searchParams.set('file', path);
+    const response = await fetch(url, {
+        headers: { Authorization: `Bearer ${env.users.user.token}` },
+    });
+    return response.text();
+};
+
+const makeDir = async (name: string) => {
+    const path = `/${env.users.user.username}/Documents/${name}-${randomUUID().slice(0, 8)}`;
+    expect((await post('/fs/mkdir', { path })).status).toBe(200);
+    return path;
+};
+
+describe('legacy /copy onto an existing file', () => {
+    it('replaces the file with overwrite', async () => {
+        const dir = await makeDir('copy-onto');
+        expect((await write(`${dir}/a.txt`, 'aaa')).status).toBe(200);
+        expect((await write(`${dir}/b.txt`, 'bbbbbb')).status).toBe(200);
+
+        const copy = await post('/copy', {
+            source: `${dir}/a.txt`,
+            destination: `${dir}/b.txt`,
+            overwrite: true,
+        });
+        expect(copy.status).toBe(200);
+        const [result] = (await copy.json()) as Array<{
+            copied: { name: string; path: string };
+            overwritten?: { name: string };
+        }>;
+        expect(result!.copied.name).toBe('b.txt');
+        expect(result!.overwritten?.name).toBe('b.txt');
+        expect(await read(`${dir}/b.txt`)).toBe('aaa');
+        expect(await read(`${dir}/a.txt`)).toBe('aaa');
+    });
+
+    it('refuses without overwrite and leaves the file alone', async () => {
+        const dir = await makeDir('copy-onto-refused');
+        await write(`${dir}/a.txt`, 'aaa');
+        await write(`${dir}/b.txt`, 'bbbbbb');
+
+        const copy = await post('/copy', {
+            source: `${dir}/a.txt`,
+            destination: `${dir}/b.txt`,
+        });
+        expect(copy.status).toBe(409);
+        expect(((await copy.json()) as { code: string }).code).toBe(
+            'item_with_same_name_exists',
+        );
+        expect(await read(`${dir}/b.txt`)).toBe('bbbbbb');
+    });
+
+    it('still copies into a directory destination under the same name', async () => {
+        const dir = await makeDir('copy-into');
+        await write(`${dir}/a.txt`, 'aaa');
+        expect((await post('/fs/mkdir', { path: `${dir}/sub` })).status).toBe(
+            200,
+        );
+
+        const copy = await post('/copy', {
+            source: `${dir}/a.txt`,
+            destination: `${dir}/sub`,
+        });
+        expect(copy.status).toBe(200);
+        expect(await read(`${dir}/sub/a.txt`)).toBe('aaa');
+    });
+
+    it('refuses to overwrite a file with itself', async () => {
+        const dir = await makeDir('copy-self');
+        await write(`${dir}/a.txt`, 'aaa');
+
+        for (const destination of [`${dir}/a.txt`, dir]) {
+            const copy = await post('/copy', {
+                source: `${dir}/a.txt`,
+                destination,
+                overwrite: true,
+            });
+            expect(copy.status).toBe(400);
+        }
+        expect(await read(`${dir}/a.txt`)).toBe('aaa');
+    });
+});
+
+describe('signed folder listing', () => {
+    const signedListing = async (path: string) => {
+        const signed = await post('/sign', {
+            items: [{ path, action: 'read' }],
+        });
+        expect(signed.status).toBe(200);
+        const readUrl = new URL(
+            (await signed.json()).signatures[0].read_url as string,
+        );
+        return fetch(
+            new URL(`${readUrl.pathname}${readUrl.search}`, env.apiOrigin),
+        );
+    };
+
+    it('lists every child of a folder larger than one query', async () => {
+        const dir = await makeDir('big');
+        const parent = (await env.server.stores.fsEntry.getEntryByPath(dir))!;
+        const total = 10_050;
+        const now = Math.floor(Date.now() / 1000);
+        for (let start = 0; start < total; start += 500) {
+            const rows: unknown[][] = [];
+            for (let i = start; i < Math.min(total, start + 500); i++) {
+                const name = `f${String(i).padStart(5, '0')}.txt`;
+                rows.push([
+                    randomUUID(),
+                    parent.userId,
+                    parent.id,
+                    parent.uuid,
+                    name,
+                    `${dir}/${name}`,
+                    0,
+                    now,
+                    now,
+                    now,
+                    0,
+                ]);
+            }
+            await env.server.clients.db.write(
+                `INSERT INTO fsentries (uuid, user_id, parent_id, parent_uid, name, path, is_dir, modified, created, accessed, size) VALUES ${rows.map(() => '(?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)').join(', ')}`,
+                rows.flat(),
+            );
+        }
+
+        const response = await signedListing(dir);
+        expect(response.status).toBe(200);
+        expect(response.headers.get('content-type')).toMatch(
+            /^application\/json/,
+        );
+        const children = (await response.json()) as Array<{
+            fsentry_name: string;
+            write_url?: string;
+        }>;
+        expect(children).toHaveLength(total);
+        expect(children[0]!.fsentry_name).toBe('f00000.txt');
+        expect(children.at(-1)!.fsentry_name).toBe('f10049.txt');
+        expect(new Set(children.map((c) => c.fsentry_name)).size).toBe(total);
+        expect(children.some((c) => c.write_url)).toBe(false);
+    }, 120_000);
+
+    it('answers a small folder in one body', async () => {
+        const dir = await makeDir('small');
+        await write(`${dir}/one.txt`, '1');
+        const response = await signedListing(dir);
+        expect(response.status).toBe(200);
+        expect(response.headers.get('content-length')).not.toBeNull();
+        const children = (await response.json()) as Array<{
+            fsentry_name: string;
+        }>;
+        expect(children.map((c) => c.fsentry_name)).toEqual(['one.txt']);
+    });
+});

src/backend/controllers/fs/LegacyFSController.http.test.ts

@@ -153,6 +153,34 @@ describe('legacy file downloads over HTTP', () => {
         },
     );
 
+    it.each(routes)(
+        'GET %s answers a ranged read of an empty file with an empty 200',
+        async (route) => {
+            const file = await writeFile(
+                `empty-${route.replace(/\W/g, '')}.bin`,
+                Buffer.alloc(0),
+            );
+            const ranged = await requestFor(route, file, {
+                headers: { Range: 'bytes=0-511' },
+            });
+            expect(ranged.status).toBe(200);
+            expect(await ranged.text()).toBe('');
+        },
+    );
+
+    it('GET /read answers byte_count on an empty file with an empty 200', async () => {
+        const file = await writeFile('empty-byte-count.bin', Buffer.alloc(0));
+        for (const query of ['byte_count=512', 'offset=0']) {
+            const url = new URL(`/read?${query}`, env.apiOrigin);
+            url.searchParams.set('file', file.path);
+            const response = await fetch(url, {
+                headers: { Authorization: `Bearer ${env.users.user.token}` },
+            });
+            expect(response.status).toBe(200);
+            expect(await response.text()).toBe('');
+        }
+    });
+
     // Storage hands over one chunk and then goes quiet, as a large object
     // does while the client is still reading.
     const stallReadsOf = (objectKey: string) => {

src/backend/controllers/fs/LegacyFSController.launchIcons.test.ts

@@ -0,0 +1,160 @@
+import type { Request, RequestHandler, Response } from 'express';
+import { v4 as uuidv4 } from 'uuid';
+import { afterAll, beforeAll, describe, expect, it, vi } from 'vitest';
+import type { Actor } from '../../core/actor.js';
+import { runWithContext } from '../../core/context.js';
+import { PuterRouter } from '../../core/http/PuterRouter.js';
+import { PuterServer } from '../../server.js';
+import { setupTestServer } from '../../testUtil.js';
+import type { LegacyFSController } from './LegacyFSController.js';
+
+const PNG_2X2 =
+    'iVBORw0KGgoAAAANSUhEUgAAAAIAAAACCAYAAABytg0kAAAACXBIWXMAAAPoAAAD6AG1e1JrAAAAEUlEQVR4nGP4z8DwH4QZYAwAR8oH+WdZbrcAAAAASUVORK5CYII=';
+
+let server: PuterServer;
+let handler: RequestHandler;
+type Driver = {
+    create: (a: Record<string, unknown>) => Promise<Record<string, unknown>>;
+};
+
+beforeAll(async () => {
+    server = await setupTestServer({
+        api_base_url: 'http://api.test.local',
+        static_hosting_domain: 'site.test',
+    } as unknown as Parameters<typeof setupTestServer>[0]);
+    await server.services.appIcon.ensureIconsDirectory();
+    const controller = server.controllers
+        .legacyFs as unknown as LegacyFSController;
+    const router = new PuterRouter();
+    controller.registerRoutes(router);
+    handler = router.routes.find(
+        (r) =>
+            r.path === '/get-launch-apps' &&
+            String(r.method).toLowerCase() === 'get',
+    )!.handler as RequestHandler;
+}, 60_000);
+
+afterAll(async () => {
+    await server?.shutdown();
+});
+
+const makeActor = async (): Promise<{ actor: Actor; id: number }> => {
+    const username = `v13-${Math.random().toString(36).slice(2, 10)}`;
+    const u = await server.stores.user.create({
+        username,
+        uuid: uuidv4(),
+        password: null,
+        email: `${username}@test.local`,
+        free_storage: 100 * 1024 * 1024,
+        requires_email_confirmation: false,
+    });
+    const r = (await server.stores.user.getById(u.id))!;
+    return {
+        id: r.id,
+        actor: {
+            user: {
+                id: r.id,
+                uuid: r.uuid,
+                username: r.username,
+                email: r.email ?? null,
+                email_confirmed: true,
+            },
+        } as unknown as Actor,
+    };
+};
+
+const createViaDriver = async (actor: Actor, icon: string) =>
+    runWithContext({ actor }, () =>
+        (server.drivers.apps as unknown as Driver).create({
+            object: {
+                name: `v13-${Math.random().toString(36).slice(2, 10)}`,
+                title: 'V',
+                index_url: `https://v13-${Math.random().toString(36).slice(2, 10)}.test/`,
+                icon,
+            },
+        }),
+    );
+
+const launchApps = async (actor: Actor, appUid: string, userId: number) => {
+    await server.clients.db.write(
+        'INSERT INTO `app_opens` (`app_uid`, `user_id`, `ts`) VALUES (?, ?, ?)',
+        [appUid, userId, Math.floor(Date.now() / 1000)],
+    );
+    let body: { recent: Array<Record<string, unknown>> } | undefined;
+    const res = {
+        json: (v: unknown) => {
+            body = v as typeof body;
+            return res;
+        },
+        status: () => res,
+        setHeader: () => res,
+    } as unknown as Response;
+    await handler(
+        {
+            query: { icon_size: '64' },
+            headers: {},
+            body: {},
+            actor,
+        } as unknown as Request,
+        res,
+        () => {},
+    );
+    return body!.recent.find((e) => e.uuid === appUid)!;
+};
+
+describe('/get-launch-apps recent icon, verified', () => {
+    it('a valid data-URL icon written through the driver is migrated to a short URL', async () => {
+        const { actor, id } = await makeActor();
+        const app = await createViaDriver(
+            actor,
+            `data:image/png;base64,${PNG_2X2}`,
+        );
+        await vi.waitFor(
+            async () => {
+                const row = await server.stores.app.getByUid(app.uid as string);
+                expect(String(row?.icon).slice(0, 80)).toMatch(
+                    /^https?:\/\/.*\/app-icon\/app-/,
+                );
+            },
+            { timeout: 10_000 },
+        );
+        const entry = await launchApps(actor, app.uid as string, id);
+        expect(String(entry.icon).length).toBeLessThan(200);
+        expect(entry.iconCdnUrl).toMatch(/-64\.png$/);
+    }, 30_000);
+
+    it('returns an icon endpoint when migration cannot decode the stored icon', async () => {
+        const { actor, id } = await makeActor();
+        // PNG signature passes the write-path sniff; sharp rejects the rest.
+        const corrupt = Buffer.concat([
+            Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]),
+            Buffer.alloc(1024 * 1024, 0x41),
+        ]).toString('base64');
+        const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+        let app: Record<string, unknown>;
+        try {
+            app = await createViaDriver(
+                actor,
+                `data:image/png;base64,${corrupt}`,
+            );
+            // Give the background pipeline time to try and fail.
+            await vi.waitFor(
+                () =>
+                    expect(
+                        warn.mock.calls.some(
+                            ([m]) => m === '[app-icon] icon processing failed',
+                        ),
+                    ).toBe(true),
+                { timeout: 10_000 },
+            );
+        } finally {
+            warn.mockRestore();
+        }
+        const row = await server.stores.app.getByUid(app!.uid as string);
+        expect(String(row?.icon).startsWith('data:image/png')).toBe(true);
+        const entry = await launchApps(actor, app!.uid as string, id);
+        expect(entry.icon).toBe(
+            `http://api.test.local/app-icon/${app!.uid}/64`,
+        );
+    }, 30_000);
+});

src/backend/controllers/fs/LegacyFSController.test.ts

@@ -5293,4 +5293,39 @@ describe('LegacyFSController GET /get-launch-apps', () => {
 
         expect(returned).toEqual(recentUids);
     });
+
+    it('skips the recent opens for recent=0 and keeps recommended', async () => {
+        const { actor, userId } = await makeUser();
+        const app = await makeHostedApp(userId, 'unregistered-skip');
+        await recordOpen(userId, app.uid);
+
+        const call = async (query: Record<string, unknown>) => {
+            const { res, captured } = makeRes();
+            await withActor(actor, async () => {
+                await getLaunchAppsHandler()(
+                    makeReq({ actor, query }),
+                    res,
+                    () => {
+                        throw new Error('handler called next() unexpectedly');
+                    },
+                );
+            });
+            return captured.body as {
+                recommended: unknown[];
+                recent: unknown[];
+            };
+        };
+        const full = await call({});
+        expect(full.recent.length).toBeGreaterThan(0);
+
+        const opens = vi.spyOn(server.stores.app, 'getRecentAppOpens');
+        try {
+            const skipped = await call({ recent: '0' });
+            expect(skipped.recent).toEqual([]);
+            expect(skipped.recommended).toEqual(full.recommended);
+            expect(opens).not.toHaveBeenCalled();
+        } finally {
+            opens.mockRestore();
+        }
+    });
 });

src/backend/controllers/fs/LegacyFSController.ts

@@ -26,6 +26,7 @@ import {
     assertResolvedActor,
     isAccessTokenActor,
     isAppActor,
+    isPlainUserActor,
     makeActor,
 } from '../../core/actor.js';
 import { Context } from '../../core/context.js';
@@ -95,6 +96,7 @@ import {
     assertAccess,
     assertCanCreate,
     assertCanMoveInto,
+    contextBoundStream,
     emitGuiItemEvent,
     expandClientPath,
     findOverwriteTarget,
@@ -102,6 +104,7 @@ import {
     getString,
     type GuiItemEventName,
     loadLegacyAssociatedApps,
+    rangeForEntry,
     replacedByMove,
     resolveReadRange,
     resolveV1Selector,
@@ -381,7 +384,9 @@ export class LegacyFSController extends PuterController {
 
                 let recent: unknown[] = [];
                 const userId = req.actor?.user?.id;
-                if (userId) {
+                // `recent=0`: a caller that only shows `recommended`.
+                const wantsRecent = req.query.recent !== '0';
+                if (userId && wantsRecent) {
                     const recentUids = await this.stores.app.getRecentAppOpens(
                         userId,
                         { limit: 10 },
@@ -418,9 +423,9 @@ export class LegacyFSController extends PuterController {
                         return {
                             ...toAppSummary(app, {
                                 config: this.config,
+                                apiBaseUrl: this.config.api_base_url,
                                 iconSize,
                             }),
-                            icon: app.icon ?? null,
                             index_url: backingGone ? null : app.index_url,
                             ...(backingGone
                                 ? { privateAccess: buildHostedBackingDenial() }
@@ -801,10 +806,23 @@ export class LegacyFSController extends PuterController {
             this.stores.fsEntry,
             body.source,
         );
-        const destinationParent = await resolveV1Selector(
+        const destination = await resolveV1Selector(
             this.stores.fsEntry,
             body.destination,
         );
+        // A file destination names the copy itself, replaced only with
+        // `overwrite`.
+        let newName = getString(body, 'new_name');
+        let destinationParent = destination;
+        if (!destination.isDir && !newName && destination.parentUid) {
+            const parent = await this.stores.fsEntry.getEntryByUuid(
+                destination.parentUid,
+            );
+            if (parent) {
+                destinationParent = parent;
+                newName = destination.name;
+            }
+        }
 
         await assertAccess(
             this.services.acl,
@@ -829,14 +847,14 @@ export class LegacyFSController extends PuterController {
             ? await findOverwriteTarget(
                   this.stores.fsEntry,
                   destinationParent,
-                  getString(body, 'new_name') ?? source.name,
+                  newName ?? source.name,
               )
             : null;
 
         const copy = await this.services.fs.copy(userId, {
             source,
             destinationParent,
-            newName: getString(body, 'new_name'),
+            newName,
             overwrite: overwriteRequested,
             dedupeName: getBoolean(body, 'dedupe_name', 'change_name') ?? false,
         });
@@ -1289,7 +1307,10 @@ export class LegacyFSController extends PuterController {
             });
         }
 
-        const range = resolveReadRange(req.headers.range, query);
+        const range = rangeForEntry(
+            entry,
+            resolveReadRange(req.headers.range, query),
+        );
         const download = await this.services.fs.readContent(entry, {
             range,
         });
@@ -1790,19 +1811,50 @@ export class LegacyFSController extends PuterController {
         // owner, so the layout it reveals is theirs to reveal, and the child
         // signatures expire; the paths are the only part that outlives them.
         if (entry.isDir) {
-            const children = await this.services.fs.listDirectory(entry.uuid);
-            const signedChildren = children.map((child) => {
+            const signChild = (child: FSEntry) => {
                 const { write_url: _, ...rest } = signEntry(child, signingCfg, {
                     ttlSeconds: NON_OWNER_SIGNATURE_TTL_SECONDS,
                 });
                 return { ...rest, path: maskEntryPath(child) };
-            });
-            res.json(signedChildren);
+            };
+            const pages = this.services.fs.listDirectoryPages(entry.uuid);
+            const first = await pages.next();
+            const firstPage = first.done ? [] : first.value;
+            const second = await pages.next();
+            if (second.done) {
+                res.json(firstPage.map(signChild));
+                return;
+            }
+
+            // Past one page the listing streams, so a large folder isn't held
+            // in memory whole. A failure partway cuts the response off.
+            const secondPage = second.value;
+            const serialize = (child: FSEntry) =>
+                JSON.stringify(signChild(child));
+            async function* allPages() {
+                yield firstPage;
+                yield secondPage;
+                yield* pages;
+            }
+            async function* body() {
+                let separator = '[';
+                for await (const page of allPages()) {
+                    if (page.length === 0) continue;
+                    yield separator + page.map(serialize).join(',');
+                    separator = ',';
+                }
+                yield separator === '[' ? '[]' : ']';
+            }
+            res.type('application/json');
+            await pipeToResponse(contextBoundStream(body()), res);
             return;
         }
 
         // File: stream bytes with Range support.
-        const range = resolveReadRange(req.headers.range, query);
+        const range = rangeForEntry(
+            entry,
+            resolveReadRange(req.headers.range, query),
+        );
         const download = await this.services.fs.readContent(entry, {
             range,
         });
@@ -1992,6 +2044,11 @@ export class LegacyFSController extends PuterController {
      */
     checkAppAcl = async (req: Request, res: Response): Promise<void> => {
         const actor = this.#requireActor(req);
+        // Sessions only: for an app, this would be a window onto its neighbours' grants.
+        if (!isPlainUserActor(actor))
+            throw new HttpError(403, 'actor must be a user', {
+                legacyCode: 'forbidden',
+            });
         const body = asRecord(req.body);
 
         const subjectRef = body.subject;
@@ -2022,7 +2079,7 @@ export class LegacyFSController extends PuterController {
                 legacyCode: 'subject_does_not_exist',
             });
 
-        let app: { uid: string } | null = null;
+        let app: { uid: string; id: number } | null = null;
         if (typeof appRef === 'string') {
             app =
                 (await this.stores.app.getByUid(appRef)) ??
@@ -2036,7 +2093,7 @@ export class LegacyFSController extends PuterController {
         // Build an actor-under-user shape for the check.
         const actorForApp = makeActor({
             user: actor.user,
-            app: { uid: (app as { uid: string }).uid },
+            app: { uid: app.uid, id: app.id },
         });
         const allowed = await acl.check(actorForApp, descriptor, mode);
         res.json({ allowed });
@@ -2084,10 +2141,12 @@ export class LegacyFSController extends PuterController {
         // by default, so opt in by naming the downloader as who pays.
         req.egressActor = actor;
 
-        const range =
+        const range = rangeForEntry(
+            entry,
             typeof req.headers.range === 'string'
                 ? req.headers.range
-                : undefined;
+                : undefined,
+        );
         const download = await this.services.fs.readContent(entry, {
             range,
         });

src/backend/controllers/fs/legacyFsHelpers.test.ts

@@ -17,15 +17,19 @@
  * along with this program.  If not, see <https://www.gnu.org/licenses/>.
  */
 
+import { Writable } from 'node:stream';
 import { afterAll, beforeAll, describe, expect, it, vi } from 'vitest';
+import { Context, runWithContext } from '../../core/context.js';
 import type { PuterServer } from '../../server.js';
 import { createTestUser, setupTestServer } from '../../testUtil.js';
 import {
     asRecord,
+    contextBoundStream,
     fsEntryMimeType,
     getBoolean,
     getString,
     loadLegacyAssociatedApps,
+    rangeForEntry,
     resolveReadRange,
     signEntry,
     signEntryThumbnail,
@@ -705,3 +709,50 @@ describe('resolveReadRange', () => {
         ).toThrow('Invalid byte_count');
     });
 });
+
+describe('rangeForEntry', () => {
+    it('drops the range for an empty file only', () => {
+        const entry = (size: number) => ({ size }) as FSEntry;
+        expect(rangeForEntry(entry(0), 'bytes=0-511')).toBeUndefined();
+        expect(rangeForEntry(entry(10), 'bytes=0-4')).toBe('bytes=0-4');
+    });
+});
+
+describe('contextBoundStream', () => {
+    it("reads every chunk in the caller's context", async () => {
+        // A sink slower than the source that completes writes from outside
+        // any request, so later chunks are asked for from its drain.
+        const pending: Array<() => void> = [];
+        const flush = runWithContext({}, () =>
+            setInterval(() => pending.splice(0).forEach((done) => done()), 5),
+        );
+        const sink = new Writable({
+            highWaterMark: 1,
+            write(_chunk, _encoding, done) {
+                pending.push(done);
+            },
+        });
+        const seen: unknown[] = [];
+        try {
+            await runWithContext({ actor: 'caller' as never }, async () => {
+                async function* chunks() {
+                    for (let i = 0; i < 40; i++) {
+                        await new Promise((resolve) => setTimeout(resolve, 1));
+                        seen.push(Context.get('actor'));
+                        yield 'x';
+                    }
+                }
+                await new Promise((resolve, reject) => {
+                    contextBoundStream(chunks())
+                        .pipe(sink)
+                        .on('finish', resolve)
+                        .on('error', reject);
+                });
+            });
+        } finally {
+            clearInterval(flush);
+        }
+        expect(seen).toHaveLength(40);
+        expect(seen.every((actor) => actor === 'caller')).toBe(true);
+    });
+});

src/backend/controllers/fs/legacyFsHelpers.ts

@@ -17,7 +17,9 @@
  * along with this program.  If not, see <https://www.gnu.org/licenses/>.
  */
 
+import { AsyncResource } from 'node:async_hooks';
 import { posix as pathPosix } from 'node:path';
+import { Readable } from 'node:stream';
 import { contentType as contentTypeFromMime } from 'mime-types';
 import type { FSEntry } from '../../stores/fs/FSEntry.js';
 import type { FSEntryStore } from '../../stores/fs/FSEntryStore.js';
@@ -150,6 +152,29 @@ export function resolveReadRange(
     return undefined;
 }
 
+/**
+ * A response body read from `chunks` for `pipeToResponse`. Each chunk is pulled
+ * in the caller's async context, which share masking reads, not in whichever
+ * socket event asked for more.
+ */
+export function contextBoundStream(
+    chunks: AsyncGenerator<string, void, undefined>,
+): Readable {
+    const next = AsyncResource.bind(() => chunks.next());
+    const stop = AsyncResource.bind(() => chunks.return(undefined));
+    return Readable.from({
+        [Symbol.asyncIterator]: () => ({ next, return: stop }),
+    });
+}
+
+/** No range is satisfiable on an empty file, so it reads whole: empty, 200. */
+export function rangeForEntry(
+    entry: FSEntry,
+    range: string | undefined,
+): string | undefined {
+    return entry.size === 0 ? undefined : range;
+}
+
 // Accepts either `{ path }` or `{ uid }` or `{ id }` or `{ parent, name }`
 // from a legacy body field. Returns a resolved entry (throwing 404 if not
 // found or 400 if no usable ref is present).

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

@@ -17,6 +17,9 @@
  * along with this program.  If not, see <https://www.gnu.org/licenses/>.
  */
 
+import { mkdir, mkdtemp, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
 import type { Request, RequestHandler, Response } from 'express';
 import { afterAll, beforeAll, describe, expect, it, vi } from 'vitest';
 import { v4 as uuidv4 } from 'uuid';
@@ -466,3 +469,63 @@ describe('HomepageController GET /show/*splat', () => {
         expect(html).toContain('/alice/Documents');
     });
 });
+
+// ── /sw.js ──────────────────────────────────────────────────────────
+
+describe('HomepageController GET /sw.js', () => {
+    const headersOf = (res: Response): Record<string, string> =>
+        Object.fromEntries(
+            (res.set as ReturnType<typeof vi.fn>).mock.calls.map(
+                ([key, value]) => [String(key).toLowerCase(), String(value)],
+            ),
+        );
+
+    it('serves the worker with root scope, as JavaScript, revalidated each time', async () => {
+        const root = await mkdtemp(path.join(tmpdir(), 'puter-sw-route-'));
+        await mkdir(path.join(root, 'dist'));
+        await writeFile(path.join(root, 'dist', 'sw.js'), '// worker\n');
+        const config = server.services.homepage.config as {
+            gui_assets_root?: string;
+            env?: string;
+        };
+        const prev = { root: config.gui_assets_root, env: config.env };
+        config.gui_assets_root = root;
+        config.env = 'prod';
+        const { res, captured } = makeRes();
+        try {
+            await callRoute('get', '/sw.js', makeReq({ path: '/sw.js' }), res);
+        } finally {
+            config.gui_assets_root = prev.root;
+            config.env = prev.env;
+        }
+        expect(captured.statusCode).toBe(200);
+        expect(captured.body).toBe('// worker\n');
+        expect(headersOf(res)).toMatchObject({
+            'content-type': 'text/javascript; charset=utf-8',
+            'cache-control': 'no-cache',
+            'service-worker-allowed': '/',
+        });
+    });
+
+    it('is a 404 when there is no worker to serve', async () => {
+        const config = server.services.homepage.config as {
+            gui_assets_root?: string;
+        };
+        const prev = config.gui_assets_root;
+        config.gui_assets_root = path.join(tmpdir(), 'no-such-gui-root');
+        const { res, captured } = makeRes();
+        try {
+            await callRoute('get', '/sw.js', makeReq({ path: '/sw.js' }), res);
+        } finally {
+            config.gui_assets_root = prev;
+        }
+        expect(captured.statusCode).toBe(404);
+    });
+
+    it('is registered for the root subdomain only', () => {
+        const route = router.routes.find(
+            (r) => r.method === 'get' && r.path === '/sw.js',
+        );
+        expect(route?.options.subdomain).toBe('');
+    });
+});

src/backend/controllers/homepage/HomepageController.ts

@@ -198,6 +198,20 @@ export class HomepageController extends PuterController {
             return sendShell(req, res, {}, launch);
         });
 
+        // -- /sw.js - the service worker, scoped to the whole origin --
+
+        router.get('/sw.js', { subdomain: '' }, async (_req, res) => {
+            const source = await homepage.serviceWorkerSource();
+            if (source === null) {
+                res.status(404).send('Not found');
+                return;
+            }
+            res.set('Content-Type', 'text/javascript; charset=utf-8');
+            res.set('Cache-Control', 'no-cache');
+            res.set('Service-Worker-Allowed', '/');
+            res.send(source);
+        });
+
         // -- Fallback static mount -----------------------------------
         // Serves lingering GUI assets (images, fonts, lib files, etc.)
         // out of <gui_assets_root>/src. Falls through to the 404 handler

src/backend/controllers/hosting/HostingController.test.js

@@ -198,7 +198,7 @@ describe('HostingController /delete-site', () => {
             );
             expect(emitSpy).toHaveBeenCalledWith(
                 'subdomain.delete',
-                { subdomain: site.subdomain, uid: String(site.uuid) },
+                { subdomain: site.subdomain, uid: String(site.uuid), userId },
                 {},
             );
         } finally {

src/backend/controllers/kvShare/KvShareController.http.test.ts

@@ -42,6 +42,7 @@ import {
     EVENTS_KV_HANDLES_PER_USER,
     KV_SHARE_BATCH_MAX,
     KV_SHARE_GRANT_LIMITS,
+    KV_SHARE_LOOKUP_LIMIT,
 } from '../events/limits.js';
 
 const BOOT_TIMEOUT_MS = 120_000;
@@ -67,6 +68,7 @@ const resetBudgets = async (env: PuterTestEnv) => {
         const user = await env.server.stores.user.getByUsername(name);
         for (const scope of [
             EVENTS_KV_HANDLE_LIMIT.scope,
+            KV_SHARE_LOOKUP_LIMIT.scope,
             ...KV_SHARE_GRANT_LIMITS.map((window) => window.scope),
         ])
             await env.server.clients.redis.del(`rate:${scope}:${user!.id}`);
@@ -123,6 +125,7 @@ describe('/kv/shares', () => {
                 'handle',
                 'holder',
                 'label',
+                'notify',
                 'prefix',
             ].sort(),
         );
@@ -131,6 +134,42 @@ describe('/kv/shares', () => {
             appUid: null,
             holder: env.users.other.username,
             label: 'Groceries',
+            notify: false,
+        });
+    });
+
+    it('takes notify, keeps it on a re-share that leaves it out, and shows it to both sides', async () => {
+        const prefix = `notify-${uuidv4().slice(0, 8)}:`;
+        const on = await shareWithOther({ prefix, notify: true });
+        expect(on).toMatchObject({ prefix, notify: true });
+
+        const kept = await shareWithOther({ prefix, access: 'write' });
+        expect(kept).toMatchObject({ handle: on.handle, notify: true });
+
+        const listed = async (path: string, token: string) =>
+            (
+                (await (await req('GET', path, token)).json()) as {
+                    items: Array<Record<string, unknown>>;
+                }
+            ).items.find((row) => row.handle === on.handle);
+        expect(
+            await listed('/kv/shares?limit=200', env.users.user.token),
+        ).toMatchObject({ notify: true });
+        expect(
+            await listed('/kv/shares/with-me?limit=200', env.users.other.token),
+        ).toMatchObject({ notify: true });
+
+        const off = await shareWithOther({ prefix, notify: false });
+        expect(off).toMatchObject({ handle: on.handle, notify: false });
+
+        const refused = await req('POST', '/kv/shares', env.users.user.token, {
+            prefix,
+            recipient: env.users.other.username,
+            notify: 'yes',
+        });
+        expect(refused.status).toBe(400);
+        await expect(refused.json()).resolves.toMatchObject({
+            code: 'kv_share_notify_invalid',
         });
     });
 
@@ -169,6 +208,7 @@ describe('/kv/shares', () => {
             appUid: null,
             holder: env.users.other.username,
             label: 'Trip',
+            notify: false,
             createdAt: shared.createdAt,
             revokedAt: null,
             revokedBy: null,
@@ -190,6 +230,7 @@ describe('/kv/shares', () => {
             access: 'write',
             appUid: null,
             label: 'Trip',
+            notify: false,
             createdAt: shared.createdAt,
         });
         expect(withMeText).not.toContain(env.users.user.username);
@@ -622,6 +663,162 @@ describe('/kv/shares', () => {
             }
         });
     });
+
+    describe('sharing again', () => {
+        let ownerId: number;
+        let third: string;
+
+        beforeAll(async () => {
+            third = `kv-again-${uuidv4().slice(0, 8)}`;
+            await createTestUser(env.server, {
+                username: third,
+                password: 'pw-test-1234',
+            });
+            ownerId = (await env.server.stores.user.getByUsername(
+                env.users.user.username,
+            ))!.id!;
+        });
+
+        const shareAt = (prefix: string, body: Record<string, unknown>) =>
+            req('POST', '/kv/shares', env.users.user.token, {
+                prefix,
+                ...body,
+            });
+
+        /** Leaves `left` units in one of the owner's windows. */
+        const drain = (
+            window: { scope: string; limit: number; window: number },
+            left = 0,
+        ) =>
+            claimRateLimit(
+                `${window.scope}:${ownerId}`,
+                window.limit,
+                window.window,
+                window.limit - left,
+            );
+
+        it('spends neither the mint nor the grant budget when every share stays as it is', async () => {
+            const prefix = `again-${uuidv4().slice(0, 8)}:`;
+            const recipients = [env.users.other.username, third];
+            const made = (await (
+                await shareAt(prefix, { recipients, label: 'Room' })
+            ).json()) as { items: Array<{ handle: string }> };
+            await drain(EVENTS_KV_HANDLE_LIMIT);
+            for (const window of KV_SHARE_GRANT_LIMITS) await drain(window);
+            try {
+                const again = await shareAt(prefix, {
+                    recipients: [...recipients, third],
+                });
+                expect(again.status).toBe(200);
+                const { items } = (await again.json()) as {
+                    items: Array<{ handle: string; label: string }>;
+                };
+                expect(items.map((item) => item.handle)).toEqual([
+                    made.items[0].handle,
+                    made.items[1].handle,
+                    made.items[1].handle,
+                ]);
+                expect(items[0].label).toBe('Room');
+
+                const single = await shareAt(prefix, {
+                    recipient: env.users.other.username,
+                    access: 'read',
+                });
+                expect(single.status).toBe(200);
+            } finally {
+                await resetBudgets(env);
+            }
+        });
+
+        it('spends the mint budget on a change, and grant units only on recipients without the share', async () => {
+            const prefix = `again-${uuidv4().slice(0, 8)}:`;
+            const other = env.users.other.username;
+            expect((await shareAt(prefix, { recipient: other })).status).toBe(
+                200,
+            );
+            for (const window of KV_SHARE_GRANT_LIMITS) await drain(window);
+            try {
+                // A level change on a standing share takes no grant unit.
+                const raised = await shareAt(prefix, {
+                    recipients: [other],
+                    access: 'write',
+                });
+                expect(raised.status).toBe(200);
+
+                // Naming an unknown user next to it costs what a new share
+                // would, so the window refuses both.
+                for (const extra of ['nobody-by-this-name', third]) {
+                    const refused = await shareAt(prefix, {
+                        recipients: [other, extra],
+                        access: 'write',
+                    });
+                    expect(refused.status).toBe(429);
+                }
+            } finally {
+                await resetBudgets(env);
+            }
+
+            await drain(EVENTS_KV_HANDLE_LIMIT);
+            try {
+                const lowered = await shareAt(prefix, {
+                    recipient: other,
+                    access: 'read',
+                });
+                expect(lowered.status).toBe(429);
+                await expect(lowered.json()).resolves.toMatchObject({
+                    code: 'too_many_requests',
+                });
+            } finally {
+                await resetBudgets(env);
+            }
+        });
+
+        it('counts turning notify on or off as a change', async () => {
+            const prefix = `again-${uuidv4().slice(0, 8)}:`;
+            const other = env.users.other.username;
+            expect((await shareAt(prefix, { recipient: other })).status).toBe(
+                200,
+            );
+            await drain(EVENTS_KV_HANDLE_LIMIT);
+            try {
+                expect(
+                    (await shareAt(prefix, { recipient: other })).status,
+                ).toBe(200);
+                expect(
+                    (
+                        await shareAt(prefix, {
+                            recipient: other,
+                            notify: true,
+                        })
+                    ).status,
+                ).toBe(429);
+            } finally {
+                await resetBudgets(env);
+            }
+        });
+
+        it('spends the lookup budget on every recipient named', async () => {
+            const prefix = `again-${uuidv4().slice(0, 8)}:`;
+            const other = env.users.other.username;
+            expect((await shareAt(prefix, { recipient: other })).status).toBe(
+                200,
+            );
+            await resetBudgets(env);
+            await drain(KV_SHARE_LOOKUP_LIMIT, 1);
+            try {
+                expect(
+                    (await shareAt(prefix, { recipient: other })).status,
+                ).toBe(200);
+                const refused = await shareAt(prefix, { recipient: other });
+                expect(refused.status).toBe(429);
+                await expect(refused.json()).resolves.toMatchObject({
+                    code: 'too_many_requests',
+                });
+            } finally {
+                await resetBudgets(env);
+            }
+        });
+    });
 });
 
 describe('/events/kv-handles beside /kv/shares', () => {

src/backend/controllers/kvShare/KvShareController.ts

@@ -69,6 +69,7 @@ const shareBody = (share: KvShareView) => ({
     appUid: publicAppUid(share.appUid),
     holder: share.holderUsername,
     label: share.label,
+    notify: share.notify,
     createdAt: share.createdAt,
 });
 
@@ -128,8 +129,8 @@ export class KvShareController extends PuterController {
     /**
      * POST /kv/shares — share a region with another account, `read` unless the
      * body asks otherwise. Sharing the same region with the same account again
-     * changes its level or label in place. `recipients` shares it with several
-     * at once and reports each one on its own item.
+     * changes its level, label or `notify` flag in place. `recipients` shares
+     * it with several at once and reports each one on its own item.
      */
     @Post('/shares', {
         subdomain: 'api',
@@ -145,6 +146,7 @@ export class KvShareController extends PuterController {
             access: body.access,
             appUid: body.appUid,
             label: body.label,
+            notify: body.notify,
         };
         const recipients = batchRecipients(body);
         if (recipients) {
@@ -206,6 +208,7 @@ export class KvShareController extends PuterController {
                 appUid: publicAppUid(row.appUid),
                 holder: row.holderUsername,
                 label: row.label,
+                notify: row.notify,
                 createdAt: row.createdAt,
                 revokedAt: row.revokedAt,
                 revokedBy: row.revokedBy,
@@ -234,6 +237,7 @@ export class KvShareController extends PuterController {
                 access: row.access,
                 appUid: publicAppUid(row.appUid),
                 label: row.label,
+                notify: row.notify,
                 createdAt: row.createdAt,
             })),
             ...(page.cursor ? { cursor: page.cursor } : {}),

src/backend/controllers/notification/NotificationController.http.test.ts

@@ -21,9 +21,9 @@ import { afterAll, beforeAll, describe, expect, it } from 'vitest';
 import { setupPuterTestEnv, type PuterTestEnv } from '../../testUtil.js';
 
 /**
- * Route-level coverage for the notification endpoint. Dismissing is the only
- * mark the desktop performs over HTTP, so this suite is what catches the route
- * going missing or a gate turning a legitimate dismiss away.
+ * Route-level coverage for the notification endpoints the desktop calls over
+ * HTTP, so this suite is what catches a route going missing or a gate turning
+ * a legitimate dismiss or removal away.
  */
 describe('notification endpoints over HTTP', () => {
     let env: PuterTestEnv;
@@ -85,4 +85,34 @@ describe('notification endpoints over HTTP', () => {
         });
         expect(after?.acknowledged).toBeFalsy();
     });
+
+    it('removes a notification', async () => {
+        const owner = env.users.user;
+        const { userId, uid } = await seedNotification(owner.username);
+
+        const res = await post('/notif/delete', owner.token, { uid });
+
+        expect(res.status).toBe(200);
+        await expect(res.json()).resolves.toEqual({});
+        const after = await env.server.stores.notification.getByUid(uid, {
+            userId,
+        });
+        expect(after).toBeNull();
+    });
+
+    it('refuses an anonymous removal', async () => {
+        const { userId, uid } = await seedNotification(env.users.other.username);
+
+        const res = await fetch(new URL('/notif/delete', env.apiOrigin), {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify({ uid }),
+        });
+
+        expect(res.status).toBeGreaterThanOrEqual(400);
+        const after = await env.server.stores.notification.getByUid(uid, {
+            userId,
+        });
+        expect(after?.uid).toBe(uid);
+    });
 });

src/backend/controllers/notification/NotificationController.test.ts

@@ -183,3 +183,74 @@ describe('NotificationController.markAck', () => {
         expect(after?.acknowledged).toBeFalsy();
     });
 });
+
+// ── /notif/delete ───────────────────────────────────────────────────
+
+describe('NotificationController.remove', () => {
+    it('deletes the underlying notification row', async () => {
+        const { actor, userId } = await makeUser();
+        const created = await server.stores.notification.create({
+            userId,
+            value: { title: 't' },
+        });
+
+        const { res, captured } = makeRes();
+        await controller.remove(
+            makeReq({ body: { uid: created.uid }, actor }),
+            res,
+        );
+
+        expect(captured.body).toEqual({});
+        const after = await server.stores.notification.getByUid(
+            created.uid as string,
+            { userId },
+        );
+        expect(after).toBeNull();
+    });
+
+    it('succeeds for a uid that names no row', async () => {
+        const { actor } = await makeUser();
+        const { res, captured } = makeRes();
+        await controller.remove(
+            makeReq({ body: { uid: 'no-such-uid' }, actor }),
+            res,
+        );
+        expect(captured.body).toEqual({});
+    });
+
+    it('rejects a missing uid with 400', async () => {
+        const { actor } = await makeUser();
+        const { res } = makeRes();
+        await expect(
+            controller.remove(makeReq({ body: {}, actor }), res),
+        ).rejects.toMatchObject({ statusCode: 400 });
+    });
+
+    it('throws 401 when there is no actor on the request', async () => {
+        const { res } = makeRes();
+        await expect(
+            controller.remove(makeReq({ body: { uid: 'whatever' } }), res),
+        ).rejects.toMatchObject({ statusCode: 401 });
+    });
+
+    it("does not delete another user's notification", async () => {
+        const a = await makeUser();
+        const b = await makeUser();
+        const created = await server.stores.notification.create({
+            userId: a.userId,
+            value: {},
+        });
+
+        const { res } = makeRes();
+        await controller.remove(
+            makeReq({ body: { uid: created.uid }, actor: b.actor }),
+            res,
+        );
+
+        const after = await server.stores.notification.getByUid(
+            created.uid as string,
+            { userId: a.userId },
+        );
+        expect(after?.uid).toBe(created.uid);
+    });
+});

src/backend/controllers/notification/NotificationController.ts

@@ -20,16 +20,44 @@
 import type { Request, Response } from 'express';
 import { Controller, Post } from '../../core/http/decorators.js';
 import { HttpError } from '../../core/http/HttpError.js';
-import type { NotificationService } from '../../services/notification/NotificationService.js';
 import { PuterController } from '../types.js';
 
+/** Both routes fire per interaction; the ceiling catches a loop, not a user. */
+const MARK_ROUTE_OPTIONS = {
+    subdomain: 'api',
+    requireUserActor: true,
+    allowFullAccessToken: true,
+    rateLimit: {
+        scope: 'notification-mark',
+        limit: 300,
+        window: 60_000,
+        key: 'user',
+    },
+} as const;
+
+/** The uid and owner a mark names, or the 400/401 the request earns. */
+const markTarget = (req: Request): { uid: string; userId: number } => {
+    const uid = req.body?.uid;
+    if (typeof uid !== 'string' || uid.length === 0) {
+        throw new HttpError(400, '`uid` must be a non-empty string', {
+            legacyCode: 'bad_request',
+        });
+    }
+    const userId = req.actor?.user?.id;
+    if (!userId)
+        throw new HttpError(401, 'Unauthorized', {
+            legacyCode: 'unauthorized',
+        });
+    return { uid, userId };
+};
+
 /**
- * GUI-facing notification endpoint. Supplements the `puter-notifications`
- * driver (which handles CRUD via `/drivers/call`) with the one mutation route
- * the puter desktop client calls directly.
+ * GUI-facing notification endpoints. Supplement the `puter-notifications`
+ * driver (which handles reads via `/drivers/call`) with the mutations the puter
+ * desktop client calls directly.
  *
- * It emits `outer.gui.notif.ack` via the NotificationService so other open tabs
- * for the same user see the state change immediately.
+ * Each goes through the NotificationService, which tells the user's other open
+ * tabs (`notif.ack`, `notif.removed`) so they update immediately.
  */
 @Controller('/notif')
 export class NotificationController extends PuterController {
@@ -37,50 +65,21 @@ export class NotificationController extends PuterController {
      * POST /notif/mark-ack — user dismissed a notification. Sets `acknowledged`
      * timestamp; pushes ack event to sockets.
      */
-    @Post('/mark-ack', {
-        subdomain: 'api',
-        requireUserActor: true,
-        allowFullAccessToken: true,
-        // Fires per notification interaction, so the ceiling stays
-        // generous — it is here to catch a loop, not to pace a user.
-        rateLimit: {
-            scope: 'notification-mark',
-            limit: 300,
-            window: 60_000,
-            key: 'user',
-        },
-    })
+    @Post('/mark-ack', MARK_ROUTE_OPTIONS)
     async markAck(req: Request, res: Response): Promise<void> {
-        const uid = req.body?.uid;
-        if (typeof uid !== 'string' || uid.length === 0) {
-            throw new HttpError(400, '`uid` must be a non-empty string', {
-                legacyCode: 'bad_request',
-            });
-        }
-        const userId = req.actor?.user?.id;
-        if (!userId)
-            throw new HttpError(401, 'Unauthorized', {
-                legacyCode: 'unauthorized',
-            });
+        const { uid, userId } = markTarget(req);
+        await this.services.notification.markAcknowledged(uid, userId);
+        res.json({});
+    }
 
-        const notifService = this.services.notification as unknown as
-            | NotificationService
-            | undefined;
-        if (notifService?.markAcknowledged) {
-            await notifService.markAcknowledged(uid, userId);
-        } else {
-            // Fallback: direct store call if service isn't wired
-            await (
-                this.stores as Record<string, unknown> as {
-                    notification: {
-                        markAcknowledged: (
-                            uid: string,
-                            userId: number,
-                        ) => Promise<boolean>;
-                    };
-                }
-            ).notification.markAcknowledged(uid, userId);
-        }
+    /**
+     * POST /notif/delete — user removed a notification from their history. A
+     * uid naming none of their rows succeeds too: it is gone either way.
+     */
+    @Post('/delete', MARK_ROUTE_OPTIONS)
+    async remove(req: Request, res: Response): Promise<void> {
+        const { uid, userId } = markTarget(req);
+        await this.services.notification.remove(uid, userId);
         res.json({});
     }
 }

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

@@ -511,6 +511,31 @@ describe('PuterAIController.openaiChatCompletions', () => {
 
         const completeArgs = completeSpy.mock.calls[0]![0];
         expect(completeArgs.provider).toBe('openai-completion');
+        expect(completeArgs.fallback).toBeUndefined();
+    });
+
+    it('forwards fallback: false so the driver stops at the first route', async () => {
+        const completeSpy = stubChatComplete({
+            message: { role: 'assistant', content: 'hi there' },
+            finish_reason: 'stop',
+            usage: { prompt_tokens: 4, completion_tokens: 2 },
+        });
+
+        const { res } = makeRes();
+        await controller.openaiChatCompletions(
+            makeReq({
+                body: {
+                    model: 'gpt-test',
+                    provider: 'openai-completion',
+                    fallback: false,
+                    messages: [{ role: 'user', content: 'hi' }],
+                },
+                actor: makeUserActor(),
+            }),
+            res,
+        );
+
+        expect(completeSpy.mock.calls[0]![0].fallback).toBe(false);
     });
 
     it('still pins OpenAI when the caller names no model, so the default model does not move', async () => {

src/backend/controllers/puterai/PuterAIController.ts

@@ -448,6 +448,7 @@ export class PuterAIController extends PuterController {
                   }
                 : {}),
             ...openaiCompatProvider(body),
+            ...(body.fallback === false ? { fallback: false } : {}),
         };
 
         const result = await this.#complete(res, completeArgs);
@@ -545,8 +546,7 @@ export class PuterAIController extends PuterController {
                         }
                     } else if (ev.type === 'usage') {
                         usageDetails = ev.usageDetails as
-                            | UsageDetails
-                            | undefined;
+                            UsageDetails | undefined;
                         finishReason = ev.finish_reason as string | undefined;
                     } else if (ev.type === 'error') {
                         res.write(
@@ -649,6 +649,7 @@ export class PuterAIController extends PuterController {
                 : {}),
             ...(finiteMaxTokens(body.max_tokens) ?? {}),
             ...openaiCompatProvider(body),
+            ...(body.fallback === false ? { fallback: false } : {}),
         };
 
         const completionId = `cmpl-${randomId()}`;
@@ -694,8 +695,7 @@ export class PuterAIController extends PuterController {
                         sendChunk(ev.text);
                     } else if (ev.type === 'usage') {
                         usageDetails = ev.usageDetails as
-                            | UsageDetails
-                            | undefined;
+                            UsageDetails | undefined;
                         finishReason = ev.finish_reason as string | undefined;
                     } else if (ev.type === 'error') {
                         res.write(
@@ -749,8 +749,7 @@ export class PuterAIController extends PuterController {
                     text: extractTextContent(
                         (
                             messageResult.message as
-                                | Record<string, unknown>
-                                | undefined
+                                Record<string, unknown> | undefined
                         )?.content,
                     ),
                     index: 0,
@@ -869,6 +868,7 @@ export class PuterAIController extends PuterController {
                   }
                 : {}),
             provider: providerName,
+            ...(body.fallback === false ? { fallback: false } : {}),
         };
 
         const responseId = generateId('resp');

src/backend/controllers/puterai/anthropicWire.test.ts

@@ -324,6 +324,18 @@ describe('parseAnthropicRequest', () => {
         expect(args.provider).toBe('claude');
         expect(args.normalize).toBe(false);
         expect(args.streamToolInput).toBe(true);
+        expect(args.fallback).toBeUndefined();
+    });
+
+    it('forwards fallback: false and nothing else for fallback', () => {
+        expect(
+            parseAnthropicRequest({ messages: [], fallback: false }, headers)
+                .fallback,
+        ).toBe(false);
+        expect(
+            parseAnthropicRequest({ messages: [], fallback: 'no' }, headers)
+                .fallback,
+        ).toBeUndefined();
     });
 
     it('maps thinking, tool_choice, stop_sequences, top_p/top_k', () => {

src/backend/controllers/puterai/anthropicWire.ts

@@ -431,6 +431,7 @@ export const parseAnthropicRequest = (
             : {}),
         ...(betas.length ? { anthropicBetas: betas } : {}),
         provider: toStringOrEmpty(body.provider) || 'claude',
+        ...(body.fallback === false ? { fallback: false } : {}),
     };
     // Silently ignored: metadata, service_tier, inference_geo, container,
     // fallbacks, diagnostics.

src/backend/controllers/static/StaticAssetsController.test.ts

@@ -151,6 +151,12 @@ describe('StaticAssetsController client_libs_root', () => {
 
         const sentPutility = await callGetHandler(router, '/putility/v1');
         expect(sentPutility).toEqual({ filename: 'putility.js/v1.js', root });
+
+        for (const route of ['/push-sw.js', '/v2/push-sw.js']) {
+            expect(findRoute(router, 'get', route)?.options.subdomain).toBe('js');
+            const sentWorker = await callGetHandler(router, route);
+            expect(sentWorker).toEqual({ filename: 'puter.js/push-sw.js', root });
+        }
     });
 
     it('does not register the client_libs routes when the root is unset', () => {
@@ -186,6 +192,11 @@ describe('StaticAssetsController puterjs_root', () => {
         expect(v1.root).toBe(root);
         const bareV1 = await callGetHandler(router, '/v1');
         expect(bareV1.filename).toBe('puter.js');
+
+        for (const route of ['/push-sw.js', '/v2/push-sw.js']) {
+            const worker = await callGetHandler(router, route);
+            expect(worker).toEqual({ filename: 'push-sw.js', root });
+        }
     });
 
     it('serves puter.dev.js when present (dev webpack build)', async () => {

src/backend/controllers/static/StaticAssetsController.ts

@@ -26,9 +26,9 @@ import type { PuterRouter } from '../../core/http/PuterRouter';
 /**
  * Static asset routes.
  *
- * /puter.js/v1, /puter.js/v2 → any subdomain /v1, /v2, /putility/v1 → js
- * subdomain /sdk/* → root subdomain — puter-js bundle /dist/_, /src/_,
- * /assets/* → root subdomain
+ * /puter.js/v1, /puter.js/v2 → any subdomain /v1, /v2, /push-sw.js,
+ * /putility/v1 → js subdomain /sdk/* → root subdomain — puter-js bundle
+ * /dist/_, /src/_, /assets/* → root subdomain
  *
  * Each block depends on its config root (`client_libs_root`, `gui_assets_root`,
  * `puterjs_root`). When unset, that block is skipped — deployments that don't
@@ -55,6 +55,12 @@ export class StaticAssetsController extends PuterController {
             router.get('/putility/v1', { subdomain: 'js' }, (_req, res) => {
                 res.sendFile('putility.js/v1.js', { root });
             });
+            // `/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.sendFile('puter.js/push-sw.js', { root });
+                });
+            }
         }
 
         // puter-js SDK mount. GUI loads it at `/sdk/puter.dev.js`; the
@@ -100,6 +106,11 @@ export class StaticAssetsController extends PuterController {
                 router.get('/v2', { subdomain: 'js' }, (_req, res) => {
                     res.sendFile(puterJsFile, { root: puterjsRoot });
                 });
+                for (const route of ['/push-sw.js', '/v2/push-sw.js']) {
+                    router.get(route, { subdomain: 'js' }, (_req, res) => {
+                        res.sendFile('push-sw.js', { root: puterjsRoot });
+                    });
+                }
             }
         }
 

src/backend/controllers/webdav/WebDAVController.largeFolder.http.test.ts

@@ -0,0 +1,146 @@
+/*
+ * 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/>.
+ */
+
+import { randomUUID } from 'node:crypto';
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+import { runWithContext } from '../../core/context.js';
+import {
+    setupPuterTestEnv,
+    TEST_OTHER_USER_CREDENTIALS,
+    TEST_USER_CREDENTIALS,
+    type PuterTestEnv,
+} from '../../testUtil.js';
+
+/** PROPFIND has no paging, so a folder must list whole however large. */
+describe('PROPFIND on a folder larger than one query', () => {
+    let env: PuterTestEnv;
+    const total = 10_050;
+    let dir: string;
+    let dirUuid: string;
+
+    beforeAll(async () => {
+        env = await setupPuterTestEnv();
+        const { username } = env.users.user;
+        dir = `/${username}/Documents/big-${randomUUID().slice(0, 8)}`;
+        const owner = (await env.server.stores.user.getByUsername(username))!;
+        const parent = (await env.server.stores.fsEntry.getEntryByPath(
+            `/${username}/Documents`,
+        ))!;
+        dirUuid = randomUUID();
+        const now = Math.floor(Date.now() / 1000);
+        const insert = (rows: unknown[][]) =>
+            env.server.clients.db.write(
+                `INSERT INTO fsentries (uuid, user_id, parent_id, parent_uid, name, path, is_dir, modified, created, accessed, size) VALUES ${rows.map(() => '(?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)').join(', ')}`,
+                rows.flat(),
+            );
+        await insert([
+            [
+                dirUuid,
+                owner.id,
+                parent.id,
+                parent.uuid,
+                dir.split('/').at(-1),
+                dir,
+                1,
+                now,
+                now,
+                now,
+                0,
+            ],
+        ]);
+        const folder = (await env.server.stores.fsEntry.getEntryByPath(dir))!;
+        for (let start = 0; start < total; start += 500) {
+            const rows: unknown[][] = [];
+            for (let i = start; i < Math.min(total, start + 500); i++) {
+                const name = `f${String(i).padStart(5, '0')}.txt`;
+                rows.push([
+                    randomUUID(),
+                    owner.id,
+                    folder.id,
+                    folder.uuid,
+                    name,
+                    `${dir}/${name}`,
+                    0,
+                    now,
+                    now,
+                    now,
+                    0,
+                ]);
+            }
+            await insert(rows);
+        }
+
+        const actor = { user: owner };
+        await runWithContext({ actor: actor as never }, () =>
+            env.server.services.share.share(actor as never, {
+                uid: dirUuid,
+                recipient: { username: env.users.other.username },
+                mode: 'read',
+            }),
+        );
+    }, 180_000);
+
+    afterAll(async () => {
+        await env?.shutdown();
+    });
+
+    const propfind = async (
+        path: string,
+        credentials: { username: string; password: string },
+    ) => {
+        const port = new URL(env.apiOrigin).port;
+        const auth = Buffer.from(
+            `${credentials.username}:${credentials.password}`,
+        ).toString('base64');
+        const response = await fetch(
+            `http://dav.puter.localhost:${port}${encodeURI(path)}`,
+            {
+                method: 'PROPFIND',
+                headers: { Authorization: `Basic ${auth}`, Depth: '1' },
+            },
+        );
+        return { status: response.status, body: await response.text() };
+    };
+
+    const hrefsOf = (xml: string) =>
+        [...xml.matchAll(/<D:href>([^<]*)<\/D:href>/g)].map((m) => m[1]!);
+
+    it('lists every child', async () => {
+        const { status, body } = await propfind(dir, TEST_USER_CREDENTIALS);
+        expect(status).toBe(207);
+        expect(body.endsWith('</D:multistatus>')).toBe(true);
+        const hrefs = hrefsOf(body);
+        expect(hrefs).toHaveLength(1 + total);
+        expect(new Set(hrefs).size).toBe(1 + total);
+        expect(body).toContain(`${dir}/f10049.txt`);
+    }, 60_000);
+
+    it("masks every page of a share recipient's listing", async () => {
+        const masked = `/${env.users.user.username}/${dirUuid}/${dir.split('/').at(-1)}`;
+        const { status, body } = await propfind(
+            masked,
+            TEST_OTHER_USER_CREDENTIALS,
+        );
+        expect(status).toBe(207);
+        const hrefs = hrefsOf(body);
+        expect(hrefs).toHaveLength(1 + total);
+        expect(hrefs.every((href) => href.startsWith(masked))).toBe(true);
+        expect(body).not.toContain('/Documents/');
+    }, 60_000);
+});

src/backend/controllers/webdav/WebDAVController.ts

@@ -24,6 +24,7 @@ import { posix as pathPosix } from 'node:path';
 import { pipeline } from 'node:stream/promises';
 import type { Actor } from '../../core/actor.js';
 import { HttpError } from '../../core/http/HttpError.js';
+import { pipeToResponse } from '../../core/http/pipeToResponse.js';
 import {
     assertNotSuspended,
     assertTeam2fa,
@@ -58,6 +59,7 @@ import {
 import { Context } from '../../core/context.js';
 import type { FSEntry } from '../../stores/fs/FSEntry.js';
 import {
+    contextBoundStream,
     emitGuiItemEvent,
     type GuiItemEventName,
 } from '../fs/legacyFsHelpers.js';
@@ -600,19 +602,41 @@ export class WebDAVController extends PuterController {
             propfindEntry(maskEntryPath(entry), entry, entry.isDir),
         ];
 
-        if (depth !== '0' && entry.isDir) {
-            const children = await this.services.fs.listDirectory(
-                entry.uuid,
-                {},
-            );
-            for (const child of children) {
-                responses.push(
-                    propfindEntry(maskEntryPath(child), child, child.isDir),
-                );
-            }
+        if (depth === '0' || !entry.isDir) {
+            this.#sendMultistatus(res, responses);
+            return;
         }
 
-        this.#sendMultistatus(res, responses);
+        const toXml = (children: FSEntry[]) =>
+            children
+                .map((child) =>
+                    propfindEntry(maskEntryPath(child), child, child.isDir),
+                )
+                .join('\n');
+        const pages = this.services.fs.listDirectoryPages(entry.uuid);
+        const first = await pages.next();
+        if (!first.done && first.value.length > 0)
+            responses.push(toXml(first.value));
+        const second = await pages.next();
+        if (second.done) {
+            this.#sendMultistatus(res, responses);
+            return;
+        }
+
+        // Past one page the listing streams, so a large folder isn't held in
+        // memory whole. A failure partway cuts the response off.
+        const secondPage = second.value;
+        async function* body() {
+            yield `${MULTISTATUS_OPEN}${responses.join('\n')}`;
+            yield `\n${toXml(secondPage)}`;
+            for await (const page of pages)
+                if (page.length > 0) yield `\n${toXml(page)}`;
+            yield MULTISTATUS_CLOSE;
+        }
+        res.status(207).set({
+            'Content-Type': 'application/xml; charset=utf-8',
+        });
+        await pipeToResponse(contextBoundStream(body()), res);
     }
 
     /**
@@ -1289,8 +1313,12 @@ function escapeXml(text: string): string {
         .replace(/'/g, ''');
 }
 
+const MULTISTATUS_OPEN =
+    '<?xml version="1.0" encoding="utf-8"?>\n<D:multistatus xmlns:D="DAV:">\n';
+const MULTISTATUS_CLOSE = '\n</D:multistatus>';
+
 function wrapMultistatus(inner: string): string {
-    return `<?xml version="1.0" encoding="utf-8"?>\n<D:multistatus xmlns:D="DAV:">\n${inner}\n</D:multistatus>`;
+    return `${MULTISTATUS_OPEN}${inner}${MULTISTATUS_CLOSE}`;
 }
 
 /**

src/backend/core/context.ts

@@ -63,10 +63,17 @@ export interface KnownContextFields {
     driverName: string;
     /**
      * Aborts when the client disconnects before the response has finished (set
-     * by DriverController). Long-running drivers poll it so work nobody will
-     * receive stops early and is never metered.
+     * by DriverController). Some drivers (Gemini, Replicate) stop early on it.
+     * Async video and image jobs keep polling and are metered after a
+     * disconnect, since the provider bills them either way.
      */
     abortSignal: AbortSignal;
+    /**
+     * Keeps the call's concurrency slot until `work` settles (set by
+     * DriverController when the method is capped), for work that outlives the
+     * response.
+     */
+    keepDriverSlot: (work: Promise<unknown>) => void;
     /**
      * Aborts the chat driver's upstream request. A client disconnect doesn't
      * fire it: the upstream bills a request it has accepted either way, so the
@@ -80,6 +87,11 @@ export interface KnownContextFields {
      * different provider's translation of it.
      */
     strictUpstreamErrors: boolean;
+    /**
+     * Set while Puter files something into an account for it (mail delivery),
+     * so filesystem events never report that write as the request actor's own.
+     */
+    platformWrite: boolean;
 }
 
 // Every key of `KnownContextFields`, checked both ways by the compiler, so
@@ -90,8 +102,10 @@ const KNOWN_KEY_FLAGS: Record<keyof KnownContextFields, true> = {
     requestId: true,
     driverName: true,
     abortSignal: true,
+    keepDriverSlot: true,
     upstreamSignal: true,
     strictUpstreamErrors: true,
+    platformWrite: true,
 };
 const KNOWN_KEYS: ReadonlySet<string> = new Set(Object.keys(KNOWN_KEY_FLAGS));
 

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

@@ -0,0 +1,163 @@
+/*
+ * 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/>.
+ */
+
+import { EventEmitter } from 'node:events';
+import type { NextFunction, Request, RequestHandler, Response } from 'express';
+import { describe, expect, it, vi } from 'vitest';
+import { isHttpError } from '../HttpError';
+import {
+    createLargeJsonBodyParser,
+    DEFAULT_JSON_LIMIT_BYTES,
+} from './largeJsonBody';
+
+const MiB = 1024 * 1024;
+
+// A complete request with no socket reads as already consumed to body-parser,
+// so the parsers call straight through, leaving any preset `body` in place.
+const makeReq = (
+    bytes: number | undefined,
+    user: string | null = 'u1',
+    body?: unknown,
+) =>
+    ({
+        complete: true,
+        body,
+        headers: {
+            'content-type': 'application/json',
+            ...(bytes === undefined ? {} : { 'content-length': String(bytes) }),
+            ...(user ? { authorization: user } : {}),
+        },
+    }) as unknown as Request;
+
+const makeRes = () => {
+    const res = new EventEmitter() as EventEmitter & {
+        setHeader: ReturnType<typeof vi.fn>;
+    };
+    res.setHeader = vi.fn();
+    return res;
+};
+
+const authProbe = vi.fn<RequestHandler>((req, _res, next) => {
+    if (req.headers.authorization) {
+        (req as { actor?: unknown }).actor = {
+            user: { uuid: req.headers.authorization },
+        };
+    }
+    next();
+});
+
+const run = (mw: RequestHandler, req: Request, res = makeRes()) =>
+    new Promise<{ err: unknown; res: ReturnType<typeof makeRes> }>(
+        (resolve) => {
+            mw(
+                req,
+                res as unknown as Response,
+                ((err?: unknown) => resolve({ err, res })) as NextFunction,
+            );
+        },
+    );
+
+const statusOf = (err: unknown) => (isHttpError(err) ? err.statusCode : err);
+
+describe('createLargeJsonBodyParser', () => {
+    const create = ({
+        budgetBytes = 200 * MiB,
+        perUserBytes = 128 * MiB,
+        accepts,
+    }: {
+        budgetBytes?: number;
+        perUserBytes?: number;
+        accepts?: (req: Request) => boolean;
+    } = {}) =>
+        createLargeJsonBodyParser({
+            authProbe,
+            limitBytes: 128 * MiB,
+            budgetBytes,
+            perUserBytes,
+            accepts,
+        });
+
+    it.each([
+        ['no Content-Length', undefined],
+        ['a body within the default limit', DEFAULT_JSON_LIMIT_BYTES],
+        ['a body over the large limit', 128 * MiB + 1],
+    ])('leaves %s to the global parser without probing', async (_, bytes) => {
+        authProbe.mockClear();
+        const { err } = await run(create(), makeReq(bytes));
+        expect(err).toBeUndefined();
+        expect(authProbe).not.toHaveBeenCalled();
+    });
+
+    it('leaves an unauthenticated large body to the global parser', async () => {
+        const mw = create({ budgetBytes: 60 * MiB });
+        const { err } = await run(mw, makeReq(60 * MiB, null));
+        expect(err).toBeUndefined();
+        // Nothing was charged, so a signed-in caller still fits.
+        expect((await run(mw, makeReq(60 * MiB))).err).toBeUndefined();
+    });
+
+    it('charges nothing for a client that left during the probe', async () => {
+        const mw = create({ budgetBytes: 60 * MiB });
+        const gone = Object.assign(makeRes(), { closed: true });
+        expect((await run(mw, makeReq(60 * MiB), gone)).err).toBeUndefined();
+        expect((await run(mw, makeReq(60 * MiB))).err).toBeUndefined();
+    });
+
+    it('refuses with 503 past the budget until a response closes', async () => {
+        const mw = create({ budgetBytes: 130 * MiB });
+        const first = await run(mw, makeReq(60 * MiB, 'u1'));
+        await run(mw, makeReq(60 * MiB, 'u2'));
+
+        const refused = await run(mw, makeReq(60 * MiB, 'u3'));
+        expect(statusOf(refused.err)).toBe(503);
+        // Load shedding is recorded, not paged.
+        expect(isHttpError(refused.err) && refused.err.alarmSeverity).toBe(
+            'info',
+        );
+        expect(refused.res.setHeader).toHaveBeenCalledWith('Retry-After', '5');
+
+        first.res.emit('close');
+        expect((await run(mw, makeReq(60 * MiB, 'u3'))).err).toBeUndefined();
+    });
+
+    it("refuses one user's bodies with 429 past their share", async () => {
+        const mw = create({ perUserBytes: 100 * MiB });
+        const first = await run(mw, makeReq(60 * MiB, 'u1'));
+
+        const refused = await run(mw, makeReq(60 * MiB, 'u1'));
+        expect(statusOf(refused.err)).toBe(429);
+        expect(refused.res.setHeader).toHaveBeenCalledWith('Retry-After', '5');
+        // Another user isn't held back by it.
+        expect((await run(mw, makeReq(60 * MiB, 'u2'))).err).toBeUndefined();
+
+        first.res.emit('close');
+        expect((await run(mw, makeReq(60 * MiB, 'u1'))).err).toBeUndefined();
+    });
+
+    it('refuses with 413 a parsed body `accepts` turns down', async () => {
+        const mw = create({
+            accepts: (req) => (req.body as { ok?: boolean }).ok === true,
+        });
+        const refused = await run(mw, makeReq(60 * MiB, 'u1', { ok: false }));
+        expect(statusOf(refused.err)).toBe(413);
+        expect(
+            (await run(mw, makeReq(60 * MiB, 'u2', { ok: true }))).err,
+        ).toBeUndefined();
+    });
+});

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

@@ -0,0 +1,134 @@
+/*
+ * 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/>.
+ */
+
+import express, { type Request, type RequestHandler } from 'express';
+import { actorUid } from '../../actor';
+import { HttpError } from '../HttpError';
+
+/** The global JSON parser's limit, which applies before auth. */
+export const DEFAULT_JSON_LIMIT_BYTES = 50 * 1024 * 1024;
+
+interface LargeJsonBodyOptions {
+    /** The global auth probe; it skips requests that already carry an actor. */
+    authProbe: RequestHandler;
+    limitBytes: number;
+    /** Declared bytes of large bodies a process holds at once. */
+    budgetBytes: number;
+    /** Declared bytes of large bodies one user holds at once. */
+    perUserBytes: number;
+    /** Checked once the body is parsed; a body it refuses gets a 413. */
+    accepts?: (req: Request) => boolean;
+}
+
+/**
+ * Parses JSON bodies over the default limit, up to `limitBytes`, once the
+ * caller's header or cookie credential resolves. Unauthenticated requests and
+ * requests without a Content-Length fall through to the global parser and its
+ * limit.
+ *
+ * The parsed body lives as long as the request, so a body's bytes count against
+ * both budgets until its response closes. Over the user's budget gets a 429,
+ * over the process budget a 503.
+ */
+export const createLargeJsonBodyParser = ({
+    authProbe,
+    limitBytes,
+    budgetBytes,
+    perUserBytes,
+    accepts,
+}: LargeJsonBodyOptions): RequestHandler => {
+    const json = express.json({ limit: limitBytes });
+    const textAsJson = express.json({
+        limit: limitBytes,
+        type: (req) =>
+            req.headers['content-type'] === 'text/plain;actually=json',
+    });
+    let inFlightBytes = 0;
+    const inFlightByUser = new Map<string, number>();
+
+    return (req, res, next) => {
+        const declared = Number(req.headers['content-length']);
+        if (!(declared > DEFAULT_JSON_LIMIT_BYTES && declared <= limitBytes)) {
+            next();
+            return;
+        }
+        void authProbe(req, res, () => {
+            // `res.closed`: the client left during the probe, so `close` has
+            // already fired and would never release a charge.
+            if (!req.actor || res.closed) {
+                next();
+                return;
+            }
+            const user = req.actor.user.uuid ?? actorUid(req.actor);
+            const userBytes = inFlightByUser.get(user) ?? 0;
+            if (userBytes + declared > perUserBytes) {
+                res.setHeader('Retry-After', '5');
+                next(
+                    new HttpError(
+                        429,
+                        'Too many large requests in progress for this account',
+                        { legacyCode: 'too_many_requests' },
+                    ),
+                );
+                return;
+            }
+            if (inFlightBytes + declared > budgetBytes) {
+                res.setHeader('Retry-After', '5');
+                next(
+                    new HttpError(503, 'Too many large requests in progress', {
+                        code: 'large_body_capacity',
+                        // Load shedding, not a fault: record it, don't page.
+                        alarmSeverity: 'info',
+                    }),
+                );
+                return;
+            }
+            inFlightBytes += declared;
+            inFlightByUser.set(user, userBytes + declared);
+            res.once('close', () => {
+                inFlightBytes -= declared;
+                const left = (inFlightByUser.get(user) ?? 0) - declared;
+                if (left > 0) inFlightByUser.set(user, left);
+                else inFlightByUser.delete(user);
+            });
+            json(req, res, (err?: unknown) => {
+                if (err) {
+                    next(err);
+                    return;
+                }
+                textAsJson(req, res, (err?: unknown) => {
+                    if (err) {
+                        next(err);
+                        return;
+                    }
+                    if (accepts && !accepts(req)) {
+                        // The same answer the default limit gives.
+                        next(
+                            new HttpError(413, 'request entity too large', {
+                                legacyCode: 'client_bad_request',
+                            }),
+                        );
+                        return;
+                    }
+                    next();
+                });
+            });
+        });
+    };
+};

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

@@ -476,9 +476,8 @@ function actorMatchesExpectedApp(
 }
 
 /**
- * Mirror of `resolvePrivateIdentity` for public hosted apps. Reads the sticky
- * `puter.public.hosted.actor.token` cookie first, then the same
- * session/bootstrap fallbacks.
+ * Fresh authenticated identities replace the sticky public billing cookie when
+ * the visitor switches accounts.
  */
 export async function resolvePublicHostedIdentity(opts: {
     req: Request;
@@ -500,37 +499,6 @@ export async function resolvePublicHostedIdentity(opts: {
     const cookies = (req as Request & { cookies?: Record<string, string> })
         .cookies;
 
-    const { name: publicCookieNameV2, legacyName: publicCookieNameLegacy } =
-        HOSTED_ASSET_COOKIES.public;
-    const publicCookieToken =
-        (typeof cookies?.[publicCookieNameV2] === 'string'
-            ? cookies[publicCookieNameV2]
-            : null) ??
-        (typeof cookies?.[publicCookieNameLegacy] === 'string'
-            ? cookies[publicCookieNameLegacy]
-            : null);
-    if (publicCookieToken) {
-        try {
-            const claims = await authService.verifyHostedAssetToken(
-                'public',
-                publicCookieToken,
-                {
-                    appUid: expectedAppUid,
-                    subdomain: expectedSubdomain,
-                    host: expectedHost,
-                },
-            );
-            return {
-                source: 'public-cookie',
-                userUid: claims.userUid,
-                sessionUuid: claims.sessionUuid,
-                hasValidPublicCookie: true,
-            };
-        } catch {
-            /* fall through — v1-signed cookies land here and get re-minted */
-        }
-    }
-
     const existingActor = req.actor;
     if (
         existingActor?.user?.uuid &&
@@ -586,6 +554,37 @@ export async function resolvePublicHostedIdentity(opts: {
         }
     }
 
+    const { name: publicCookieNameV2, legacyName: publicCookieNameLegacy } =
+        HOSTED_ASSET_COOKIES.public;
+    const publicCookieToken =
+        (typeof cookies?.[publicCookieNameV2] === 'string'
+            ? cookies[publicCookieNameV2]
+            : null) ??
+        (typeof cookies?.[publicCookieNameLegacy] === 'string'
+            ? cookies[publicCookieNameLegacy]
+            : null);
+    if (publicCookieToken) {
+        try {
+            const claims = await authService.verifyHostedAssetToken(
+                'public',
+                publicCookieToken,
+                {
+                    appUid: expectedAppUid,
+                    subdomain: expectedSubdomain,
+                    host: expectedHost,
+                },
+            );
+            return {
+                source: 'public-cookie',
+                userUid: claims.userUid,
+                sessionUuid: claims.sessionUuid,
+                hasValidPublicCookie: true,
+            };
+        } catch {
+            /* fall through — v1-signed cookies land here and get re-minted */
+        }
+    }
+
     return { source: 'none' };
 }
 

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

@@ -2591,3 +2591,239 @@ describe('createPuterSiteMiddleware — private-app gate decisions', () => {
         },
     );
 });
+
+describe('public hosted asset billing identity', () => {
+    it.each(['actor', 'session', 'query'] as const)(
+        'replaces an older billing cookie with the current %s identity',
+        async (source) => {
+            const owner = await makeUserWithHome();
+            const previous = await makeUser();
+            const current = await makeUser();
+            const home = (await server.stores.fsEntry.getEntryByPath(
+                `/${owner.username}`,
+            ))!;
+            const sub = `switch-${uuidv4().slice(0, 8)}`;
+            const host = `${sub}.site.puter.localhost`;
+            await server.stores.subdomain.create({
+                userId: owner.id,
+                subdomain: sub,
+                rootDirId: home.id,
+            });
+            await writeFile(
+                owner.id,
+                `/${owner.username}/index.html`,
+                Buffer.from('hello'),
+            );
+            const app = await server.stores.app.create(
+                { name: sub, title: sub, index_url: `http://${host}/` },
+                { ownerUserId: owner.id },
+            );
+            const previousToken = await server.services.auth.getUserAppToken(
+                actorFor(previous),
+                app.uid,
+            );
+            const previousActor =
+                (await server.services.auth.authenticateFromToken(
+                    previousToken,
+                ))!;
+            const currentToken = await server.services.auth.getUserAppToken(
+                actorFor(current),
+                app.uid,
+            );
+            const oldCookie = await server.services.auth.createHostedAssetToken(
+                'public',
+                {
+                    appUid: app.uid,
+                    userUid: previous.uuid,
+                    sessionUuid: previousActor.session?.uid,
+                    subdomain: sub,
+                    host,
+                },
+            );
+            const cookieName = HOSTED_ASSET_COOKIES.public.name;
+            const req = makeReq({
+                hostname: host,
+                path: '/index.html',
+                cookies: {
+                    [cookieName]: oldCookie,
+                    ...(source === 'session' ? { session: currentToken } : {}),
+                },
+                query:
+                    source === 'query'
+                        ? { 'puter.auth.token': currentToken }
+                        : {},
+            });
+            if (source === 'actor')
+                req.actor =
+                    (await server.services.auth.authenticateFromToken(
+                        currentToken,
+                    ))!;
+            const { res, out } = makeRes();
+            await buildMiddleware({ cookie_name: 'session' })(
+                req,
+                res,
+                vi.fn(),
+            );
+            await new Promise<void>((resolve) => setImmediate(resolve));
+            expect(out.statusCode).toBe(200);
+            expect(req.egressActor?.user?.uuid).toBe(current.uuid);
+            const refreshed = out.cookies[cookieName];
+            expect(refreshed).toBeTruthy();
+            expect(
+                (
+                    await server.services.auth.verifyHostedAssetToken(
+                        'public',
+                        refreshed,
+                        { appUid: app.uid, host },
+                    )
+                ).userUid,
+            ).toBe(current.uuid);
+            const nextReq = makeReq({
+                hostname: host,
+                path: '/index.html',
+                cookies: { [cookieName]: refreshed },
+            });
+            await runMiddleware(buildMiddleware(), nextReq);
+            expect(nextReq.egressActor?.user?.uuid).toBe(current.uuid);
+        },
+    );
+
+    it('bills recognized visitors, reuses the parent session, and falls back to the owner', async () => {
+        const owner = await makeUserWithHome();
+        const visitor = await makeUser();
+        const home = (await server.stores.fsEntry.getEntryByPath(
+            `/${owner.username}`,
+        ))!;
+        const sub = `egress-${uuidv4().slice(0, 8)}`;
+        const host = `${sub}.site.puter.localhost`;
+        await server.stores.subdomain.create({
+            userId: owner.id,
+            subdomain: sub,
+            rootDirId: home.id,
+        });
+        await writeFile(
+            owner.id,
+            `/${owner.username}/index.html`,
+            Buffer.from('hello'),
+        );
+        const app = await server.stores.app.create(
+            { name: sub, title: sub, index_url: `http://${host}/` },
+            { ownerUserId: owner.id },
+        );
+        const token = await server.services.auth.getUserAppToken(
+            actorFor(visitor),
+            app.uid,
+        );
+        const authenticated =
+            await server.services.auth.authenticateFromToken(token);
+        const serve = async (query = {}, cookies = {}, headers = {}) => {
+            const req = makeReq({ hostname: host, path: '/index.html', query });
+            Object.assign(req, { cookies, headers });
+            const { res, out } = makeRes();
+            await buildMiddleware()(req, res, vi.fn());
+            await new Promise<void>((resolve) => setImmediate(resolve));
+            expect(out.statusCode).toBe(200);
+            return { req, out };
+        };
+        const create = vi.spyOn(server.stores.session, 'create');
+        try {
+            const first = await serve({ 'puter.auth.token': token });
+            expect(first.req.egressActor?.user?.uuid).toBe(visitor.uuid);
+            const cookieName = HOSTED_ASSET_COOKIES.public.name;
+            const cookie = first.out.cookies[cookieName];
+            expect(cookie).toBeTruthy();
+            const claims = await server.services.auth.verifyHostedAssetToken(
+                'public',
+                cookie,
+                { appUid: app.uid, host },
+            );
+            expect(claims.sessionUuid).toBe(authenticated?.session?.uid);
+            const next = await serve({}, { [cookieName]: cookie });
+            expect(next.req.egressActor?.user?.uuid).toBe(visitor.uuid);
+            expect(next.out.cookies).toEqual({});
+            const blockedCookies = await serve(
+                {},
+                {},
+                { referer: `http://${host}/?puter.auth.token=${token}` },
+            );
+            expect(blockedCookies.req.egressActor?.user?.uuid).toBe(
+                visitor.uuid,
+            );
+            expect(create).not.toHaveBeenCalled();
+            const anonymous = await serve();
+            expect(anonymous.req.egressActor?.user?.uuid).toBe(owner.uuid);
+            const invalid = await serve({}, { [cookieName]: 'invalid' });
+            expect(invalid.req.egressActor?.user?.uuid).toBe(owner.uuid);
+            await server.services.auth.revokeAllSessionsForUserId(visitor.id);
+            const revoked = await serve({}, { [cookieName]: cookie });
+            expect(revoked.req.egressActor?.user?.uuid).toBe(owner.uuid);
+        } finally {
+            create.mockRestore();
+        }
+    });
+});
+
+describe('site rooted in the owner tree, root moved to Trash', () => {
+    it('stops serving a trashed folder and resumes when restored', async () => {
+        const owner = await makeUserWithHome();
+        const dir = await server.services.fs.mkdir(owner.id, {
+            path: `/${owner.username}/Documents/site`,
+            createMissingParents: true,
+        });
+        const body = Buffer.from('<html>trashed</html>');
+        await server.services.fs.write(owner.id, {
+            fileMetadata: {
+                path: `/${owner.username}/Documents/site/index.html`,
+                size: body.byteLength,
+            },
+            fileContent: body,
+        });
+        const sub = `tr-${Math.random().toString(36).slice(2, 8)}`;
+        await server.stores.subdomain.create({
+            userId: owner.id,
+            subdomain: sub,
+            rootDirId: dir.id,
+        });
+        const serveIndex = async () => {
+            const mw = createPuterSiteMiddleware(hostingConfig, {
+                clients: server.clients,
+                stores: server.stores,
+                services: server.services,
+            });
+            const { res, out } = makeRes();
+            await mw(
+                makeReq({
+                    hostname: `${sub}.site.puter.localhost`,
+                    path: '/',
+                }),
+                res,
+                vi.fn(),
+            );
+            await new Promise<void>((resolve) => setImmediate(resolve));
+            return out;
+        };
+        expect((await serveIndex()).statusCode).toBe(200);
+
+        const trash = (await server.stores.fsEntry.getEntryByPath(
+            `/${owner.username}/Trash`,
+        ))!;
+        const entry = (await server.stores.fsEntry.getEntryById(dir.id))!;
+        await server.services.fs.move(owner.id, {
+            source: entry,
+            destinationParent: trash,
+        });
+        const moved = (await server.stores.fsEntry.getEntryById(dir.id))!;
+        expect(moved.path.startsWith(`/${owner.username}/Trash/`)).toBe(true);
+
+        const out = await serveIndex();
+        expect(out.statusCode).toBe(404);
+        const documents = (await server.stores.fsEntry.getEntryByPath(
+            `/${owner.username}/Documents`,
+        ))!;
+        await server.services.fs.move(owner.id, {
+            source: moved,
+            destinationParent: documents,
+        });
+        expect((await serveIndex()).statusCode).toBe(200);
+    });
+});

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

@@ -27,6 +27,7 @@ import { MANAGE_PERM_PREFIX } from '../../../services/permission/consts';
 import type { puterStores } from '../../../stores';
 import type { IConfig, LayerInstances } from '../../../types';
 import { awaitLater } from '../../../util/concurrency';
+import { isTrashedPath } from '../../../util/hostedAppBacking';
 import { makeActor } from '../../actor';
 import {
     buildAppCenterFallback,
@@ -109,10 +110,6 @@ const isServableEntryPath = (
     return !isWorkersSourcePath(relPath) && !isSiteConfigPath(relPath);
 };
 
-/** Inside some owner's top-level Trash, which is where Delete puts things. */
-const isTrashedPath = (path: string): boolean =>
-    /^\/[^/]+\/Trash(\/|$)/u.test(path);
-
 /**
  * Suggested value for `config.hosting_csp`. Not applied unless configured.
  *
@@ -333,6 +330,7 @@ export const createPuterSiteMiddleware = (
 
         const associatedApp = (await appLookup) as AppRow | null;
 
+        let hostedVisitorUid: string | undefined;
         const isPrivateApp = Boolean(associatedApp?.is_private);
         const privateApp = isPrivateApp ? associatedApp : null;
 
@@ -400,6 +398,8 @@ export const createPuterSiteMiddleware = (
                 return;
             }
 
+            hostedVisitorUid = identity.userUid;
+
             // Entitlement check runs on every request — matching v1. The
             // sticky cookie is an identity shortcut, not an access cache;
             // the marketplace extension already caches access decisions
@@ -509,11 +509,8 @@ export const createPuterSiteMiddleware = (
             res.status(404).type('text/plain').send('Subdomain not found');
             return;
         } else {
-            // Public hosted site. Mint the public hosted-actor cookie if
-            // we can identify the visitor — lets the hosted page make
-            // cross-origin requests as the actor without needing a
-            // host-scoped main session cookie. No-op for anonymous
-            // visitors.
+            // Remember the authenticated visitor for asset billing across
+            // requests that do not carry the original app token.
             try {
                 const identity = await resolvePublicHostedIdentity({
                     req,
@@ -526,6 +523,7 @@ export const createPuterSiteMiddleware = (
                     expectedSubdomain: subdomain,
                     expectedHost: host,
                 });
+                hostedVisitorUid = identity.userUid;
                 if (
                     identity.userUid &&
                     !(identity as { hasValidPublicCookie?: boolean })
@@ -574,7 +572,7 @@ export const createPuterSiteMiddleware = (
                 .send(SUBDOMAIN_404);
             return;
         }
-        if (!rootEntry.isDir) {
+        if (!rootEntry.isDir || isTrashedPath(rootEntry.path)) {
             res.status(404)
                 .type('text/html; charset=UTF-8')
                 .send(SUBDOMAIN_404);
@@ -584,37 +582,27 @@ export const createPuterSiteMiddleware = (
         // A site rooted in someone else's directory stands on the `manage`
         // grant that authorized publishing it, and serves that whole subtree
         // with the ACL bypassed — so the grant is re-read on every request.
-        // Trash is its own check: a grant is keyed on the node, not its
-        // location, so it survives the owner deleting the directory. Sites
-        // rooted in their publisher's own tree skip all of this.
         if (rootEntry.userId !== site.user_id) {
             let stillPublishable = false;
-            if (!isTrashedPath(rootEntry.path)) {
-                try {
-                    stillPublishable = await layers.services.acl.check(
-                        makeActor({
-                            user: {
-                                id: owner.id,
-                                uuid: owner.uuid,
-                                username: owner.username,
-                            },
-                        }),
-                        {
-                            path: rootEntry.path,
-                            resolveAncestors: () =>
-                                layers.services.fs.getAncestorChain(
-                                    rootEntry.path,
-                                ),
+            try {
+                stillPublishable = await layers.services.acl.check(
+                    makeActor({
+                        user: {
+                            id: owner.id,
+                            uuid: owner.uuid,
+                            username: owner.username,
                         },
-                        MANAGE_PERM_PREFIX,
-                    );
-                } catch (e) {
-                    // Fail closed — an unreadable grant is not a held one.
-                    console.warn(
-                        '[puter-site] publish grant recheck failed',
-                        e,
-                    );
-                }
+                    }),
+                    {
+                        path: rootEntry.path,
+                        resolveAncestors: () =>
+                            layers.services.fs.getAncestorChain(rootEntry.path),
+                    },
+                    MANAGE_PERM_PREFIX,
+                );
+            } catch (e) {
+                // Fail closed — an unreadable grant is not a held one.
+                console.warn('[puter-site] publish grant recheck failed', e);
             }
             if (!stillPublishable) {
                 res.status(404)
@@ -837,7 +825,22 @@ export const createPuterSiteMiddleware = (
         // hosting is unauthenticated by design, so most visitors are nobody in
         // particular. Set unconditionally because hosting subdomains are not
         // metered by default: this is what opts the response in.
-        req.egressActor = req.actor ?? {
+        let visitorActor = req.actor;
+        if (hostedVisitorUid && visitorActor?.user?.uuid !== hostedVisitorUid) {
+            try {
+                const visitor =
+                    await layers.stores.user.getByUuid(hostedVisitorUid);
+                if (visitor && !visitor.suspended) {
+                    visitorActor = makeActor({
+                        user: visitor,
+                        app: associatedApp ?? undefined,
+                    });
+                }
+            } catch {
+                // Unknown requesters are billed to the site owner.
+            }
+        }
+        req.egressActor = visitorActor ?? {
             user: {
                 uuid: owner.uuid,
                 id: owner.id,

src/backend/core/http/middleware/rateLimit.js

@@ -84,6 +84,10 @@ export function sweepMemoryWindows() {
         )
             memoryWindows.delete(k);
     }
+    for (const [k, entry] of memoryCounters) {
+        if (entry.index < Math.floor(now / entry.windowMs) - 1)
+            memoryCounters.delete(k);
+    }
 }
 
 {
@@ -155,6 +159,97 @@ async function peekMemory(key, limit, windowMs) {
     return timestamps.length < limit;
 }
 
+// -- Counted claims --------------------------------------------------
+//
+// `claim` keeps a member per unit, which is fine for a few units and not for
+// thousands. The counted form keeps two counters per key, the current fixed
+// window and the one before it, and slides by weighting the previous one by
+// how much of it the window still covers. It can be off by a little at window
+// edges, and its buckets are separate from the other forms'.
+
+/** The sliding-window estimate from the two fixed windows it overlaps. */
+const slidingCount = (previous, current, now, windowMs) =>
+    previous * (1 - (now % windowMs) / windowMs) + current;
+
+/** How many of `units` a counted claim that left `used` spent may keep. */
+const countedAdmits = (used, limit, units) =>
+    units - Math.min(units, Math.max(0, Math.ceil(used - limit)));
+
+/** Key → `{ index, current, previous, windowMs }`, swept with the windows. */
+const memoryCounters = new Map();
+
+async function claimCountMemory(key, limit, windowMs, units) {
+    const now = Date.now();
+    const index = Math.floor(now / windowMs);
+    let entry = memoryCounters.get(key);
+    if (!entry) {
+        if (memoryCounters.size >= MEMORY_MAX_KEYS) {
+            memoryCounters.delete(memoryCounters.keys().next().value);
+        }
+        entry = { index, current: 0, previous: 0, windowMs };
+        memoryCounters.set(key, entry);
+    } else if (entry.index !== index) {
+        entry.previous = entry.index === index - 1 ? entry.current : 0;
+        entry.current = 0;
+        entry.index = index;
+    }
+    entry.windowMs = windowMs;
+    const used = slidingCount(entry.previous, entry.current, now, windowMs);
+    const admitted = countedAdmits(used + units, limit, units);
+    entry.current += admitted;
+    return admitted;
+}
+
+async function claimCountRedis(redis, key, limit, windowMs, units) {
+    const now = Date.now();
+    const index = Math.floor(now / windowMs);
+    // The hash tag keeps both windows in one slot, so one MULTI reads both.
+    const current = `ratec:{${key}}:${index}`;
+    const results = await redis
+        .multi()
+        .incrby(current, units)
+        .pexpire(current, 2 * windowMs)
+        .get(`ratec:{${key}}:${index - 1}`)
+        .exec();
+    const used = slidingCount(
+        Number(multiResult(results, 2) ?? 0),
+        Number(multiResult(results, 0)),
+        now,
+        windowMs,
+    );
+    const admitted = countedAdmits(used, limit, units);
+    if (admitted < units) await redis.decrby(current, units - admitted);
+    return admitted;
+}
+
+async function claimCountKv(kv, key, limit, windowMs, units) {
+    const now = Date.now();
+    const index = Math.floor(now / windowMs);
+    const current = `ratec:${key}:${index}`;
+    const [counted, previous] = await Promise.all([
+        kv.incr({
+            key: current,
+            pathAndAmountMap: { '': units },
+            expireAt: Math.ceil((now + 2 * windowMs) / 1000),
+        }),
+        kv.get({ key: `ratec:${key}:${index - 1}` }),
+    ]);
+    const used = slidingCount(
+        Number(previous.res ?? 0),
+        Number(counted.res),
+        now,
+        windowMs,
+    );
+    const admitted = countedAdmits(used, limit, units);
+    if (admitted < units) {
+        await kv.decr({
+            key: current,
+            pathAndAmountMap: { '': units - admitted },
+        });
+    }
+    return admitted;
+}
+
 // -- Redis backend ---------------------------------------------------
 
 // ioredis MULTI/EXEC reports per-command failures inside the exec() result
@@ -475,6 +570,10 @@ function instrumentBackendPair(name, pair) {
             withSpan('rate_limit.claim', attrs, () =>
                 pair.claim(key, limit, windowMs, units),
             ),
+        count: (key, limit, windowMs, units) =>
+            withSpan('rate_limit.count', attrs, () =>
+                pair.count(key, limit, windowMs, units),
+            ),
         acquire: (key, limit) =>
             withSpan('rate_limit.acquire', attrs, () =>
                 pair.acquire(key, limit),
@@ -486,6 +585,7 @@ const memoryBackendPair = instrumentBackendPair('memory', {
     rate: checkMemory,
     peek: peekMemory,
     claim: claimMemory,
+    count: claimCountMemory,
     acquire: acquireMemoryConcurrent,
 });
 
@@ -536,6 +636,8 @@ export function configureRateLimit({
                 peekRedis(redis, key, limit, windowMs),
             claim: (key, limit, windowMs, units) =>
                 claimRedis(redis, key, limit, windowMs, units),
+            count: (key, limit, windowMs, units) =>
+                claimCountRedis(redis, key, limit, windowMs, units),
             acquire: (key, limit) => acquireRedisConcurrent(redis, key, limit),
         });
     }
@@ -545,6 +647,8 @@ export function configureRateLimit({
             peek: (key, limit) => peekKv(kv, key, limit),
             claim: (key, limit, windowMs, units) =>
                 claimKv(kv, key, limit, windowMs, units),
+            count: (key, limit, windowMs, units) =>
+                claimCountKv(kv, key, limit, windowMs, units),
             acquire: (key, limit) => acquireKvConcurrent(kv, key, limit),
         });
     }
@@ -874,6 +978,32 @@ export async function claimRateLimit(key, limit, windowMs, units, backend) {
     }
 }
 
+/**
+ * `claimRateLimit` for budgets measured in many units per call: a claim costs
+ * the same however many units it spends (see "Counted claims" above). Its
+ * buckets are its own, so a key is only ever claimed one way. Fails open,
+ * admitting every unit.
+ */
+export async function claimCountedRateLimit(
+    key,
+    limit,
+    windowMs,
+    units,
+    backend,
+) {
+    if (!(units > 0)) return 0;
+    const bk = resolveBackend(backend);
+    try {
+        return await bk.count(key, limit, windowMs, units);
+    } catch (err) {
+        console.error(
+            '[rate-limit] imperative counted claim failed, failing open:',
+            err,
+        );
+        return units;
+    }
+}
+
 /**
  * Charge a route-shaped rate-limit spec from inside a handler.
  *
@@ -1049,8 +1179,8 @@ export function concurrencyGate(opts) {
  * Acquire a concurrent slot for a driver call. Mirrors `checkDriverRateLimit`
  * but returns an acquisition handle: caller MUST invoke `release()` on the
  * returned object exactly once, even on thrown errors — typically in a
- * `finally`. `ok: false` means the slot was full; callers should reject with
- * 429 in that case.
+ * `finally`. `renew()` keeps a long-held slot past the orphan TTL. `ok: false`
+ * means the slot was full; callers should reject with 429 in that case.
  *
  * `opts` is the resolved per-method spec from the driver's decorator (or
  * imperative `concurrent` field). Omitting `opts` (driver declares nothing)
@@ -1060,7 +1190,7 @@ export function concurrencyGate(opts) {
  */
 export async function acquireDriverConcurrent(req, ifaceName, method, opts) {
     if (!opts || typeof opts.limit !== 'number') {
-        return { ok: true, release: noop };
+        return { ok: true, release: noop, renew: noop };
     }
     const slot = await charge(
         req,
@@ -1072,8 +1202,7 @@ export async function acquireDriverConcurrent(req, ifaceName, method, opts) {
             label: '[concurrent] driver acquire',
         },
     );
-    if (!slot) return { ok: true, release: noop };
-    if (!slot.ok) return { ok: false, release: noop };
-    const { release } = guardSlot(slot, '[concurrent] driver');
-    return { ok: true, release };
+    if (!slot) return { ok: true, release: noop, renew: noop };
+    if (!slot.ok) return { ok: false, release: noop, renew: noop };
+    return guardSlot(slot, '[concurrent] driver');
 }

src/backend/core/http/middleware/rateLimit.test.js

@@ -37,6 +37,7 @@ import {
     acquireDriverConcurrent,
     checkDriverRateLimit,
     checkRateLimit,
+    claimCountedRateLimit,
     claimRateLimit,
     concurrencyGate,
     consumeRouteRateLimit,
@@ -1487,6 +1488,13 @@ describe('rate + concurrent limiting — kv backend', () => {
         expect(await claimRateLimit(key, 5, 60_000, 1)).toBe(0);
     });
 
+    it('claims counted units, admitting only what fits', async () => {
+        const key = uniqueScope();
+        expect(await claimCountedRateLimit(key, 5, 60_000, 3)).toBe(3);
+        expect(await claimCountedRateLimit(key, 5, 60_000, 3)).toBe(2);
+        expect(await claimCountedRateLimit(key, 5, 60_000, 1)).toBe(0);
+    });
+
     it('claims against a full bucket as full while expired rows are unswept', async () => {
         const key = uniqueScope();
         await seedUnswept(`rate:${key}:`, 3);
@@ -2010,6 +2018,103 @@ describe('acquireConcurrent (imperative)', () => {
     });
 });
 
+describe('claimCountedRateLimit', () => {
+    const uniqueKey = () =>
+        `counted-${Math.random().toString(36).slice(2, 10)}`;
+    const WINDOW = 10_000;
+    /** The start of a fixed window, so nothing before it carries in. */
+    const windowStart = (n) => vi.setSystemTime(n * WINDOW);
+
+    afterEach(() => {
+        vi.useRealTimers();
+    });
+
+    describe.each([
+        ['memory', () => configureRateLimit()],
+        [
+            'redis',
+            () =>
+                configureRateLimit({
+                    default: 'redis',
+                    redis: new RedisMock(),
+                }),
+        ],
+    ])('%s backend', (_name, configure) => {
+        beforeEach(() => {
+            configure();
+            vi.useFakeTimers({ toFake: ['Date'] });
+            windowStart(1_000);
+        });
+
+        it('admits up to the limit and spends only what fits', async () => {
+            const key = uniqueKey();
+            expect(await claimCountedRateLimit(key, 5, WINDOW, 3)).toBe(3);
+            expect(await claimCountedRateLimit(key, 5, WINDOW, 3)).toBe(2);
+            expect(await claimCountedRateLimit(key, 5, WINDOW, 1)).toBe(0);
+        });
+
+        it('spends thousands of units in one claim', async () => {
+            const key = uniqueKey();
+            expect(
+                await claimCountedRateLimit(key, 15_000, WINDOW, 6_000),
+            ).toBe(6_000);
+            expect(
+                await claimCountedRateLimit(key, 15_000, WINDOW, 10_000),
+            ).toBe(9_000);
+        });
+
+        it('carries the previous window by how much of it is still inside', async () => {
+            const key = uniqueKey();
+            expect(await claimCountedRateLimit(key, 100, WINDOW, 100)).toBe(
+                100,
+            );
+            // A quarter into the next window, 75 of those still count.
+            vi.setSystemTime(1_001 * WINDOW + WINDOW / 4);
+            expect(await claimCountedRateLimit(key, 100, WINDOW, 50)).toBe(25);
+            // Two windows on, nothing carries.
+            windowStart(1_003);
+            expect(await claimCountedRateLimit(key, 100, WINDOW, 100)).toBe(
+                100,
+            );
+        });
+
+        it('keeps its buckets apart from claimRateLimit', async () => {
+            const key = uniqueKey();
+            expect(await claimCountedRateLimit(key, 2, WINDOW, 2)).toBe(2);
+            expect(await claimRateLimit(key, 2, WINDOW, 2)).toBe(2);
+        });
+    });
+
+    it('claims nothing for zero units', async () => {
+        const key = uniqueKey();
+        expect(await claimCountedRateLimit(key, 1, WINDOW, 0)).toBe(0);
+        expect(await claimCountedRateLimit(key, 1, WINDOW, 1)).toBe(1);
+    });
+
+    it('fails open, admitting every unit, when the backend throws', async () => {
+        const redis = new RedisMock();
+        redis.multi = () => {
+            throw new Error('redis down');
+        };
+        configureRateLimit({ default: 'redis', redis });
+        const spy = vi.spyOn(console, 'error').mockImplementation(() => {});
+        expect(await claimCountedRateLimit(uniqueKey(), 1, WINDOW, 4)).toBe(4);
+        spy.mockRestore();
+    });
+
+    it('drops a memory counter once its windows have passed', async () => {
+        configureRateLimit();
+        vi.useFakeTimers({ toFake: ['Date'] });
+        windowStart(2_000);
+        const key = uniqueKey();
+        expect(await claimCountedRateLimit(key, 1, WINDOW, 1)).toBe(1);
+        windowStart(2_002);
+        sweepMemoryWindows();
+        windowStart(2_000);
+        expect(await claimCountedRateLimit(key, 1, WINDOW, 1)).toBe(1);
+    });
+});
+
 describe('claimRateLimit', () => {
     const uniqueKey = () => `claim-${Math.random().toString(36).slice(2, 10)}`;
 

src/backend/data/hardcoded-permissions.js

@@ -104,6 +104,8 @@ const default_user_permissions = {
     // is there; which app may is the per-app grant, which is what the user is
     // actually asked about.
     'events:background': {},
+    // Likewise, the per-app grant decides whose notifications go out as pushes.
+    'notifications:push': {},
 };
 
 module.exports = {

src/backend/drivers/ai-chat/ChatCompletionDriver.routing.test.ts

@@ -209,6 +209,7 @@ afterAll(async () => {
 const attemptsFor = async (
     model: string,
     thrown: unknown = new Error('upstream down'),
+    extra: { provider?: string; fallback?: boolean } = {},
 ) => {
     createMock.mockRejectedValue(thrown);
     let caught: HttpError | undefined;
@@ -217,6 +218,7 @@ const attemptsFor = async (
             driver.complete({
                 model,
                 messages: [{ role: 'user', content: 'hi' }],
+                ...extra,
             }),
         );
     } catch (e) {
@@ -886,6 +888,59 @@ describe('ChatCompletionDriver duplicate-model fallback', () => {
     });
 });
 
+describe('ChatCompletionDriver fallback opt-out', () => {
+    const SHARED = 'deepseek-v4-pro';
+
+    it('fails on the first route when the caller sets fallback: false', async () => {
+        const attempts = await attemptsFor(SHARED, undefined, {
+            fallback: false,
+        });
+
+        expect(attempts).toHaveLength(1);
+        expect(attempts[0]).toMatchObject({ provider: 'deepseek' });
+    });
+
+    it('tries only the pinned provider', async () => {
+        const attempts = await attemptsFor(SHARED, undefined, {
+            provider: 'openrouter',
+            fallback: false,
+        });
+
+        expect(attempts).toHaveLength(1);
+        expect(attempts[0]).toMatchObject({ provider: 'openrouter' });
+    });
+
+    it('rejects a pinned provider that has no route for the model', async () => {
+        createMock.mockClear();
+        await expect(
+            withTestActor(() =>
+                driver.complete({
+                    model: SHARED,
+                    provider: 'claude',
+                    fallback: false,
+                    messages: [{ role: 'user', content: 'hi' }],
+                }),
+            ),
+        ).rejects.toMatchObject({ statusCode: 400 });
+        expect(createMock).not.toHaveBeenCalled();
+    });
+
+    it('still marks the failed route for the next caller', async () => {
+        const [only] = await attemptsFor(SHARED, undefined, {
+            fallback: false,
+        });
+
+        expect(isRouteUnhealthy(only.provider, only.model)).toBe(true);
+    });
+
+    it('keeps the chain when fallback is true or unset', async () => {
+        expect(
+            await attemptsFor(SHARED, undefined, { fallback: true }),
+        ).toHaveLength(3);
+        expect(await attemptsFor(SHARED)).toHaveLength(3);
+    });
+});
+
 // Each attempt in a fallback chain is a whole completion at that model's
 // prices, so each one has to clear the credit gate on its own. The chain used
 // to re-check with a nominal 1-microcent amount, which any account with a

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

@@ -709,6 +709,20 @@ export class ChatCompletionDriver extends PuterDriver {
                 legacyCode: 'bad_request',
             });
         }
+        // A pinned provider without a route for the model normally resolves
+        // to another vendor; with `fallback: false` that is the one thing the
+        // caller asked us not to do.
+        if (
+            args.fallback === false &&
+            intendedProvider &&
+            model.provider !== intendedProvider
+        ) {
+            throw new HttpError(
+                400,
+                `Model ${args.model} is not served by provider ${intendedProvider}`,
+                { legacyCode: 'bad_request' },
+            );
+        }
 
         args.messages = normalizeMediaParts(normalize_messages(args.messages));
         if (args.tools) {
@@ -946,8 +960,15 @@ export class ChatCompletionDriver extends PuterDriver {
             const bucketKey = model.id;
             const tried = new Set([routeId(model.provider!, model.id)]);
             let lastError: Error | null = e as Error;
+            // With `fallback: false` the caller wants this route's answer or
+            // its error, not a bill for another provider's attempt.
+            const fallbackAllowed = args.fallback !== false;
 
-            while (lastError && attempts.length < MAX_ATTEMPTS) {
+            while (
+                fallbackAllowed &&
+                lastError &&
+                attempts.length < MAX_ATTEMPTS
+            ) {
                 const fallback = this.#findFallback(bucketKey, tried);
                 if (!fallback) break;
 

src/backend/drivers/ai-chat/providers/alibaba/AlibabaProvider.test.ts

@@ -809,6 +809,11 @@ describe('Alibaba official catalog', () => {
         expect(models.some((model) => model.id === 'qwen-image-fixture')).toBe(
             false,
         );
+        const fixture = models.find(
+            (model) => model.id === 'qwen-catalog-fixture',
+        )!;
+        expect(fixture.puterId).toBe('alibaba:qwen/qwen-catalog-fixture');
+        expect(modelLookupNames(models)).toContain('qwen-catalog-fixture');
         const plus = models.find((model) => model.id === 'qwen-plus')!;
         const original = ALIBABA_MODELS.find(
             (model) => model.id === 'qwen-plus',
@@ -909,6 +914,115 @@ describe('Alibaba official catalog', () => {
         expect(model.costs).toEqual({ tokens: 1_000_000 });
     });
 
+    it.each([
+        ['qwen3.9-plus-2027-01-01', 'alibaba:qwen/qwen3.9-plus-2027-01-01'],
+        ['kimi/kimi-k3', 'alibaba:kimi/kimi-k3'],
+        [
+            'deepseek-v4.1-flash-1017',
+            'alibaba:deepseek/deepseek-v4.1-flash-1017',
+        ],
+        ['glm-5.3-prime', 'alibaba:zhipu/glm-5.3-prime'],
+        ['decision-model-preview', 'alibaba:qwen/decision-model-preview'],
+    ])(
+        'gives uncurated model %s a puterId in the alibaba:<vendor>/<id> form',
+        (id, puterId) => {
+            const model = mapAlibabaCatalogModel({
+                model: id,
+                capabilities: ['TG'],
+            })!;
+            expect(model.puterId).toBe(puterId);
+        },
+    );
+
+    it('skips a vendor-prefixed spelling of a curated model', () => {
+        const model = mapAlibabaCatalogModel({
+            model: 'zhipu/glm-5.2',
+            capabilities: ['TG', 'Reasoning'],
+            inference_metadata: {
+                request_modality: ['Text'],
+                response_modality: ['Text'],
+            },
+        });
+        expect(model).toBeNull();
+    });
+
+    it.each([
+        [
+            'ASR',
+            {
+                capabilities: ['ASR'],
+                inference_metadata: {
+                    request_modality: ['Audio'],
+                    response_modality: ['Text'],
+                },
+            },
+        ],
+        [
+            'rerank',
+            {
+                capabilities: ['TR'],
+                inference_metadata: {
+                    request_modality: ['Text'],
+                    response_modality: ['Text'],
+                },
+            },
+        ],
+        [
+            'image generation',
+            {
+                capabilities: ['IG'],
+                inference_metadata: {
+                    request_modality: ['Text'],
+                    response_modality: ['Text', 'Image'],
+                },
+            },
+        ],
+        [
+            'realtime omni',
+            {
+                capabilities: ['Realtime-Omni'],
+                inference_metadata: {
+                    request_modality: ['Text', 'Image', 'Audio', 'Video'],
+                    response_modality: ['Text', 'Audio'],
+                },
+            },
+        ],
+        [
+            'TTS',
+            {
+                capabilities: ['TTS'],
+                inference_metadata: {
+                    request_modality: ['Audio'],
+                    response_modality: ['Text'],
+                },
+            },
+        ],
+    ])('rejects %s models that cannot serve chat completions', (_kind, raw) => {
+        expect(
+            mapAlibabaCatalogModel({
+                model: 'non-chat-fixture',
+                ...(raw as AlibabaApiModel),
+            }),
+        ).toBeNull();
+    });
+
+    it('admits a vision model', () => {
+        const model = mapAlibabaCatalogModel({
+            model: 'vision-fixture',
+            capabilities: ['VU'],
+            inference_metadata: {
+                request_modality: ['Text', 'Image'],
+                response_modality: ['Text'],
+            },
+        })!;
+        expect(model.modalities?.input).toEqual(['text', 'image']);
+    });
+
+    it('does not admit an uncurated entry without capability or modality data', () => {
+        expect(mapAlibabaCatalogModel({ model: 'mystery-model' })).toBeNull();
+        expect(mapAlibabaCatalogModel({ model: 'qwen-plus' })).not.toBeNull();
+    });
+
     it('refuses inference with unverified catalog prices', async () => {
         seedPages();
         const { provider } = makeProvider();

src/backend/drivers/ai-chat/providers/alibaba/catalog.ts

@@ -82,6 +82,23 @@ const positiveLimit = (value: unknown): number | undefined =>
         ? value
         : undefined;
 
+const chatCapabilities = ['TG', 'Reasoning', 'VU'];
+
+const curatedPuterIds = new Set(ALIBABA_MODELS.map((model) => model.puterId));
+
+const inferPuterId = (id: string): string => {
+    if (id.includes('/')) return `alibaba:${id}`;
+    const family = id.split('-')[0];
+    const sibling = ALIBABA_MODELS.find(
+        (model) => model.puterId && model.id.split('-')[0] === family,
+    );
+    // Unprefixed feed ids are Model Studio's own family unless a curated
+    // sibling points at a third-party org.
+    const org =
+        sibling?.puterId?.slice('alibaba:'.length).split('/')[0] ?? 'qwen';
+    return `alibaba:${org}/${id}`;
+};
+
 export const mapAlibabaCatalogModel = (
     raw: AlibabaApiModel,
     previous?: IChatModel,
@@ -90,16 +107,25 @@ export const mapAlibabaCatalogModel = (
     const id = raw.model.trim();
     const existing =
         previous ?? ALIBABA_MODELS.find((model) => model.id === id);
+    const input = raw.inference_metadata?.request_modality;
     const output = raw.inference_metadata?.response_modality;
-    if (output && !output.includes('Text')) return null;
     if (
-        !output &&
-        !existing &&
-        !raw.capabilities?.some((capability) =>
-            ['TG', 'Reasoning', 'VU'].includes(capability),
+        raw.capabilities &&
+        !raw.capabilities.some((capability) =>
+            chatCapabilities.includes(capability),
         )
     )
         return null;
+    if (input && !input.includes('Text')) return null;
+    if (output && !output.includes('Text')) return null;
+    if (!raw.capabilities && !input && !output && !existing) return null;
+    let puterId = existing?.puterId;
+    if (!puterId) {
+        puterId = inferPuterId(id);
+        // A feed entry spelling a curated model differently would duplicate
+        // the curated entry's puterId and list the model twice.
+        if (curatedPuterIds.has(puterId)) return null;
+    }
     const catalogPricing: AlibabaCatalogTier[] = (raw.prices ?? []).map(
         (tier) => {
             // Abbreviated ranges do not specify whether k means 1000 or 1024 tokens.
@@ -149,6 +175,7 @@ export const mapAlibabaCatalogModel = (
     return {
         ...existing,
         id,
+        puterId,
         name: raw.name ?? existing?.name ?? id,
         description: raw.description ?? existing?.description,
         aliases: existing?.aliases,

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

@@ -177,6 +177,7 @@ describe('OpenAiChatProvider model catalog', () => {
         expect(ids).toContain('gpt-5.2-2025-12-11');
         expect(ids).toContain('gpt-6-astra');
         expect(ids).toContain('gpt-6.1-sol');
+        expect(ids).toContain('gpt-6.1-terra');
         expect(ids).toContain('gpt-6-sol');
         expect(ids).toContain('gpt-6-luna');
     });
@@ -348,30 +349,33 @@ describe('OpenAiChatProvider.complete request shape', () => {
         expect(args.safety_identifier).toBe('puter-u42');
     });
 
-    it.each(['gpt-6-astra', 'gpt-6.1-sol', 'gpt-6-sol', 'gpt-6-luna'])(
-        'resolves the namespaced %s alias',
-        async (model) => {
-            const { provider } = makeProvider();
-            createMock.mockResolvedValueOnce(baseCompletion);
+    it.each([
+        'gpt-6-astra',
+        'gpt-6.1-sol',
+        'gpt-6.1-terra',
+        'gpt-6-sol',
+        'gpt-6-luna',
+    ])('resolves the namespaced %s alias', async (model) => {
+        const { provider } = makeProvider();
+        createMock.mockResolvedValueOnce(baseCompletion);
 
-            await withTestActor(() =>
-                provider.complete({
-                    model: `openai/${model}`,
-                    messages: [{ role: 'user', content: 'hello' }],
-                    reasoning_effort: 'low',
-                }),
-            );
+        await withTestActor(() =>
+            provider.complete({
+                model: `openai/${model}`,
+                messages: [{ role: 'user', content: 'hello' }],
+                reasoning_effort: 'low',
+            }),
+        );
 
-            expect(createMock.mock.calls[0]![0].model).toBe(model);
-            expect(createMock.mock.calls[0]![0].reasoning_effort).toBe('low');
-            expect(recordSpy).toHaveBeenCalledWith(
-                expect.any(Object),
-                expect.anything(),
-                `openai:${model}`,
-                expect.any(Object),
-            );
-        },
-    );
+        expect(createMock.mock.calls[0]![0].model).toBe(model);
+        expect(createMock.mock.calls[0]![0].reasoning_effort).toBe('low');
+        expect(recordSpy).toHaveBeenCalledWith(
+            expect.any(Object),
+            expect.anything(),
+            `openai:${model}`,
+            expect.any(Object),
+        );
+    });
 
     it('omits parallel_tool_calls/tool_choice when no tool is sent (Chat Completions rejects them alone)', async () => {
         const { provider } = makeProvider();

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

@@ -224,6 +224,7 @@ describe('OpenAiResponsesChatProvider model catalog', () => {
     });
 
     it.each([
+        ['gpt-6.1-terra', '2026-06-01', '2026-10-26', 100, 5, 500],
         ['gpt-6.1-sol', '2026-04-30', '2026-09-29', 200, 10, 1000],
         ['gpt-6-sol', '2026-04-20', '2026-09-22', 200, 20, 1000],
         ['gpt-6-luna', '2026-05-18', '2026-09-22', 10, 1, 50],
@@ -244,6 +245,7 @@ describe('OpenAiResponsesChatProvider model catalog', () => {
                     tokens: 1_000_000,
                     prompt_tokens: input,
                     cached_tokens: cached,
+                    cache_write_tokens: input * 1.25,
                     completion_tokens: output,
                 },
                 context: 1_050_000,
@@ -332,6 +334,7 @@ describe('OpenAiResponsesChatProvider.complete request shape', () => {
         'gpt-6-luna',
         'gpt-6-astra',
         'gpt-6.1-sol',
+        'gpt-6.1-terra',
         'gpt-5.6',
         'openai/gpt-5.6',
         'openai/gpt-5.6-luna',
@@ -367,7 +370,7 @@ describe('OpenAiResponsesChatProvider.complete request shape', () => {
         },
     );
 
-    it.each(['gpt-5.6-luna', 'gpt-6-luna'])(
+    it.each(['gpt-5.6-luna', 'gpt-6-luna', 'gpt-6.1-terra'])(
         'preserves sampling with reasoning disabled for %s',
         async (model) => {
             const { provider } = makeProvider();
@@ -620,7 +623,13 @@ describe('OpenAiResponsesChatProvider.complete request shape', () => {
         expect(gpt41Args).not.toHaveProperty('verbosity');
     });
 
-    it.each(['gpt-6-astra', 'gpt-6.1-sol', 'gpt-6-sol', 'gpt-6-luna'])(
+    it.each([
+        'gpt-6-astra',
+        'gpt-6.1-sol',
+        'gpt-6.1-terra',
+        'gpt-6-sol',
+        'gpt-6-luna',
+    ])(
         'maps flat controls to Responses options for %s aliases',
         async (model) => {
             const { provider } = makeProvider();
@@ -860,47 +869,51 @@ describe('OpenAiResponsesChatProvider.complete non-stream output', () => {
         });
     });
 
-    it('bills the whole request at long-context rates past 272K input tokens', async () => {
-        const sol = OPEN_AI_MODELS.find((m) => m.id === 'gpt-6-sol')!;
-        const { provider } = makeProvider();
-        responsesCreateMock.mockResolvedValueOnce({
-            output: [{ role: 'assistant' }],
-            output_text: 'hi',
-            usage: {
-                input_tokens: 300_000,
-                output_tokens: 10_000,
-                input_tokens_details: {
-                    cached_tokens: 50_000,
-                    cache_write_tokens: 20_000,
+    it.each([
+        ['gpt-6-sol', 119],
+        ['gpt-6.1-terra', 59],
+    ] as const)(
+        'bills %s at long-context rates past 272K input tokens',
+        async (modelId, total) => {
+            const model = OPEN_AI_MODELS.find((m) => m.id === modelId)!;
+            const { provider } = makeProvider();
+            responsesCreateMock.mockResolvedValueOnce({
+                output: [{ role: 'assistant' }],
+                output_text: 'hi',
+                usage: {
+                    input_tokens: 300_000,
+                    output_tokens: 10_000,
+                    input_tokens_details: {
+                        cached_tokens: 50_000,
+                        cache_write_tokens: 20_000,
+                    },
                 },
-            },
-        });
+            });
 
-        await withTestActor(() =>
-            provider.complete({
-                model: 'gpt-6-sol',
-                messages: [{ role: 'user', content: 'hi' }],
-            }),
-        );
+            await withTestActor(() =>
+                provider.complete({
+                    model: modelId,
+                    messages: [{ role: 'user', content: 'hi' }],
+                }),
+            );
 
-        const [, , , overrides] = recordSpy.mock.calls[0]!;
-        // $0.92 + $0.02 + $0.10 + $0.15 = $1.19, against $0.62 at the
-        // standard rates.
-        expect(overrides).toEqual({
-            prompt_tokens: 230_000 * Number(sol.costs.prompt_tokens) * 2,
-            cached_tokens: 50_000 * Number(sol.costs.cached_tokens) * 2,
-            cache_write_tokens:
-                20_000 * Number(sol.costs.cache_write_tokens) * 2,
-            completion_tokens:
-                10_000 * Number(sol.costs.completion_tokens) * 1.5,
-        });
-        const totalCents =
-            Object.values(overrides as Record<string, number>).reduce(
-                (a, b) => a + b,
-                0,
-            ) / 1_000_000;
-        expect(totalCents).toBeCloseTo(119);
-    });
+            const [, , , overrides] = recordSpy.mock.calls[0]!;
+            expect(overrides).toEqual({
+                prompt_tokens: 230_000 * Number(model.costs.prompt_tokens) * 2,
+                cached_tokens: 50_000 * Number(model.costs.cached_tokens) * 2,
+                cache_write_tokens:
+                    20_000 * Number(model.costs.cache_write_tokens) * 2,
+                completion_tokens:
+                    10_000 * Number(model.costs.completion_tokens) * 1.5,
+            });
+            const totalCents =
+                Object.values(overrides as Record<string, number>).reduce(
+                    (a, b) => a + b,
+                    0,
+                ) / 1_000_000;
+            expect(totalCents).toBeCloseTo(total);
+        },
+    );
 
     it('bills cached tokens at the input rate when the model prices no cache read', async () => {
         // gpt-5.4-pro is responses-API-only and its catalogue entry has no

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

@@ -31,6 +31,31 @@ const GPT_LONG_CONTEXT_PRICING = {
 
 // Hardcoded from https://models.dev/api.json
 export const OPEN_AI_MODELS: IChatModel[] = [
+    {
+        puterId: 'openai:openai/gpt-6.1-terra',
+        id: 'gpt-6.1-terra',
+        responsesSampling: 'reasoningDisabled',
+        modalities: { input: ['text', 'image'], output: ['text'] },
+        open_weights: false,
+        tool_call: true,
+        knowledge: '2026-06-01',
+        release_date: '2026-10-26',
+        aliases: ['openai/gpt-6.1-terra'],
+        costs_currency: 'usd-cents',
+        input_cost_key: 'prompt_tokens',
+        output_cost_key: 'completion_tokens',
+        costs: {
+            tokens: 1_000_000,
+            prompt_tokens: 100,
+            cached_tokens: 5,
+            cache_write_tokens: 100 * 1.25,
+            completion_tokens: 500,
+        },
+        long_context_pricing: GPT_LONG_CONTEXT_PRICING,
+        context: 1_050_000,
+        max_tokens: 128_000,
+        responses_api: true,
+    },
     {
         puterId: 'openai:openai/gpt-6.1-sol',
         id: 'gpt-6.1-sol',

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

@@ -175,6 +175,11 @@ export interface UsageDetails {
 export interface ICompleteArguments {
     messages: PuterMessage[];
     provider?: string;
+    /**
+     * `false` makes the first route's failure final instead of retrying the
+     * request on another provider that serves the same model.
+     */
+    fallback?: boolean;
     stream?: boolean;
     model: string;
     test_mode?: boolean;

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

@@ -289,6 +289,9 @@ describe('clampReasoningEffort', () => {
         ['gpt-5.5', 'max', 'xhigh'],
         ['gpt-5', 'high', 'high'],
         ['gpt-6-astra-1', 'none', 'low'],
+        ...(['none', 'low', 'medium', 'high', 'xhigh', 'max'] as const).map(
+            (effort) => ['gpt-6.1-terra', effort, effort] as const,
+        ),
     ] as const)(
         'clamps %s requesting %s to %s',
         (modelId, requested, expected) => {

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

@@ -39,9 +39,49 @@ describe('estimateTextTokens', () => {
         const long = estimateTextTokens('hello world '.repeat(100));
         expect(long).toBeGreaterThan(short);
     });
+
+    it('counts words the way splitting on \\s+ does', () => {
+        const splitEstimate = (text: string) =>
+            Math.floor(
+                (text.length / 4 + text.split(/\s+/).length * (4 / 3)) / 2,
+            );
+        for (const text of [
+            'a',
+            ' a',
+            'a ',
+            '  a  b\t\nc  ',
+            'x y z w 

  　v',
+            'é ü 日本語 テキスト',
+            '\r\n\v\f',
+        ]) {
+            expect(estimateTextTokens(text), JSON.stringify(text)).toBe(
+                splitEstimate(text),
+            );
+        }
+    });
+
+    it('gives text past the scan budget the word density scanned so far', () => {
+        const text = 'ab cd '.repeat(1000);
+        const budget = { chars: 12, scannedChars: 0, scannedRuns: 0 };
+        // Uniform text extrapolates to the full count.
+        expect(estimateTextTokens(text, budget)).toBe(estimateTextTokens(text));
+        expect(budget.chars).toBe(0);
+        // A later part with no budget left takes the same density.
+        expect(estimateTextTokens(text, budget)).toBe(estimateTextTokens(text));
+    });
 });
 
 describe('estimatePromptTokens', () => {
+    it('scans a bounded amount of text per prompt', () => {
+        // Many parts, each under the budget alone, past it together; the
+        // unscanned ones are extrapolated, which is exact for uniform text.
+        const part = 'lorem ipsum dolor '.repeat(30_000);
+        const parts = Array.from({ length: 8 }, () => ({ text: part }));
+        expect(estimatePromptTokens([{ role: 'user', content: parts }])).toBe(
+            8 * estimateTextTokens(part),
+        );
+    });
+
     it('counts plain string content', () => {
         const tokens = estimatePromptTokens([
             { role: 'user', content: 'a fairly ordinary sentence to price' },

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

@@ -29,7 +29,11 @@
  * passes every gate.
  */
 
-import { estimateTextTokens } from '../../util/tokenEstimate.js';
+import {
+    createWordScanBudget,
+    estimateTextTokens,
+    type WordScanBudget,
+} from '../../util/tokenEstimate.js';
 
 // Re-exported so existing consumers keep one import site for all estimators.
 export { estimateTextTokens } from '../../util/tokenEstimate.js';
@@ -91,23 +95,25 @@ const attachmentTokens = (value: unknown): number => {
  * recognises is charged the unmeasured estimate — the alternative is a content
  * type nobody has taught the gate about arriving for free.
  */
-const partTokens = (part: unknown): number => {
-    if (typeof part === 'string') return estimateTextTokens(part);
+const partTokens = (part: unknown, budget: WordScanBudget): number => {
+    if (typeof part === 'string') return estimateTextTokens(part, budget);
     if (!part || typeof part !== 'object') return 0;
 
     const p = part as ContentPart;
 
-    if (typeof p.text === 'string') return estimateTextTokens(p.text);
+    if (typeof p.text === 'string') return estimateTextTokens(p.text, budget);
 
     // Model-output shapes replayed as history: Anthropic thinking blocks,
     // our own streamed `reasoning` chunks, OpenAI refusals. All text — they
     // must not fall through to the attachment default below, which would
     // price a few sentences of reasoning like a full-frame image.
-    if (typeof p.thinking === 'string') return estimateTextTokens(p.thinking);
+    if (typeof p.thinking === 'string')
+        return estimateTextTokens(p.thinking, budget);
     if (typeof p.reasoning === 'string') {
-        return estimateTextTokens(p.reasoning);
+        return estimateTextTokens(p.reasoning, budget);
     }
-    if (typeof p.refusal === 'string') return estimateTextTokens(p.refusal);
+    if (typeof p.refusal === 'string')
+        return estimateTextTokens(p.refusal, budget);
 
     // OpenAI-style `{ image_url: { url } }` (or the flattened string form).
     if (p.image_url) {
@@ -136,6 +142,7 @@ const partTokens = (part: unknown): number => {
     if (p.type === 'tool_use' && p.input !== undefined) {
         return estimateTextTokens(
             typeof p.input === 'string' ? p.input : JSON.stringify(p.input),
+            budget,
         );
     }
     if (p.type === 'tool_result') {
@@ -143,10 +150,11 @@ const partTokens = (part: unknown): number => {
             typeof p.content === 'string'
                 ? p.content
                 : JSON.stringify(p.content ?? ''),
+            budget,
         );
     }
     if (p.type === 'compaction') {
-        return estimateTextTokens(String(p.encrypted_content ?? ''));
+        return estimateTextTokens(String(p.encrypted_content ?? ''), budget);
     }
 
     return UNMEASURED_ATTACHMENT_TOKENS;
@@ -164,21 +172,22 @@ const partTokens = (part: unknown): number => {
 export const estimatePromptTokens = (messages: unknown): number => {
     if (!Array.isArray(messages)) return 0;
 
+    const budget = createWordScanBudget();
     let tokens = 0;
     for (const message of messages) {
         if (typeof message === 'string') {
-            tokens += estimateTextTokens(message);
+            tokens += estimateTextTokens(message, budget);
             continue;
         }
         if (!message || typeof message !== 'object') continue;
 
         const content = (message as ContentPart).content;
         if (typeof content === 'string') {
-            tokens += estimateTextTokens(content);
+            tokens += estimateTextTokens(content, budget);
         } else if (Array.isArray(content)) {
-            for (const part of content) tokens += partTokens(part);
+            for (const part of content) tokens += partTokens(part, budget);
         } else if (content) {
-            tokens += partTokens(content);
+            tokens += partTokens(content, budget);
         }
     }
     return tokens;

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

@@ -339,13 +339,16 @@ export class ImageGenerationDriver extends PuterDriver {
         );
 
         if (resolvedOutputPath) {
-            await saveGeneratedMediaToFS(
+            // False when write access was revoked while the job ran; the
+            // result still comes back.
+            const outputSaved = await saveGeneratedMediaToFS(
                 this.services.fs,
                 actor,
                 result,
                 resolvedOutputPath,
                 { noun: 'image', defaultType: 'application/octet-stream' },
             );
+            Context.set('driverMetadata', { outputSaved });
         }
 
         return result;

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

@@ -37,6 +37,7 @@ import {
     type MockInstance,
 } from 'vitest';
 
+import { Context } from '../../../../core/context.js';
 import type { MeteringService } from '../../../../services/metering/MeteringService.js';
 import { PuterServer } from '../../../../server.js';
 import { setupTestServer } from '../../../../testUtil.js';
@@ -349,3 +350,55 @@ describe('KlingImageProvider billing', () => {
         expect(incrementUsageSpy).not.toHaveBeenCalled();
     });
 });
+
+// -- After the caller leaves -----------------------------------------
+
+describe('KlingImageProvider after the caller leaves', () => {
+    it('keeps polling after a disconnect and meters the finished image', async () => {
+        mockFlow(envelope(task('processing')), envelope(succeeded));
+        const url = await withTestActor(() => {
+            const abort = new AbortController();
+            abort.abort();
+            Context.set('abortSignal', abort.signal);
+            return makeProvider().generate({ prompt: 'a red apple' });
+        });
+        expect(url).toBe('https://kling.example/1.png');
+        expect(incrementUsageSpy).toHaveBeenCalledTimes(1);
+    });
+
+    it('meters an image that finishes after the window', async () => {
+        fetchSpy.mockResolvedValueOnce(envelope(task('submitted')));
+        const realNow = Date.now.bind(Date);
+        let skew = 0;
+        vi.spyOn(Date, 'now').mockImplementation(() => realNow() + skew);
+        let finished = false;
+        fetchSpy.mockImplementation(async () => {
+            skew = 6 * 60 * 1000;
+            return finished
+                ? envelope(succeeded)
+                : envelope(task('processing'));
+        });
+
+        let failure: unknown;
+        try {
+            await generate({ model: 'kling-v3-omni', quality: '4k' });
+        } catch (e) {
+            failure = e;
+        }
+        expect(failure).toMatchObject({
+            statusCode: 504,
+            legacyCode: 'upstream_timeout',
+            message: 'Timed out waiting for Kling image generation to complete',
+        });
+        expect(incrementUsageSpy).not.toHaveBeenCalled();
+
+        finished = true;
+        await vi.waitFor(() =>
+            expect(incrementUsageSpy).toHaveBeenCalledTimes(1),
+        );
+        const [, usageType, amount, cost] = incrementUsageSpy.mock.calls[0]!;
+        expect(usageType).toBe('kling-image-generation:kling-v3-omni:4k');
+        expect(amount).toBe(1);
+        expect(cost).toBe(5.6 * 1_000_000);
+    });
+});

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

@@ -24,9 +24,12 @@ import type { AiMeteringService } from '../../../util/aiCostFactor.js';
 import { klingImageInput, klingRequest } from '../../../util/kling.js';
 import {
     CONTENT_FILTER_PATTERN,
-    isTransientUpstreamError,
     sanitizeUpstreamMessage,
 } from '../../../util/upstreamErrors.js';
+import {
+    JobHold,
+    pollUntilSettled,
+} from '../../../ai-video/providers/polling.js';
 import {
     closestAspectRatio,
     formatAspectRatio,
@@ -145,6 +148,7 @@ export class KlingImageProvider implements IImageProvider {
         );
         if (!hold) throw insufficientCreditsError();
 
+        const jobHold = new JobHold(hold);
         try {
             const aspectRatio = params.imageSize
                 ? formatAspectRatio(
@@ -184,7 +188,35 @@ export class KlingImageProvider implements IImageProvider {
                 path,
                 { body, baseUrl: this.#baseUrl },
             );
-            const task = await this.#pollUntilSettled(path, created);
+            // Billed per image; a failed task isn't.
+            const task = await pollUntilSettled<KlingImageTask>({
+                provider: 'kling',
+                providerLabel: 'Kling',
+                noun: 'image',
+                intervalMs: this.#pollIntervalMs,
+                windowMs: POLL_WINDOW_MS,
+                initial: created,
+                fetch: () =>
+                    klingRequest<KlingImageTask>(
+                        this.#apiKey,
+                        'GET',
+                        `${path}/${encodeURIComponent(created.task_id)}`,
+                        { baseUrl: this.#baseUrl },
+                    ),
+                isPending: (task) =>
+                    task.task_status === 'submitted' ||
+                    task.task_status === 'processing',
+                meter: async (task, settled) => {
+                    if (settled && task?.task_status !== 'succeed') return;
+                    await this.#meteringService.incrementUsage(
+                        actor,
+                        usageType,
+                        1,
+                        Math.round(cents * 1_000_000),
+                    );
+                },
+                hold: jobHold,
+            });
             if (task.task_status !== 'succeed') {
                 throw this.#taskFailure(task.task_status_msg);
             }
@@ -192,68 +224,12 @@ export class KlingImageProvider implements IImageProvider {
             if (!url) {
                 throw new Error('Kling response did not include an image URL');
             }
-
-            await this.#meteringService.incrementUsage(
-                actor,
-                usageType,
-                1,
-                Math.round(cents * 1_000_000),
-            );
             return url;
         } finally {
-            await hold.release();
+            await jobHold.release();
         }
     }
 
-    async #pollUntilSettled(
-        path: string,
-        created: KlingImageTask,
-    ): Promise<KlingImageTask> {
-        const signal = Context.get('abortSignal') as AbortSignal | undefined;
-        const deadline = Date.now() + POLL_WINDOW_MS;
-        let task = created;
-        while (
-            task.task_status === 'submitted' ||
-            task.task_status === 'processing'
-        ) {
-            if (signal?.aborted) {
-                throw new HttpError(
-                    400,
-                    'Client disconnected before image generation finished',
-                    {
-                        legacyCode: 'client_aborted',
-                        fields: { provider: 'kling' },
-                    },
-                );
-            }
-            if (Date.now() > deadline) {
-                throw new HttpError(
-                    504,
-                    'Timed out waiting for Kling image generation to complete',
-                    {
-                        legacyCode: 'upstream_timeout',
-                        fields: { provider: 'kling' },
-                    },
-                );
-            }
-            await new Promise((resolve) =>
-                setTimeout(resolve, this.#pollIntervalMs),
-            );
-            try {
-                task = await klingRequest<KlingImageTask>(
-                    this.#apiKey,
-                    'GET',
-                    `${path}/${encodeURIComponent(created.task_id)}`,
-                    { baseUrl: this.#baseUrl },
-                );
-            } catch (err) {
-                // A missed poll is not a failed task.
-                if (!isTransientUpstreamError(err)) throw err;
-            }
-        }
-        return task;
-    }
-
     /**
      * A content-policy refusal is the caller's to act on; anything else
      * Kling's.

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

@@ -47,7 +47,13 @@ import { PuterServer } from '../../server.js';
 import type { MeteringService } from '../../services/metering/MeteringService.js';
 import { setupTestServer } from '../../testUtil.js';
 import { generateDefaultFsentries } from '../../util/userProvisioning.js';
-import type { VoiceChangerDriver } from './VoiceChangerDriver.js';
+import type { DriverStreamResult } from '../meta.js';
+import {
+    OggOpusClock,
+    outputBytesPerSecond,
+    type VoiceChangerDriver,
+    wavDataOffset,
+} from './VoiceChangerDriver.js';
 import {
     callerError,
     readStreamResult,
@@ -330,11 +336,11 @@ describe('VoiceChangerDriver.convert success path', () => {
 
     it('meters one usage line at the per-second rate from costs.ts', async () => {
         const { actor } = await makeUser();
+        // 32 KB of mp3_44100_128 back = 2 seconds.
         fetchSpy.mockResolvedValueOnce(
-            okResponse(new ArrayBuffer(8), 'audio/mpeg'),
+            okResponse(new ArrayBuffer(32_000), 'audio/mpeg'),
         );
 
-        // 32 KB audio at 16 kbit/s = 2 seconds rounded up.
         const buf = Buffer.alloc(32_000);
         await readStreamResult(
             await withActor(actor, () =>
@@ -344,7 +350,7 @@ describe('VoiceChangerDriver.convert success path', () => {
 
         const usageType = 'elevenlabs:eleven_multilingual_sts_v2:second';
         const perSecond = VOICE_CHANGER_COSTS[usageType];
-        const expectedSeconds = Math.max(1, Math.ceil(32_000 / 16000));
+        const expectedSeconds = 2;
 
         const calls = incrementUsageSpy.mock.calls.filter(
             ([, type]) => type === usageType,
@@ -365,7 +371,7 @@ describe('VoiceChangerDriver.convert success path', () => {
                 .map(([, , , cost]) => cost);
         const convert = async (charges: number) => {
             fetchSpy.mockResolvedValueOnce(
-                okResponse(new ArrayBuffer(8), 'audio/mpeg'),
+                okResponse(new ArrayBuffer(32_000), 'audio/mpeg'),
             );
             await readStreamResult(
                 await withActor(actor, () =>
@@ -385,6 +391,230 @@ describe('VoiceChangerDriver.convert success path', () => {
         expect(held).toEqual([base, base! * 2]);
     });
 
+    it.each<[string, number]>([
+        ['mp3_44100_128', 16_000],
+        ['mp3_22050_32', 4_000],
+        ['opus_48000_64', 8_000],
+        ['pcm_44100', 88_200],
+        ['ulaw_8000', 8_000],
+        ['wav_44100', 88_200],
+        ['mp3_44100_999999', 16_000],
+        ['flac_44100', 16_000],
+    ])('sizes %s at %s bytes per second', (format, bytes) => {
+        expect(outputBytesPerSecond(format)).toBe(bytes);
+    });
+
+    /** A 16-bit mono WAV header, with an optional LIST chunk before data. */
+    const wavHeader = (sampleRate: number, dataBytes: number, list = 0) => {
+        const listChunk = list
+            ? Buffer.concat([
+                  Buffer.from('LIST'),
+                  Buffer.from(new Uint32Array([list]).buffer),
+                  Buffer.alloc(list),
+              ])
+            : Buffer.alloc(0);
+        const fmt = Buffer.alloc(24);
+        fmt.write('fmt ', 0, 'ascii');
+        fmt.writeUInt32LE(16, 4);
+        fmt.writeUInt16LE(1, 8);
+        fmt.writeUInt16LE(1, 10);
+        fmt.writeUInt32LE(sampleRate, 12);
+        fmt.writeUInt32LE(sampleRate * 2, 16);
+        fmt.writeUInt16LE(2, 20);
+        fmt.writeUInt16LE(16, 22);
+        const data = Buffer.alloc(8);
+        data.write('data', 0, 'ascii');
+        data.writeUInt32LE(dataBytes, 4);
+        const body = Buffer.concat([fmt, listChunk, data]);
+        const riff = Buffer.alloc(12);
+        riff.write('RIFF', 0, 'ascii');
+        riff.writeUInt32LE(4 + body.length + dataBytes, 4);
+        riff.write('WAVE', 8, 'ascii');
+        return Buffer.concat([riff, body]);
+    };
+
+    it("finds where a WAV stream's samples start", () => {
+        expect(wavDataOffset(wavHeader(16_000, 0))).toBe(44);
+        expect(wavDataOffset(wavHeader(16_000, 0, 26))).toBe(78);
+        expect(wavDataOffset(wavHeader(16_000, 0).subarray(0, 40))).toBe(
+            undefined,
+        );
+        expect(wavDataOffset(Buffer.alloc(64))).toBe(undefined);
+    });
+
+    /** One Ogg page carrying `body` as a single packet. */
+    const oggPage = (granule: bigint, sequence: number, body: Buffer) => {
+        const lacing: number[] = [];
+        let left = body.length;
+        while (left >= 255) {
+            lacing.push(255);
+            left -= 255;
+        }
+        lacing.push(left);
+        const header = Buffer.alloc(27);
+        header.write('OggS', 0, 'ascii');
+        header.writeBigUInt64LE(granule, 6);
+        header.writeUInt32LE(sequence, 18);
+        header[26] = lacing.length;
+        return Buffer.concat([header, Buffer.from(lacing), body]);
+    };
+
+    /** A sparse Ogg Opus stream: `seconds` of audio in very few bytes. */
+    const oggOpus = (seconds: number, preSkip = 312) => {
+        const opusHead = Buffer.alloc(19);
+        opusHead.write('OpusHead', 0, 'ascii');
+        opusHead[8] = 1;
+        opusHead[9] = 1;
+        opusHead.writeUInt16LE(preSkip, 10);
+        opusHead.writeUInt32LE(48_000, 12);
+        const pages = [
+            oggPage(0n, 0, opusHead),
+            oggPage(0n, 1, Buffer.from('OpusTags')),
+        ];
+        for (let s = 1; s <= seconds; s++) {
+            pages.push(
+                oggPage(BigInt(preSkip + s * 48_000), s + 1, Buffer.alloc(300)),
+            );
+        }
+        return Buffer.concat(pages);
+    };
+
+    it('times an Ogg Opus stream by its last granule, however it is chunked', () => {
+        const stream = oggOpus(7);
+        const whole = new OggOpusClock();
+        whole.push(stream);
+        expect(whole.seconds).toBe(7);
+
+        const trickle = new OggOpusClock();
+        for (const byte of stream) trickle.push(Buffer.from([byte]));
+        expect(trickle.seconds).toBe(7);
+    });
+
+    it('does not time a stream that is not Ogg Opus', () => {
+        const clock = new OggOpusClock();
+        clock.push(Buffer.alloc(4096, 1));
+        expect(clock.seconds).toBe(undefined);
+    });
+
+    describe('meters the length of the audio that comes back', () => {
+        const usageType = 'elevenlabs:eleven_multilingual_sts_v2:second';
+        const billed = async () => {
+            await vi.waitFor(() =>
+                expect(
+                    incrementUsageSpy.mock.calls.filter(
+                        ([, type]) => type === usageType,
+                    ),
+                ).toHaveLength(1),
+            );
+            const [, , count, cost] = incrementUsageSpy.mock.calls.find(
+                ([, type]) => type === usageType,
+            )!;
+            expect(cost).toBe(VOICE_CHANGER_COSTS[usageType]! * count);
+            return count;
+        };
+        const convert = async (
+            actor: Actor,
+            inputBytes: number,
+            args: Record<string, unknown> = {},
+        ) =>
+            readStreamResult(
+                await withActor(actor, () =>
+                    driver.convert({
+                        audio: dataUrl(Buffer.alloc(inputBytes), 'audio/ogg'),
+                        ...args,
+                    }),
+                ),
+            );
+
+        it('bills 600 s for a compact 600 s clip, not its byte size', async () => {
+            const { actor } = await makeUser();
+            // 600 s of Opus at 8 kbps in; 600 s of mp3_44100_128 out.
+            fetchSpy.mockResolvedValueOnce(
+                okResponse(new ArrayBuffer(600 * 16_000)),
+            );
+            await convert(actor, 441_078);
+            expect(await billed()).toBe(600);
+        });
+
+        it('sizes the output by the requested output_format', async () => {
+            const { actor } = await makeUser();
+            // pcm_16000 is 16-bit mono: 32,000 bytes per second.
+            fetchSpy.mockResolvedValueOnce(
+                okResponse(new ArrayBuffer(3 * 32_000), 'audio/pcm'),
+            );
+            await convert(actor, 1_000_000, { output_format: 'pcm_16000' });
+            expect(await billed()).toBe(3);
+        });
+
+        it('does not bill a WAV header as audio', async () => {
+            const { actor } = await makeUser();
+            // 3 s of wav_16000 is 96,000 bytes of samples plus its header.
+            fetchSpy.mockResolvedValueOnce(
+                okResponse(
+                    new Uint8Array(
+                        Buffer.concat([
+                            wavHeader(16_000, 3 * 32_000, 26),
+                            Buffer.alloc(3 * 32_000),
+                        ]),
+                    ).buffer,
+                    'audio/wav',
+                ),
+            );
+            await convert(actor, 1_000_000, { output_format: 'wav_16000' });
+            expect(await billed()).toBe(3);
+        });
+
+        it('bills sparse Opus output by its duration, not its bytes', async () => {
+            const { actor } = await makeUser();
+            // 20 s of mostly silent opus_48000_64 is far under 20 s of bytes.
+            const body = oggOpus(20);
+            expect(body.length).toBeLessThan(8_000 * 2);
+            fetchSpy.mockResolvedValueOnce(
+                okResponse(new Uint8Array(body).buffer, 'audio/ogg'),
+            );
+            await convert(actor, 1_000, { output_format: 'opus_48000_64' });
+            expect(await billed()).toBe(20);
+        });
+
+        it('sizes an undocumented output_format as the default', async () => {
+            const { actor } = await makeUser();
+            // 3 s at the default mp3_44100_128.
+            fetchSpy.mockResolvedValueOnce(
+                okResponse(new ArrayBuffer(3 * 16_000)),
+            );
+            await convert(actor, 1_000_000, {
+                output_format: 'mp3_44100_999999',
+            });
+            expect(await billed()).toBe(3);
+        });
+
+        it('charges at least the input estimate when the caller hangs up', async () => {
+            const { actor } = await makeUser();
+            fetchSpy.mockResolvedValueOnce(
+                new Response(
+                    new ReadableStream({
+                        start(controller) {
+                            controller.enqueue(new Uint8Array(16_000));
+                        },
+                    }),
+                    { status: 200, headers: { 'content-type': 'audio/mpeg' } },
+                ),
+            );
+            const result = (await withActor(actor, () =>
+                driver.convert({
+                    audio: dataUrl(Buffer.alloc(80_000), 'audio/mpeg'),
+                }),
+            )) as DriverStreamResult;
+            for await (const _chunk of result.stream) break;
+            expect(await billed()).toBe(5);
+            await vi.waitFor(async () =>
+                expect(
+                    await server.stores.creditHold.outstanding(actor.user.uuid),
+                ).toBe(0),
+            );
+        });
+    });
+
     it('meters nothing when ElevenLabs breaks off before any audio', async () => {
         const { actor } = await makeUser();
         fetchSpy.mockResolvedValueOnce(

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

@@ -17,9 +17,11 @@
  * along with this program.  If not, see <https://www.gnu.org/licenses/>.
  */
 
+import { pipeline, Readable, Transform } from 'node:stream';
 import { Context } from '../../core/context.js';
 import { HttpError } from '../../core/http/HttpError.js';
 import type { DriverStreamResult } from '../meta.js';
+import { OUTPUT_FORMATS } from '../ai-tts/providers/elevenlabs/ElevenLabsTTSProvider.js';
 import { PuterDriver } from '../types.js';
 import {
     type AiMeteringService,
@@ -198,10 +200,9 @@ export class VoiceChangerDriver extends PuterDriver {
                 legacyCode: 'bad_request',
             });
 
-        // Metering: estimate duration from file size if we don't parse metadata.
-        // 16 kbit/s is a safe lower bound for speech audio; pre-check credits
-        // before we hit the ElevenLabs API. Post-usage we increment by the same
-        // estimate — duration parsing is deferred to v2.1 if needed.
+        // The hold estimates seconds from the input at 128 kbps: compact audio
+        // is under-held rather than refused. Usage is metered from the length
+        // of the audio that comes back.
         const estimatedSeconds = Math.max(
             1,
             Math.ceil(loaded.buffer.byteLength / 16000),
@@ -263,6 +264,10 @@ export class VoiceChangerDriver extends PuterDriver {
         if (search) url.search = search;
 
         const metering = this.#aiMetering;
+        const output = measuredOutput(
+            outputBytesPerSecond(outputFormat),
+            outputFormat,
+        );
         return withStreamedAiCharge(
             metering,
             actor,
@@ -287,16 +292,206 @@ export class VoiceChangerDriver extends PuterDriver {
                     dataType: 'stream',
                     content_type:
                         response.headers.get('content-type') ?? 'audio/mpeg',
-                    stream: upstreamBodyStream(response),
+                    stream: output.measure(upstreamBodyStream(response)),
                 };
             },
-            () =>
-                metering.incrementUsage(
+            async () => {
+                const measured = await output.seconds;
+                // A stream cut short was still converted in full upstream.
+                const seconds =
+                    measured.complete && measured.seconds
+                        ? measured.seconds
+                        : Math.max(measured.seconds ?? 0, estimatedSeconds);
+                return metering.incrementUsage(
                     actor,
                     usageKey,
-                    estimatedSeconds,
-                    estimatedCost,
-                ),
+                    seconds,
+                    ucentsPerSecond * seconds,
+                );
+            },
         );
     }
 }
+
+/**
+ * Bytes per second of an ElevenLabs `output_format`. A format outside the
+ * documented set is sized as the default, so a made-up bitrate can't shrink the
+ * bill.
+ */
+export function outputBytesPerSecond(format: string): number {
+    const known = OUTPUT_FORMATS.has(format) ? format : DEFAULT_OUTPUT_FORMAT;
+    const [codec, rate, kbps] = known.split('_');
+    if (codec === 'mp3' || codec === 'opus') return Number(kbps) * 125;
+    if (codec === 'ulaw' || codec === 'alaw') return Number(rate);
+    // pcm and wav: 16-bit mono.
+    return Number(rate) * 2;
+}
+
+// Past this, a WAV whose data chunk hasn't started is billed by raw length.
+const WAV_HEADER_MAX_BYTES = 64 * 1024;
+
+/**
+ * Where the samples of a RIFF/WAVE stream start, once `head` reaches its `data`
+ * chunk; undefined until then, or if `head` isn't a WAV.
+ */
+export function wavDataOffset(head: Buffer): number | undefined {
+    if (head.length < 12) return undefined;
+    if (
+        head.toString('ascii', 0, 4) !== 'RIFF' ||
+        head.toString('ascii', 8, 12) !== 'WAVE'
+    )
+        return undefined;
+    let offset = 12;
+    while (offset + 8 <= head.length) {
+        if (head.toString('ascii', offset, offset + 4) === 'data')
+            return offset + 8;
+        const size = head.readUInt32LE(offset + 4);
+        offset += 8 + size + (size & 1);
+    }
+    return undefined;
+}
+
+const OGG_HEADER_BYTES = 27;
+const NO_GRANULE = 2n ** 64n - 1n;
+
+/**
+ * Walks an Ogg Opus stream page by page as it arrives. Opus is variable
+ * bitrate, so its length comes from the last page's granule position (48 kHz
+ * samples, less the stream's pre-skip) rather than its byte count.
+ */
+export class OggOpusClock {
+    #header = Buffer.alloc(0);
+    #skip = 0;
+    #firstBody: Buffer | undefined = Buffer.alloc(0);
+    #firstBodyBytes = 0;
+    #granule: bigint | undefined;
+    #preSkip = 0;
+    #broken = false;
+
+    push(chunk: Buffer): void {
+        let offset = 0;
+        while (!this.#broken && offset < chunk.length) {
+            if (this.#skip > 0) {
+                const n = Math.min(this.#skip, chunk.length - offset);
+                if (this.#firstBody && this.#firstBody.length < 19) {
+                    this.#firstBody = Buffer.concat([
+                        this.#firstBody,
+                        chunk.subarray(offset, offset + n),
+                    ]);
+                }
+                this.#skip -= n;
+                offset += n;
+                if (this.#skip === 0 && this.#firstBody) this.#readOpusHead();
+                continue;
+            }
+            const want =
+                this.#header.length < OGG_HEADER_BYTES
+                    ? OGG_HEADER_BYTES
+                    : OGG_HEADER_BYTES + this.#header[26]!;
+            const n = Math.min(
+                want - this.#header.length,
+                chunk.length - offset,
+            );
+            this.#header = Buffer.concat([
+                this.#header,
+                chunk.subarray(offset, offset + n),
+            ]);
+            offset += n;
+            if (this.#header.length < want) continue;
+            if (this.#header.toString('ascii', 0, 4) !== 'OggS') {
+                this.#broken = true;
+                return;
+            }
+            if (want === OGG_HEADER_BYTES && this.#header[26]! > 0) continue;
+            const granule = this.#header.readBigUInt64LE(6);
+            if (granule !== NO_GRANULE) this.#granule = granule;
+            let body = 0;
+            for (const lacing of this.#header.subarray(OGG_HEADER_BYTES)) {
+                body += lacing;
+            }
+            this.#header = Buffer.alloc(0);
+            this.#skip = body;
+            if (this.#firstBody) this.#firstBodyBytes = body;
+        }
+    }
+
+    /** Whole seconds so far, once the stream has proven to be Ogg Opus. */
+    get seconds(): number | undefined {
+        if (this.#broken || this.#granule === undefined) return undefined;
+        const samples = Number(this.#granule) - this.#preSkip;
+        return samples > 0
+            ? Math.max(1, Math.ceil(samples / 48_000))
+            : undefined;
+    }
+
+    #readOpusHead(): void {
+        const head = this.#firstBody!;
+        this.#firstBody = undefined;
+        if (
+            this.#firstBodyBytes < 19 ||
+            head.toString('ascii', 0, 8) !== 'OpusHead'
+        ) {
+            this.#broken = true;
+            return;
+        }
+        this.#preSkip = head.readUInt16LE(10);
+    }
+}
+
+/**
+ * Counts the bytes of a converted stream. `seconds` settles when the stream
+ * ends or closes: its length in whole seconds (undefined when nothing came
+ * back), and whether the upstream sent all of it. A WAV's header isn't audio,
+ * so it isn't counted; Opus is timed by its pages.
+ */
+function measuredOutput(bytesPerSecond: number, format: string) {
+    let bytes = 0;
+    let head: Buffer | undefined = format.startsWith('wav_')
+        ? Buffer.alloc(0)
+        : undefined;
+    const opus = format.startsWith('opus_') ? new OggOpusClock() : undefined;
+    let headerBytes = 0;
+    let settle!: (measured: { seconds?: number; complete: boolean }) => void;
+    const seconds = new Promise<{ seconds?: number; complete: boolean }>(
+        (resolve) => {
+            settle = resolve;
+        },
+    );
+    const lengthOf = () => {
+        const timed = opus?.seconds;
+        if (timed !== undefined) return timed;
+        const audio = bytes - headerBytes;
+        return audio > 0
+            ? Math.max(1, Math.ceil(audio / bytesPerSecond))
+            : undefined;
+    };
+    const measure = (source: Readable): Readable => {
+        const counter = new Transform({
+            transform(chunk: Buffer, _encoding, callback) {
+                bytes += chunk.length;
+                opus?.push(chunk);
+                if (head) {
+                    head = Buffer.concat([head, chunk]);
+                    const offset = wavDataOffset(head);
+                    if (offset !== undefined) headerBytes = offset;
+                    if (
+                        offset !== undefined ||
+                        head.length >= WAV_HEADER_MAX_BYTES
+                    )
+                        head = undefined;
+                }
+                callback(null, chunk);
+            },
+            flush(callback) {
+                settle({ seconds: lengthOf(), complete: true });
+                callback();
+            },
+        });
+        counter.once('close', () =>
+            settle({ seconds: lengthOf(), complete: false }),
+        );
+        pipeline(source, counter, () => {});
+        return counter;
+    };
+    return { measure, seconds };
+}

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

@@ -508,6 +508,26 @@ describe('SpeechToTextDriver model selection and payload shape', () => {
         expect(sent.temperature).toBe(0.2);
     });
 
+    it('keeps extra_body from overriding the response shape billing reads', async () => {
+        const { actor } = await makeUser();
+        transcriptionsCreateMock.mockResolvedValueOnce({ text: 'x' });
+
+        await withActor(actor, () =>
+            driver.transcribe({
+                file: dataUrl(Buffer.from('a'), 'audio/mp3'),
+                model: 'gpt-transcribe',
+                extra_body: {
+                    response_format: 'text',
+                    stream: true,
+                    chunking_strategy: 'auto',
+                },
+            }),
+        );
+
+        const sent = transcriptionsCreateMock.mock.calls[0]![0];
+        expect(sent.extra_body).toEqual({ chunking_strategy: 'auto' });
+    });
+
     it('does not forward timestamp_granularities, which gpt-transcribe ignores', async () => {
         const { actor } = await makeUser();
         transcriptionsCreateMock.mockResolvedValueOnce({ text: 'x' });
@@ -684,6 +704,72 @@ describe('SpeechToTextDriver metering', () => {
         expect(creditCall[1]).toBe(expected);
     });
 
+    it('meters the duration OpenAI reports, not the byte estimate', async () => {
+        const { actor } = await makeUser();
+        const usageType = 'openai:gpt-transcribe:second';
+        const billed = async (bytes: number, seconds: number) => {
+            incrementUsageSpy.mockClear();
+            transcriptionsCreateMock.mockResolvedValueOnce({
+                text: 'x',
+                usage: { type: 'duration', seconds },
+            });
+            await withActor(actor, () =>
+                driver.transcribe({
+                    file: dataUrl(Buffer.alloc(bytes, 1), 'audio/ogg'),
+                }),
+            );
+            const [, , count, cost] = incrementUsageSpy.mock.calls.find(
+                ([, type]) => type === usageType,
+            )!;
+            expect(cost).toBe(SPEECH_TO_TEXT_COSTS[usageType]! * count);
+            return count;
+        };
+        // 600 s of Opus at 8 kbps, and 60 s of 44.1 kHz stereo WAV.
+        expect(await billed(441_078, 600)).toBe(600);
+        expect(await billed(10_584_078, 59.2)).toBe(60);
+    });
+
+    it('asks for json behind response_format=text so usage comes back', async () => {
+        const { actor } = await makeUser();
+        transcriptionsCreateMock.mockResolvedValueOnce({
+            text: 'plain transcript',
+            usage: { type: 'duration', seconds: 42 },
+        });
+        const result = await withActor(actor, () =>
+            driver.transcribe({
+                file: dataUrl(Buffer.from('a'), 'audio/mp3'),
+                response_format: 'text',
+            }),
+        );
+        expect(result).toBe('plain transcript');
+        expect(transcriptionsCreateMock.mock.calls[0]![0].response_format).toBe(
+            'json',
+        );
+        const usageType = 'openai:gpt-transcribe:second';
+        const [, , count] = incrementUsageSpy.mock.calls.find(
+            ([, type]) => type === usageType,
+        )!;
+        expect(count).toBe(42);
+    });
+
+    it('falls back to the byte estimate when OpenAI reports token usage', async () => {
+        const { actor } = await makeUser();
+        transcriptionsCreateMock.mockResolvedValueOnce({
+            text: 'x',
+            usage: { type: 'tokens', input_tokens: 10, output_tokens: 2 },
+        });
+        await withActor(actor, () =>
+            driver.transcribe({
+                file: dataUrl(Buffer.alloc(32000, 0), 'audio/mp3'),
+            }),
+        );
+        const usageType = 'openai:gpt-transcribe:second';
+        const [, , count] = incrementUsageSpy.mock.calls.find(
+            ([, type]) => type === usageType,
+        )!;
+        expect(count).toBe(2);
+    });
+
     it('holds and meters at the AI cost factor', async () => {
         const { actor } = await makeUser();
         const usageType = 'openai:gpt-transcribe:second';

src/backend/drivers/ai-speech2txt/providers/openai/OpenAISpeechToTextProvider.ts

@@ -170,9 +170,9 @@ export class OpenAISpeechToTextProvider extends SpeechToTextProvider {
             );
         }
 
-        // Estimate seconds from raw bytes — 16 kbps is a conservative speech-audio
-        // lower bound. Full metadata parsing (music-metadata) is deferred — clients
-        // aren't observably sensitive to billing-time delta vs real duration.
+        // The hold estimates seconds from bytes at 128 kbps: compact audio is
+        // under-held rather than refused, and usage is metered from the
+        // duration OpenAI reports.
         const estimatedSeconds = Math.max(
             1,
             Math.ceil(loaded.buffer.byteLength / 16000),
@@ -198,8 +198,13 @@ export class OpenAISpeechToTextProvider extends SpeechToTextProvider {
                 file: openaiFile,
                 model: selectedModel,
             };
+            // A `text` response carries no usage, so json is asked for and
+            // its text returned.
             if (args.response_format)
-                payload.response_format = args.response_format;
+                payload.response_format =
+                    args.response_format === 'text'
+                        ? 'json'
+                        : args.response_format;
             if (args.language) payload.language = args.language;
             if (typeof args.temperature === 'number')
                 payload.temperature = args.temperature;
@@ -207,7 +212,15 @@ export class OpenAISpeechToTextProvider extends SpeechToTextProvider {
             // The API ignores a bare `logprobs` flag; it only honors `include`.
             if (args.logprobs && caps.canLogprobs)
                 payload.include = ['logprobs'];
-            if (args.extra_body) payload.extra_body = args.extra_body;
+            if (args.extra_body && typeof args.extra_body === 'object') {
+                // Billing reads usage off the response; these can strip it.
+                const extra = {
+                    ...(args.extra_body as Record<string, unknown>),
+                };
+                delete extra.response_format;
+                delete extra.stream;
+                payload.extra_body = extra;
+            }
 
             const result = await this.#openai.audio.transcriptions.create(
                 payload as unknown as Parameters<
@@ -215,11 +228,12 @@ export class OpenAISpeechToTextProvider extends SpeechToTextProvider {
                 >[0],
             );
 
+            const billedSeconds = reportedSeconds(result) ?? estimatedSeconds;
             this.deps.metering.incrementUsage(
                 actor,
                 usageType,
-                estimatedSeconds,
-                ucentsPerSecond * estimatedSeconds,
+                billedSeconds,
+                ucentsPerSecond * billedSeconds,
             );
 
             // Text response_format: return raw string; otherwise forward the OpenAI object.
@@ -234,3 +248,18 @@ export class OpenAISpeechToTextProvider extends SpeechToTextProvider {
         }
     }
 }
+
+/** Whole seconds of audio OpenAI reports billing for, if it reports them. */
+function reportedSeconds(result: unknown): number | undefined {
+    if (!result || typeof result !== 'object') return undefined;
+    const { usage, duration } = result as {
+        usage?: { type?: string; seconds?: unknown };
+        duration?: unknown;
+    };
+    const seconds = usage?.type === 'duration' ? usage.seconds : duration;
+    return typeof seconds === 'number' &&
+        Number.isFinite(seconds) &&
+        seconds > 0
+        ? Math.max(1, Math.ceil(seconds))
+        : undefined;
+}

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

@@ -48,7 +48,7 @@ const VOICE_ID_PATTERN = /^[A-Za-z0-9]{20}$/;
 const VOICE_SEARCH_MAX_PAGES = 5;
 // https://elevenlabs.io/docs/api-reference/text-to-speech/convert
 // mp3_44100_192 needs the Creator tier; pcm/wav at 44.1 kHz need Pro.
-const OUTPUT_FORMATS = new Set([
+export const OUTPUT_FORMATS = new Set([
     'alaw_8000',
     'mp3_22050_32',
     'mp3_24000_48',

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

@@ -41,7 +41,8 @@ import {
 } from 'vitest';
 
 import { v4 as uuidv4 } from 'uuid';
-import { runWithContext } from '../../core/context.js';
+import { Context, runWithContext } from '../../core/context.js';
+import { HttpError } from '../../core/http/HttpError.js';
 import { type Actor, SYSTEM_ACTOR } from '../../core/actor.js';
 import { PuterServer } from '../../server.js';
 import type { MeteringService } from '../../services/metering/MeteringService.js';
@@ -926,6 +927,29 @@ describe('VideoGenerationDriver.generate puter_output_path', () => {
         expect(result).toBe(`data:video/mp4;base64,${videoBytes}`);
     });
 
+    it('returns the result and flags it unsaved when write access is revoked mid-job', async () => {
+        vi.spyOn(server.services.acl, 'check').mockResolvedValueOnce(true);
+        vi.spyOn(server.services.fs, 'checkFSAccess').mockRejectedValueOnce(
+            new HttpError(403, 'Access denied', { legacyCode: 'forbidden' }),
+        );
+        const fsWriteSpy = vi.spyOn(server.services.fs, 'write');
+        const videoBytes = Buffer.from('video-bytes').toString('base64');
+        completeTogetherJob(`data:video/mp4;base64,${videoBytes}`);
+
+        const [result, metadata] = await withTestUser(async () => [
+            await driver.generate({
+                prompt: 'hi',
+                model: DEFAULT_MODEL,
+                puter_output_path: '/testuser/videos/clip.mp4',
+            } as never),
+            Context.get('driverMetadata'),
+        ]);
+
+        expect(result).toBe(`data:video/mp4;base64,${videoBytes}`);
+        expect(fsWriteSpy).not.toHaveBeenCalled();
+        expect(metadata).toEqual({ outputSaved: false });
+    });
+
     it('does not forward puter_output_path to the upstream provider call', async () => {
         const aclCheckSpy = vi.spyOn(server.services.acl, 'check');
         aclCheckSpy.mockResolvedValueOnce(true);

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

@@ -336,13 +336,16 @@ export class VideoGenerationDriver extends PuterDriver {
         });
 
         if (resolvedOutputPath) {
-            await saveGeneratedMediaToFS(
+            // False when write access was revoked while the job ran; the
+            // result still comes back.
+            const outputSaved = await saveGeneratedMediaToFS(
                 this.services.fs,
                 actor,
                 result,
                 resolvedOutputPath,
                 { noun: 'video', defaultType: 'video/mp4' },
             );
+            Context.set('driverMetadata', { outputSaved });
         }
 
         return result;

src/backend/drivers/ai-video/providers/byteplus/BytePlusVideoProvider.test.ts

@@ -395,25 +395,33 @@ describe('BytePlusVideoProvider.generate polling and outcomes', () => {
         expect(fetchSpy).toHaveBeenCalledTimes(4); // 1 create + 3 polls
     });
 
-    it('gives up after the wait window as HttpError 504 upstream_timeout, without metering', async () => {
+    it('gives up after the wait window as HttpError 504 upstream_timeout, metering the task once it settles', async () => {
         vi.useFakeTimers();
         try {
+            let late: Record<string, unknown> = {
+                id: 'cgt-slow',
+                status: 'running',
+            };
             fetchSpy
                 .mockResolvedValueOnce(
                     jsonResponse({ id: 'cgt-slow', status: 'queued' }),
                 )
-                .mockImplementation(async () =>
-                    jsonResponse({ id: 'cgt-slow', status: 'running' }),
-                );
+                .mockImplementation(async () => jsonResponse(late));
             // The default poll interval keeps the window to ~60 polls.
             const provider = new BytePlusVideoProvider(
                 { apiKey: 'test-key' },
                 aiMetering(),
             );
 
-            const rejection = withTestActor(() =>
-                provider.generate({ prompt: 'hi' }),
-            ).catch((e: unknown) => e);
+            const rejection = (async () => {
+                try {
+                    await withTestActor(() =>
+                        provider.generate({ prompt: 'hi' }),
+                    );
+                } catch (e) {
+                    return e;
+                }
+            })();
 
             // Ten-minute wait window, polled every 5s.
             await vi.advanceTimersByTimeAsync(VIDEO_POLL_WINDOW_MS + 5_000);
@@ -425,7 +433,21 @@ describe('BytePlusVideoProvider.generate polling and outcomes', () => {
                     'Timed out waiting for BytePlus video generation to complete',
                 fields: { provider: 'byteplus' },
             });
+            // BytePlus still renders and bills the task past the window.
             expect(incrementUsageSpy).not.toHaveBeenCalled();
+            late = {
+                id: 'cgt-slow',
+                status: 'succeeded',
+                content: { video_url: 'https://byteplus.example/v.mp4' },
+                usage: { completion_tokens: 1234 },
+            };
+            await vi.advanceTimersByTimeAsync(10_000);
+            expect(incrementUsageSpy).toHaveBeenCalledTimes(1);
+            const [, usageType, tokens, cost] =
+                incrementUsageSpy.mock.calls[0]!;
+            expect(usageType).toMatch(/^byteplus-video-generation:/);
+            expect(tokens).toBe(1234);
+            expect(cost).toBeGreaterThan(0);
         } finally {
             vi.useRealTimers();
         }