@blaxel/core 0.3.22-preview.296 → 0.3.22-preview.298

package/dist/esm/common/settings.js

@@ -24,8 +24,8 @@ function missingCredentialsMessage() {
     return "No Blaxel credentials found. Set the BL_API_KEY and BL_WORKSPACE environment variables, or run `bl login`.";
 }
 // Build info - these placeholders are replaced at build time by build:replace-imports
-const BUILD_VERSION = "0.3.22-preview.296";
-const BUILD_COMMIT = "a65a57ef50380a21d37481404d9c834cbcb624b5";
+const BUILD_VERSION = "0.3.22-preview.298";
+const BUILD_COMMIT = "94d483b7b57386ae909bb8c438c550405f671211";
 const BUILD_SENTRY_DSN = "https://fd5e60e1c9820e1eef5ccebb84a07127@o4508714045276160.ingest.us.sentry.io/4510465864564736";
 const BLAXEL_API_VERSION = "2026-04-28";
 // Bun < 1.3.11 never sends connection-level WINDOW_UPDATE: the pooled h2

package/dist/esm/sandbox/process/process.http.test.js

@@ -0,0 +1,124 @@
+import { createClient } from "@hey-api/client-fetch";
+import { createServer } from "node:http";
+import { afterEach, describe, expect, it, vi } from "vitest";
+vi.mock("../../common/env.js", () => ({ env: process.env }));
+import { SandboxProcess } from "./process.js";
+const servers = [];
+afterEach(async () => { await Promise.all(servers.splice(0).map(server => new Promise(resolve => { server.closeAllConnections(); server.close(() => resolve()); }))); });
+async function localServer(handler) {
+    const server = createServer(handler);
+    servers.push(server);
+    await new Promise(resolve => server.listen(0, "127.0.0.1", resolve));
+    const address = server.address();
+    if (!address || typeof address === "string")
+        throw new Error("missing port");
+    return new SandboxProcess({ metadata: { name: "local" }, spec: {}, forceUrl: `http://127.0.0.1:${address.port}`, headers: {} });
+}
+describe("process HTTP contract", () => {
+    it("preserves caller identity after a lost POST response and never retries POST", async () => {
+        let starts = 0;
+        let name = "";
+        const process = await localServer((request, response) => {
+            void (async () => {
+                if (request.method === "POST") {
+                    starts++;
+                    const chunks = [];
+                    for await (const chunk of request) {
+                        if (Buffer.isBuffer(chunk))
+                            chunks.push(chunk);
+                    }
+                    name = JSON.parse(Buffer.concat(chunks).toString()).name;
+                    response.destroy();
+                    return;
+                }
+                response.setHeader("content-type", "application/json");
+                response.end(JSON.stringify({ name, status: "completed", exitCode: 0, stdout: "done" }));
+            })().catch((error) => response.destroy(error));
+        });
+        const input = { name: "original-command", command: "echo done" };
+        let error;
+        try {
+            await process.exec(input);
+        }
+        catch (caught) {
+            error = caught;
+        }
+        expect(error).toBeInstanceOf(TypeError);
+        expect(name).toBe(input.name);
+        expect(input).toEqual({ name: "original-command", command: "echo done" });
+        expect((await process.wait(name)).status).toBe("completed");
+        expect(starts).toBe(1);
+    });
+    it("rejects failed log streams while intentional close remains successful", async () => {
+        let streaming = false;
+        const process = await localServer((_request, response) => {
+            if (!streaming) {
+                response.writeHead(503);
+                response.end("unavailable");
+                return;
+            }
+            response.writeHead(200, { "content-type": "text/plain" });
+            response.write("stdout:hello\n");
+        });
+        const onError = vi.fn();
+        await expect(process.streamLogs("p", { onError }).wait()).rejects.toThrow("503");
+        expect(onError).toHaveBeenCalledTimes(1);
+        streaming = true;
+        const stream = process.streamLogs("p");
+        stream.close();
+        await expect(stream.wait()).resolves.toBeUndefined();
+    });
+    it("retries real status HTTP errors within the wait deadline", async () => {
+        let reads = 0;
+        const process = await localServer((_request, response) => {
+            reads++;
+            response.setHeader("content-type", "application/json");
+            if (reads === 1) {
+                response.writeHead(503);
+                response.end(JSON.stringify({ error: "unavailable" }));
+                return;
+            }
+            response.end(JSON.stringify({ status: "completed", exitCode: 0 }));
+        });
+        expect((await process.wait("p", { maxWait: 2000 })).status).toBe("completed");
+        expect(reads).toBe(2);
+    });
+    it("uses the configured client and interceptors for execution and log streaming", async () => {
+        const process = await localServer((request, response) => {
+            expect(request.headers["x-session"]).toBe("inherited");
+            expect(request.headers["x-intercepted"]).toBe("yes");
+            if (request.method === "POST") {
+                response.setHeader("content-type", "application/x-ndjson");
+                response.end(JSON.stringify({ type: "stdout", data: "streamed" }) + "\n" + JSON.stringify({ type: "result", data: JSON.stringify({ status: "completed", exitCode: 0, pid: "123" }) }) + "\n");
+            }
+            else {
+                response.setHeader("content-type", "text/plain");
+                response.end("stdout:reconnected\n");
+            }
+        });
+        const generated = createClient({ headers: { "x-session": "inherited" } });
+        const intercept = vi.fn((request) => { request.headers.set("x-intercepted", "yes"); return request; });
+        generated.interceptors.request.use(intercept);
+        Object.defineProperty(process, "client", { value: generated });
+        const onLog = vi.fn();
+        expect((await process.exec({ command: "echo streamed", waitForCompletion: true, onLog })).status).toBe("completed");
+        await process.streamLogs("123", { onLog }).wait();
+        expect(onLog.mock.calls).toEqual([["streamed"], ["reconnected"]]);
+        expect(intercept).toHaveBeenCalledTimes(2);
+    });
+    it("observes after a lost kill response, without sending kill twice", async () => {
+        let kills = 0;
+        const process = await localServer((request, response) => {
+            if (request.method === "DELETE") {
+                kills++;
+                response.destroy();
+                return;
+            }
+            response.setHeader("content-type", "application/json");
+            response.end(JSON.stringify({ status: "killed" }));
+        });
+        await expect(process.kill("p")).rejects.toBeInstanceOf(TypeError);
+        expect((await process.wait("p", { maxWait: 2000 })).status).toBe("killed");
+        expect(kills).toBe(1);
+    });
+});

package/dist/esm/sandbox/process/process.js

@@ -1,7 +1,6 @@
-import { settings } from "../../common/settings.js";
-import { SandboxAction } from "../action.js";
-import { retryOnTransientReset } from "../../common/transient-retry.js";
-import { deleteProcessByIdentifier, deleteProcessByIdentifierKill, deleteProcessByIdentifierStdin, getProcess, getProcessByIdentifier, getProcessByIdentifierLogs, postProcess, postProcessByIdentifierStdin } from "../client/index.js";
+import { ResponseError, SandboxAction } from "../action.js";
+import { isRetryableGatewayError, isTransientResetError, retryOnTransientReset } from "../../common/transient-retry.js";
+import { deleteProcessByIdentifier, deleteProcessByIdentifierKill, deleteProcessByIdentifierStdin, getProcess, getProcessByIdentifier, getProcessByIdentifierLogs, getProcessByIdentifierLogsStream, postProcess, postProcessByIdentifierStdin } from "../client/index.js";
 export class SandboxProcess extends SandboxAction {
     constructor(sandbox) {
         super(sandbox);
@@ -12,9 +11,7 @@ export class SandboxProcess extends SandboxAction {
             if (options.onError) {
                 options.onError(err);
             }
-            else {
-                console.error("Stream error:", err);
-            }
+            throw err;
         };
         const processLine = (line) => {
             if (line.startsWith("[keepalive]")) {
@@ -35,19 +32,15 @@ export class SandboxProcess extends SandboxAction {
         const done = (async () => {
             let buffer = '';
             try {
-                const headers = this.sandbox.forceUrl ? this.sandbox.headers : settings.headers;
-                const stream = await this.h2Fetch(`${this.url}/process/${identifier}/logs/stream`, {
-                    method: 'GET',
+                const { response: stream, data, error } = await getProcessByIdentifierLogsStream(this.withClient({
+                    path: { identifier },
+                    baseUrl: this.url,
                     signal: controller.signal,
-                    headers,
-                });
-                if (stream.status !== 200) {
-                    handleError(new Error(`Failed to stream logs: ${await stream.text()}`));
-                    return;
-                }
+                    parseAs: "stream",
+                }));
+                this.handleResponseError(stream, data, error);
                 if (!stream.body) {
-                    handleError(new Error('No stream body'));
-                    return;
+                    throw new Error('No stream body');
                 }
                 const reader = stream.body.getReader();
                 const decoder = new TextDecoder();
@@ -71,7 +64,7 @@ export class SandboxProcess extends SandboxAction {
                 }
             }
             catch (err) {
-                if (err && typeof err === 'object' && 'name' in err && err.name === 'AbortError') {
+                if (controller.signal.aborted) {
                     // Process remaining buffer before returning on abort
                     if (buffer.trim()) {
                         processLine(buffer);
@@ -81,27 +74,16 @@ export class SandboxProcess extends SandboxAction {
                 handleError(err instanceof Error ? err : new Error('Unknown stream error'));
             }
         })();
+        // Callback-only users need not await wait(); preserve rejection for those who do.
+        void done.catch(() => { });
         return {
             close: () => controller.abort(),
             wait: () => done,
         };
     }
     async exec(process) {
-        let onLog;
-        let onStdout;
-        let onStderr;
-        if ('onLog' in process && process.onLog) {
-            onLog = process.onLog;
-            delete process.onLog;
-        }
-        if ('onStdout' in process && process.onStdout) {
-            onStdout = process.onStdout;
-            delete process.onStdout;
-        }
-        if ('onStderr' in process && process.onStderr) {
-            onStderr = process.onStderr;
-            delete process.onStderr;
-        }
+        const { onLog, onStdout, onStderr, ...request } = process;
+        process = request;
         // Store original wait_for_completion setting
         const shouldWaitForCompletion = process.waitForCompletion;
         // When waiting for completion with streaming callbacks, use streaming endpoint
@@ -130,22 +112,15 @@ export class SandboxProcess extends SandboxAction {
         }
     }
     async execWithStreaming(processRequest, options) {
-        const headers = this.sandbox.forceUrl ? this.sandbox.headers : settings.headers;
         const controller = new AbortController();
-        const response = await this.h2Fetch(`${this.url}/process`, {
-            method: 'POST',
+        const { response, data, error } = await postProcess(this.withClient({
+            baseUrl: this.url,
             signal: controller.signal,
-            headers: {
-                ...headers,
-                'Content-Type': 'application/json',
-                'Accept': 'text/event-stream',
-            },
-            body: JSON.stringify(processRequest),
-        });
-        if (!response.ok) {
-            const errorText = await response.text();
-            throw new Error(`Failed to execute process: ${errorText}`);
-        }
+            headers: { Accept: "text/event-stream" },
+            body: processRequest,
+            parseAs: "stream",
+        }));
+        this.handleResponseError(response, data, error);
         const contentType = response.headers.get('Content-Type') || '';
         const isStreaming = contentType.includes('application/x-ndjson');
         // Fallback: server doesn't support streaming, use legacy approach
@@ -280,37 +255,77 @@ export class SandboxProcess extends SandboxAction {
             close: () => controller.abort(),
         };
     }
-    async wait(identifier, { maxWait = 60000, interval = 1000 } = {}) {
-        const startTime = Date.now();
-        let data = await this.get(identifier);
-        let status = data.status ?? "running";
-        while (status === "running") {
-            await new Promise((resolve) => setTimeout(resolve, interval));
-            try {
-                data = await this.get(identifier);
-                status = data.status ?? "running";
-            }
-            catch {
-                break;
-            }
-            if (Date.now() - startTime > maxWait) {
-                throw new Error("Process did not finish in time");
+    /** Wait for a terminal API state. Timeout/cancellation never stops the command. */
+    async wait(identifier, { maxWait = 60000, interval = 1000, signal } = {}) {
+        if (!Number.isFinite(maxWait) || (maxWait < 0 && maxWait !== -1) || !Number.isFinite(interval) || interval <= 0) {
+            throw new RangeError("maxWait must be -1 or finite and non-negative; interval must be finite and positive");
+        }
+        signal?.throwIfAborted();
+        const controller = new AbortController();
+        let lastError;
+        let pollTimer;
+        const cancel = () => controller.abort(signal?.reason);
+        const timeoutError = () => new Error(`Process did not finish in time (${identifier}); it may still be running`, { cause: lastError });
+        if (maxWait === 0)
+            throw timeoutError();
+        const deadline = maxWait === -1 ? Infinity : performance.now() + maxWait;
+        const timeout = maxWait === -1 ? undefined : setTimeout(() => controller.abort(timeoutError()), maxWait);
+        signal?.addEventListener("abort", cancel, { once: true });
+        const interrupted = new Promise((_, reject) => {
+            // Preserve the caller's AbortSignal reason, which need not be an Error.
+            // eslint-disable-next-line @typescript-eslint/prefer-promise-reject-errors
+            controller.signal.addEventListener("abort", () => reject(controller.signal.reason), { once: true });
+        });
+        const poll = async () => {
+            while (true) {
+                if (performance.now() >= deadline)
+                    controller.abort(timeoutError());
+                controller.signal.throwIfAborted();
+                try {
+                    const result = await this.get(identifier, { signal: controller.signal, retry: false });
+                    if (performance.now() >= deadline)
+                        controller.abort(timeoutError());
+                    controller.signal.throwIfAborted();
+                    if (["completed", "failed", "killed", "stopped"].includes(result.status))
+                        return result;
+                    if (result.status !== "running")
+                        throw new Error(`Unknown process status: ${result.status}`);
+                    lastError = undefined;
+                }
+                catch (error) {
+                    controller.signal.throwIfAborted();
+                    const retryable = isTransientResetError(error) || isRetryableGatewayError(error)
+                        || (error instanceof ResponseError && [408, 429, 500].includes(error.status ?? 0))
+                        || (error instanceof TypeError && /^(fetch failed|Failed to fetch|NetworkError when attempting to fetch resource\.)$/.test(error.message));
+                    if (!retryable)
+                        throw error;
+                    lastError = error;
+                }
+                // A failed observation uses the same polling cadence as a running process.
+                await new Promise(resolve => { pollTimer = setTimeout(resolve, interval); });
             }
+        };
+        try {
+            return await Promise.race([poll(), interrupted]);
+        }
+        finally {
+            clearTimeout(timeout);
+            clearTimeout(pollTimer);
+            signal?.removeEventListener("abort", cancel);
         }
-        return data;
     }
-    async get(identifier) {
-        // Idempotent GET: self-heal a transient connection reset (also makes the
-        // wait() poll loop resilient). exec() stays un-retried — it is a
-        // non-idempotent POST and retrying it duplicates the process (ENG-2340).
-        return retryOnTransientReset(async () => {
+    async get(identifier, { signal, retry = true } = {}) {
+        const read = async () => {
             const { response, data, error } = await getProcessByIdentifier(this.withClient({
                 path: { identifier },
                 baseUrl: this.url,
+                signal,
             }));
             this.handleResponseError(response, data, error);
             return data;
-        });
+        };
+        // wait owns the retry budget; standalone reads retain their existing retries.
+        return retry ? retryOnTransientReset(read) : read();
     }
     async list() {
         // Idempotent GET: self-heal a transient connection reset.

package/dist/esm/sandbox/process/process.live.test.js

@@ -0,0 +1,101 @@
+import { createServer } from "node:http";
+import { randomUUID } from "node:crypto";
+import { describe, expect, it, vi } from "vitest";
+vi.mock("../../common/env.js", () => ({ env: process.env }));
+import { SandboxProcess } from "./process.js";
+// Opt-in disposable sandbox API. No credentials or .env files are loaded.
+const url = process.env.LOCAL_PROCESS_API_URL;
+const client = (forceUrl) => new SandboxProcess({ metadata: { name: "local-process-tests" }, spec: {}, forceUrl, headers: {} });
+describe.skipIf(!url)("real sandbox process API", () => {
+    it("reconnects after wait timeout and recovers exit code and logs", async () => {
+        const api = client(url);
+        const name = `ts-timeout-${randomUUID()}`;
+        await api.exec({ name, command: "sleep 1; echo recovered; exit 7", waitForCompletion: false, keepAlive: false });
+        await expect(api.wait(name, { maxWait: 20, interval: 5 })).rejects.toThrow("did not finish in time");
+        const result = await api.wait(name, { maxWait: -1, interval: 20, signal: AbortSignal.timeout(5000) });
+        expect(result.status).toBe("failed");
+        expect(result.exitCode).toBe(7);
+        expect(await api.logs(name)).toContain("recovered");
+    });
+    it("cancels only observation, then explicitly kills and confirms the original command", async () => {
+        const api = client(url);
+        const name = `ts-cancel-${randomUUID()}`;
+        await api.exec({ name, command: "sleep 30", waitForCompletion: false, keepAlive: false });
+        try {
+            const controller = new AbortController();
+            controller.abort("done waiting");
+            await expect(api.wait(name, { signal: controller.signal })).rejects.toBe("done waiting");
+            expect((await api.get(name)).status).toBe("running");
+            await api.kill(name);
+            const result = await api.wait(name, { maxWait: 5000, interval: 20 });
+            expect(["killed", "failed", "completed"]).toContain(result.status);
+        }
+        finally {
+            await api.kill(name).catch(() => { });
+        }
+    });
+    it("gracefully stops and confirms an API terminal state", async () => {
+        const api = client(url);
+        const name = `ts-stop-${randomUUID()}`;
+        await api.exec({ name, command: "sleep 30", waitForCompletion: false, keepAlive: false });
+        try {
+            await api.stop(name);
+            const result = await api.wait(name, { maxWait: 5000, interval: 20 });
+            expect(["stopped", "failed", "completed"]).toContain(result.status);
+        }
+        finally {
+            await api.kill(name).catch(() => { });
+        }
+    });
+    it("streams logs and the final result through the generated client", async () => {
+        const api = client(url);
+        const output = [];
+        const result = await api.exec({ name: `ts-stream-${randomUUID()}`, command: "echo streamed-live", waitForCompletion: true, keepAlive: false, onLog: line => output.push(line) });
+        expect(result.status).toBe("completed");
+        expect(result.exitCode).toBe(0);
+        expect(output.join("\n")).toContain("streamed-live");
+    });
+    it("recovers the original command after its execution response is lost", async () => {
+        let posts = 0;
+        const server = createServer((request, response) => {
+            void (async () => {
+                const chunks = [];
+                for await (const chunk of request) {
+                    if (Buffer.isBuffer(chunk))
+                        chunks.push(chunk);
+                }
+                const body = Buffer.concat(chunks);
+                const upstream = await fetch(`${url}${request.url}`, { method: request.method, headers: { "content-type": "application/json" }, body: body.length ? body : undefined });
+                await upstream.arrayBuffer();
+                posts++;
+                response.destroy();
+            })().catch((error) => response.destroy(error));
+        });
+        await new Promise(resolve => server.listen(0, "127.0.0.1", resolve));
+        const address = server.address();
+        if (!address || typeof address === "string")
+            throw new Error("missing port");
+        const proxy = client(`http://127.0.0.1:${address.port}`);
+        try {
+            const identifier = `ts-lost-response-${randomUUID()}`;
+            let failure;
+            try {
+                await proxy.exec({ name: identifier, command: "echo exactly-once", waitForCompletion: true, keepAlive: false });
+            }
+            catch (error) {
+                failure = error;
+            }
+            expect(failure).toBeInstanceOf(TypeError);
+            const api = client(url);
+            const result = await api.wait(identifier, { maxWait: 5000 });
+            expect(result.status).toBe("completed");
+            expect(result.exitCode).toBe(0);
+            expect((await api.logs(identifier)).match(/exactly-once/g)).toHaveLength(1);
+            expect(posts).toBe(1);
+        }
+        finally {
+            server.closeAllConnections();
+            await new Promise(resolve => server.close(() => resolve()));
+        }
+    });
+});

package/dist/esm/sandbox/process/process.wait.test.js

@@ -0,0 +1,119 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+vi.mock("../../common/env.js", () => ({ env: process.env }));
+import { SandboxProcess } from "./process.js";
+import { ResponseError } from "../action.js";
+const api = () => new SandboxProcess({ metadata: { name: "local" }, spec: {}, forceUrl: "http://localhost", headers: {} });
+const response = (status) => new Response(JSON.stringify({ status, exitCode: status === "failed" ? 7 : 0 }), { headers: { "content-type": "application/json" } });
+afterEach(() => { vi.useRealTimers(); vi.unstubAllGlobals(); vi.restoreAllMocks(); });
+describe("process wait", () => {
+    it.each(["completed", "failed", "killed", "stopped"])("returns terminal %s immediately", async (status) => {
+        const fetch = vi.fn().mockResolvedValue(response(status));
+        vi.stubGlobal("fetch", fetch);
+        expect((await api().wait("original")).status).toBe(status);
+        expect(fetch).toHaveBeenCalledTimes(1);
+    });
+    it.each([401, 403, 404])("propagates HTTP %s instead of returning the previous running state", async (status) => {
+        vi.stubGlobal("fetch", vi.fn().mockResolvedValueOnce(response("running")).mockResolvedValue(new Response("{}", { status })));
+        await expect(api().wait("original", { interval: 1 })).rejects.toBeInstanceOf(ResponseError);
+    });
+    it.each([408, 429, 500, 502, 503, 504])("recovers from HTTP %s", async (status) => {
+        const fetch = vi.fn().mockResolvedValueOnce(new Response("{}", { status })).mockResolvedValue(response("completed"));
+        vi.stubGlobal("fetch", fetch);
+        expect((await api().wait("original", { interval: 1 })).status).toBe("completed");
+        expect(fetch).toHaveBeenCalledTimes(2);
+    });
+    it("recovers from a lost connection", async () => {
+        vi.stubGlobal("fetch", vi.fn().mockRejectedValueOnce(new TypeError("fetch failed")).mockResolvedValue(response("completed")));
+        expect((await api().wait("original", { interval: 1 })).status).toBe("completed");
+    });
+    it("bounds a hung request and aborts its transport", async () => {
+        vi.useFakeTimers();
+        const fetch = vi.fn(() => new Promise(() => { }));
+        vi.stubGlobal("fetch", fetch);
+        const assertion = expect(api().wait("original", { maxWait: 25 })).rejects.toThrow("Process did not finish in time (original)");
+        await vi.advanceTimersByTimeAsync(25);
+        await assertion;
+        expect(fetch.mock.calls[0][0].signal.aborted).toBe(true);
+        expect(vi.getTimerCount()).toBe(0);
+    });
+    it("retains the last network error as the timeout cause", async () => {
+        vi.useFakeTimers();
+        const cause = new TypeError("fetch failed");
+        vi.stubGlobal("fetch", vi.fn().mockRejectedValue(cause));
+        const assertion = expect(api().wait("original", { maxWait: 25 })).rejects.toMatchObject({ cause });
+        await vi.advanceTimersByTimeAsync(25);
+        await assertion;
+    });
+    it("cancels while sleeping without another request or leaked timers", async () => {
+        vi.useFakeTimers();
+        const fetch = vi.fn().mockResolvedValue(response("running"));
+        vi.stubGlobal("fetch", fetch);
+        const controller = new AbortController();
+        const reason = new Error("caller cancelled");
+        const assertion = expect(api().wait("original", { signal: controller.signal })).rejects.toBe(reason);
+        await vi.advanceTimersByTimeAsync(5);
+        controller.abort(reason);
+        await assertion;
+        await vi.advanceTimersByTimeAsync(2000);
+        expect(fetch).toHaveBeenCalledTimes(1);
+        expect(vi.getTimerCount()).toBe(0);
+    });
+    it("waits indefinitely through transient failures and returns a terminal state", async () => {
+        vi.useFakeTimers();
+        const fetch = vi.fn()
+            .mockRejectedValueOnce(new TypeError("fetch failed"))
+            .mockImplementation(() => Promise.resolve(response("running")));
+        vi.stubGlobal("fetch", fetch);
+        let settled = false;
+        const waiting = api().wait("original", { maxWait: -1, interval: 60_000 });
+        void waiting.then(() => { settled = true; });
+        await vi.advanceTimersByTimeAsync(86_400_000);
+        expect(settled).toBe(false);
+        expect(vi.getTimerCount()).toBe(1); // Only the next polling interval.
+        fetch.mockImplementation(() => Promise.resolve(response("failed")));
+        await vi.advanceTimersByTimeAsync(60_000);
+        expect(await waiting).toMatchObject({ status: "failed", exitCode: 7 });
+        expect(vi.getTimerCount()).toBe(0);
+    });
+    it("cancels an infinite wait with a hung request", async () => {
+        vi.useFakeTimers();
+        const fetch = vi.fn(() => new Promise(() => { }));
+        vi.stubGlobal("fetch", fetch);
+        const controller = new AbortController();
+        const reason = new Error("caller cancelled");
+        const assertion = expect(api().wait("original", { maxWait: -1, signal: controller.signal })).rejects.toBe(reason);
+        await vi.advanceTimersByTimeAsync(86_400_000);
+        expect(vi.getTimerCount()).toBe(0);
+        controller.abort(reason);
+        await assertion;
+        expect(fetch.mock.calls[0][0].signal.aborted).toBe(true);
+        expect(fetch).toHaveBeenCalledTimes(1);
+    });
+    it("still propagates permanent errors during an infinite wait", async () => {
+        const fetch = vi.fn().mockResolvedValue(new Response("{}", { status: 404 }));
+        vi.stubGlobal("fetch", fetch);
+        await expect(api().wait("original", { maxWait: -1 })).rejects.toBeInstanceOf(ResponseError);
+        expect(fetch).toHaveBeenCalledTimes(1);
+    });
+    it.each([-2, -0.5, Infinity, NaN])("rejects invalid maxWait %s", async (maxWait) => {
+        const fetch = vi.fn();
+        vi.stubGlobal("fetch", fetch);
+        await expect(api().wait("original", { maxWait })).rejects.toBeInstanceOf(RangeError);
+        expect(fetch).not.toHaveBeenCalled();
+    });
+    it("keeps zero as an immediate deadline", async () => {
+        const fetch = vi.fn();
+        vi.stubGlobal("fetch", fetch);
+        await expect(api().wait("original", { maxWait: 0 })).rejects.toThrow("did not finish in time");
+        expect(fetch).not.toHaveBeenCalled();
+    });
+    it("rejects an unknown state instead of claiming completion", async () => {
+        vi.stubGlobal("fetch", vi.fn().mockResolvedValue(response("unknown")));
+        await expect(api().wait("original")).rejects.toThrow("Unknown process status");
+    });
+    it("rejects a late terminal response even before the timeout callback runs", async () => {
+        vi.spyOn(performance, "now").mockReturnValueOnce(0).mockReturnValueOnce(0).mockReturnValue(30);
+        vi.stubGlobal("fetch", vi.fn().mockResolvedValue(response("completed")));
+        await expect(api().wait("original", { maxWait: 25 })).rejects.toThrow("Process did not finish in time");
+    });
+});