@prized/sdk 0.1.0 → 0.1.2

package/dist/esm/http.js

@@ -5,6 +5,11 @@ import { commandEffect, restate, withAbort, withOutcome } from './outcome.js';
 import { VERSION } from './version.js';
 export const DEFAULT_BASE_URL = 'https://api.prized.dev';
 export const DEFAULT_EDGE_URL = 'https://term.prized.dev';
+/** Node's own fetch (not Bun's or Deno's, which also say they are Node), with web streams. */
+function nodeFetch() {
+    const versions = globalThis.process?.versions;
+    return typeof versions?.node === 'string' && versions.bun === undefined && versions.deno === undefined && typeof ReadableStream === 'function';
+}
 function envApiKey() {
     try {
         const env = globalThis.process?.env;
@@ -17,7 +22,15 @@ function envApiKey() {
 function isLoopback(hostname) {
     return hostname === 'localhost' || hostname === '127.0.0.1' || hostname === '[::1]';
 }
-/** An http(s) origin, trailing slashes and a trailing /api/v1 dropped. */
+/**
+ * https anywhere, plain http only to this machine: the API key rides in
+ * every request's Authorization header. The same rule for the options and
+ * for an edge the API names.
+ */
+function secureEndpoint(url) {
+    return url.protocol === 'https:' || (url.protocol === 'http:' && isLoopback(url.hostname));
+}
+/** An https (or loopback http) origin, trailing slashes and a trailing /api/v1 dropped. */
 function normalizeOrigin(name, raw) {
     let url;
     try {
@@ -29,6 +42,9 @@ function normalizeOrigin(name, raw) {
     if (url.protocol !== 'https:' && url.protocol !== 'http:') {
         throw new PrizedError('invalid_argument', `${name} must be an http(s) URL`);
     }
+    if (!secureEndpoint(url)) {
+        throw new PrizedError('invalid_argument', `${name} must use https (plain http only for localhost, 127.0.0.1 or [::1])`);
+    }
     if (url.username || url.password || url.search || url.hash) {
         throw new PrizedError('invalid_argument', `${name} must not carry credentials, a query or a fragment`);
     }
@@ -53,10 +69,11 @@ export function abortableSleep(ms, signal) {
     });
 }
 /**
- * How long a streamed or long exec keeps polling while its polls fail
- * before it stops the command (pollOutageMs): long enough to ride out a
- * dropped connection or an edge that restarts. The Python SDK's
- * DEFAULT_POLL_OUTAGE.
+ * How long a wait (a streamed or long exec, a handle's wait()) keeps polling
+ * while its polls fail before it gives up (pollOutageMs), and a streamed or
+ * long exec stops its command, and how long a start is sent again: long
+ * enough to ride out a dropped connection or an edge that restarts (about
+ * 70 s, the last time it crashed). The Python SDK's DEFAULT_POLL_OUTAGE.
  */
 export const DEFAULT_POLL_OUTAGE_MS = 120_000;
 /** A pollOutageMs given (a number of ms ≥ 0), or undefined. */
@@ -98,22 +115,54 @@ export function resolveConfig(options = {}) {
         sleep: options.sleep ?? abortableSleep,
         now: options.now ?? Date.now,
         random: options.random ?? Math.random,
+        streamBodies: options.fetch === undefined && nodeFetch(),
     };
 }
+/** Prized's own domain: its API and its edges are hosts under it. */
+const PRIZED_DOMAIN = 'prized.dev';
+function under(host, domain) {
+    return host === domain || host.endsWith(`.${domain}`);
+}
+/** A URL's hostname (lowercase, as URL gives it), or '' if it does not parse. */
+function hostOf(raw) {
+    try {
+        return new URL(raw).hostname;
+    }
+    catch {
+        return '';
+    }
+}
+/**
+ * Where a toolboxBase may point, given the API's host: the API host itself;
+ * prized.dev's own hosts when the API is one of them; loopback when the API
+ * is. Never a domain guessed from the API host's name (a public suffix such
+ * as co.uk would trust everyone under it). The Python SDK's _trusted_edge.
+ */
+function trustedEdge(edgeHost, apiHost) {
+    if (edgeHost === '' || apiHost === '')
+        return false;
+    if (isLoopback(apiHost) || isLoopback(edgeHost))
+        return isLoopback(apiHost) && isLoopback(edgeHost);
+    return edgeHost === apiHost || (under(apiHost, PRIZED_DOMAIN) && under(edgeHost, PRIZED_DOMAIN));
+}
 /**
  * Where exec and files go for one sandbox. An explicit edgeUrl wins; else the
  * API's own `toolboxBase` when it has the expected shape (https, or plain
- * http on loopback for local development); else the default edge.
+ * http on loopback for local development, ending /v1/sandbox/<id>) on a host
+ * trusted beside the API's (term.prized.dev beside api.prized.dev; see
+ * trustedEdge); else the default edge, for Prized's own API only. The API key
+ * is never sent anywhere else: discovery is routing, not authority.
  */
 export function toolboxBaseFor(config, sandboxId, toolboxBase) {
     const path = `/v1/sandbox/${encodeURIComponent(sandboxId)}`;
     if (config.edgeUrl !== null)
         return `${config.edgeUrl}${path}`;
+    const apiHost = hostOf(config.baseUrl);
     if (toolboxBase) {
         try {
             const url = new URL(toolboxBase);
-            const secure = url.protocol === 'https:' || (url.protocol === 'http:' && isLoopback(url.hostname));
-            if (secure &&
+            if (secureEndpoint(url) &&
+                trustedEdge(url.hostname, apiHost) &&
                 !url.username &&
                 !url.password &&
                 !url.search &&
@@ -126,7 +175,11 @@ export function toolboxBaseFor(config, sandboxId, toolboxBase) {
             // fall through to the default
         }
     }
-    return `${DEFAULT_EDGE_URL}${path}`;
+    // Prized's own edge only for Prized's own API: a key for another
+    // deployment is never sent to it. That deployment names its edge.
+    if (under(apiHost, PRIZED_DOMAIN))
+        return `${DEFAULT_EDGE_URL}${path}`;
+    throw new PrizedError('edge_unknown', `The API at ${config.baseUrl} named no command endpoint this SDK trusts for ${sandboxId}; pass edgeUrl for that deployment.`, { sandboxId });
 }
 /**
  * The edge this config's sandboxes answer on, before the API has named one:
@@ -223,7 +276,7 @@ export function retryable(error, mode, method) {
     // have done a write's work, so a write is left to its caller (a create
     // that may have made a sandbox finds and deletes it). A GET did nothing:
     // a poll that meets one is sent again rather than failing its create.
-    if (error.status === 500 && method === 'GET')
+    if (mode === 'safe' && error.status === 500 && method === 'GET')
         return true;
     return error.status === 429 || error.status === 502 || error.status === 503 || error.status === 504;
 }
@@ -309,6 +362,84 @@ export function backoffMs(config, attempt) {
     const base = Math.min(MAX_BACKOFF_MS, BACKOFF_FIRST_MS * 2 ** attempt);
     return Math.round(base / 2 + (config.random() * base) / 2);
 }
+/**
+ * How long a file transfer may move no bytes before the attempt is given up
+ * (sdk/retry-spec.json transferStallMs; the Python SDK's TRANSFER_STALL).
+ * The edge holds a request about 20 s at most before it reads the body (its
+ * admission queue, then waking a paused sandbox), and ends a body that brings
+ * nothing for 60 s itself: kept above that, a stalled copy is over at the
+ * edge before the next one goes to the same staged name, so the two never
+ * race. Once an upload's last byte is handed over, its answer is waited for
+ * that and a second more for every uploadAnswerBytesPerSecond it sent: what
+ * the socket's buffers, or a proxy that takes a whole body before it sends it
+ * on, still hold moves unseen, and must not read as a stall (the Python SDK's
+ * UPLOAD_ANSWER_RATE). Mutable for tests only.
+ */
+export const timing = { transferStallMs: 120_000, uploadAnswerBytesPerSecond: 128 * 1024 };
+/** A streamed upload goes out this many bytes at a time. */
+export const UPLOAD_CHUNK = 64 * 1024;
+/**
+ * A body's bytes, to stream; null for one to send as it is. By shape, not
+ * instanceof: a Uint8Array or Buffer from another realm (a test runner's vm
+ * context, say) is one too.
+ */
+async function bodyBytes(body) {
+    if (typeof body === 'string')
+        return new TextEncoder().encode(body);
+    if (ArrayBuffer.isView(body))
+        return new Uint8Array(body.buffer, body.byteOffset, body.byteLength);
+    if (Object.prototype.toString.call(body) === '[object ArrayBuffer]')
+        return new Uint8Array(body);
+    if (typeof body.arrayBuffer === 'function')
+        return new Uint8Array(await body.arrayBuffer());
+    return null;
+}
+/**
+ * `bytes` as a stream fed UPLOAD_CHUNK at a time, `moved` told each time
+ * fetch asks for more, and at the end given the answer's allowance
+ * (timing.uploadAnswerBytesPerSecond).
+ */
+function inPieces(bytes, moved) {
+    let at = 0;
+    return new ReadableStream({
+        pull(controller) {
+            if (at >= bytes.byteLength) {
+                moved((bytes.byteLength / timing.uploadAnswerBytesPerSecond) * 1000);
+                controller.close();
+                return;
+            }
+            moved();
+            // A copy: a runtime may take the piece's buffer as it sends it.
+            controller.enqueue(bytes.slice(at, at + UPLOAD_CHUNK));
+            at += UPLOAD_CHUNK;
+        },
+    }, 
+    // Nothing read ahead: a pull is the socket taking the last piece.
+    { highWaterMark: 0 });
+}
+/** A body read whole, `moved` told of every piece. */
+async function readAll(response, moved) {
+    if (response.body === null)
+        return new Uint8Array(0);
+    const reader = response.body.getReader();
+    const parts = [];
+    let size = 0;
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        moved();
+        parts.push(value);
+        size += value.byteLength;
+    }
+    const whole = new Uint8Array(size);
+    let at = 0;
+    for (const part of parts) {
+        whole.set(part, at);
+        at += part.byteLength;
+    }
+    return whole;
+}
 /**
  * One fetch, body included, under one timeout and the caller's signal. A
  * body that stalls or breaks after the headers fails the attempt like a
@@ -317,10 +448,24 @@ export function backoffMs(config, attempt) {
 async function attemptOnce(config, spec, url, timeoutMs) {
     const controller = new AbortController();
     let timedOut = false;
+    let stalled = false;
     const timer = setTimeout(() => {
         timedOut = true;
         controller.abort();
     }, timeoutMs);
+    // The stall bound starts over whenever bytes move (stallMs), until the attempt is over.
+    let stall;
+    let over = false;
+    const moved = (extraMs = 0) => {
+        if (spec.stallMs === undefined || over)
+            return;
+        clearTimeout(stall);
+        stall = setTimeout(() => {
+            stalled = true;
+            timedOut = true;
+            controller.abort();
+        }, spec.stallMs + extraMs);
+    };
     const onAbort = () => controller.abort();
     spec.signal?.addEventListener('abort', onAbort, { once: true });
     const headers = {
@@ -330,30 +475,52 @@ async function attemptOnce(config, spec, url, timeoutMs) {
         ...spec.headers,
     };
     let body;
-    if (spec.json !== undefined) {
-        headers['content-type'] = 'application/json';
-        body = JSON.stringify(spec.json);
-    }
-    else if (spec.body !== undefined) {
-        headers['content-type'] = spec.contentType ?? 'application/octet-stream';
-        body = spec.body;
-    }
+    // Watched from the start unless an upload goes out unwatched (Config.streamBodies).
+    let watched = spec.stallMs !== undefined && spec.body === undefined;
+    let streamed = false;
     let status = null;
     try {
+        if (spec.json !== undefined) {
+            headers['content-type'] = 'application/json';
+            body = JSON.stringify(spec.json);
+        }
+        else if (spec.body !== undefined) {
+            headers['content-type'] = spec.contentType ?? 'application/octet-stream';
+            body = spec.body;
+            const bytes = spec.stallMs !== undefined && config.streamBodies ? await bodyBytes(spec.body) : null;
+            if (bytes !== null) {
+                headers['content-length'] = String(bytes.byteLength);
+                body = inPieces(bytes, moved);
+                streamed = true;
+                watched = true;
+            }
+        }
+        if (watched)
+            moved();
         const response = await config.fetch(url, {
             method: spec.method,
             headers,
             body: body,
+            // A streamed body (Node's fetch asks for it): sent before the answer is read.
+            ...(streamed ? { duplex: 'half' } : {}),
             // Never follow a redirect with the key attached.
             redirect: 'manual',
             signal: controller.signal,
         });
         status = response.status;
+        if (spec.stallMs !== undefined)
+            moved();
         const ok = response.status >= 200 && response.status < 300;
         if (response.status >= 300 && response.status < 400) {
             await response.body?.cancel().catch(() => undefined);
             return { answer: { status: response.status, headers: response.headers, text: '', bytes: null } };
         }
+        if (spec.stallMs !== undefined) {
+            const whole = await readAll(response, moved);
+            if (ok && spec.read === 'bytes')
+                return { answer: { status: response.status, headers: response.headers, text: '', bytes: whole } };
+            return { answer: { status: response.status, headers: response.headers, text: new TextDecoder('utf-8').decode(whole), bytes: null } };
+        }
         if (ok && spec.read === 'bytes') {
             const bytes = new Uint8Array(await response.arrayBuffer());
             return { answer: { status: response.status, headers: response.headers, text: '', bytes } };
@@ -361,10 +528,12 @@ async function attemptOnce(config, spec, url, timeoutMs) {
         return { answer: { status: response.status, headers: response.headers, text: await response.text(), bytes: null } };
     }
     catch (error) {
-        return { error, timedOut, status };
+        return { error, timedOut, stalled, status };
     }
     finally {
+        over = true;
         clearTimeout(timer);
+        clearTimeout(stall);
         spec.signal?.removeEventListener('abort', onAbort);
     }
 }
@@ -410,8 +579,9 @@ export function outcomeOf(error) {
 /**
  * The error a request throws. With an `effect`, it says whether the sandbox
  * acted on the request: by this attempt, or by an earlier one that was sent
- * again (`acted`: only a keyed request, the background start, is sent again
- * after it may have arrived). `cutStatus`: the 2xx whose body broke off.
+ * again (`acted`: only a keyed request, the background start, and a staged
+ * upload are sent again after they may have arrived). `cutStatus`: the 2xx
+ * whose body broke off.
  */
 function raised(failure, outcome, acted, effect, cutStatus = null) {
     if (effect === undefined)
@@ -426,7 +596,8 @@ export async function request(config, spec) {
     const timeoutMs = spec.timeoutMs ?? config.requestTimeoutMs;
     const sandboxId = spec.sandboxId ?? null;
     const effect = spec.effect ?? (spec.retry === 'exec' ? commandEffect() : undefined);
-    const unsent = spec.retry === 'exec' ? effect : undefined;
+    // Whether an attempt that was sent again (or an earlier copy) may have reached the sandbox.
+    let acted = spec.acted ?? false;
     // Names the last attempt's failure, if any, so a call cut short by its
     // deadline still says what it was waiting out (a 503, a rate limit).
     const pastDeadline = (last) => {
@@ -434,9 +605,11 @@ export async function request(config, spec) {
         const tail = what === null ? '' : ` The last attempt failed with ${what}.`;
         let error = new PrizedError('timeout', `The time allowed for this call ran out.${tail}`, { sandboxId, cause: last });
         // A command is sent again only when it provably never arrived, so every
-        // attempt of one cut short this way never reached the sandbox.
-        if (unsent !== undefined)
-            error = withOutcome(error, unsent, 'never');
+        // attempt of one cut short this way never reached the sandbox. A staged
+        // upload's copies may have, unless each provably never arrived, and so
+        // may a keyed start's (the one `safe` request that names an effect).
+        if (effect !== undefined)
+            error = withOutcome(error, effect, spec.retry !== 'exec' && acted ? 'maybe' : 'never');
         cutShort.add(error);
         return error;
     };
@@ -445,8 +618,6 @@ export async function request(config, spec) {
         return error;
     };
     let last;
-    // Whether an attempt that was sent again may have reached the sandbox.
-    let acted = false;
     // An abort with an `effect` says whether the sandbox may have acted:
     // before an attempt, or while waiting to send one again, nothing was sent
     // that might have, unless an earlier attempt of a keyed request (`acted`)
@@ -476,15 +647,19 @@ export async function request(config, spec) {
             }
             const unsentAttempt = !outcome.timedOut && neverSent(outcome.error);
             failure = failed(outcome.timedOut
-                ? new PrizedError('timeout', `No answer within ${attemptMs} ms`, { sandboxId, cause: outcome.error })
+                ? new PrizedError('timeout', outcome.stalled ? `No bytes moved for ${spec.stallMs} ms` : `No answer within ${attemptMs} ms`, {
+                    sandboxId,
+                    cause: outcome.error,
+                })
                 : unsentAttempt
                     ? new PrizedError('network_error', null, { sandboxId, cause: outcome.error })
                     : new PrizedError('network_error', lostMessage(spec.method, url, outcome.error), { sandboxId, cause: outcome.error }));
             // The status came and the body did not: the sandbox acted on it.
             const cut = outcome.status !== null && outcome.status >= 200 && outcome.status < 300;
             const said = cut ? 'did' : unsentAttempt ? 'never' : 'maybe';
-            // A command or upload is sent again only if it never left.
-            const resend = spec.retry === 'safe' || (spec.retry === 'exec' && unsentAttempt);
+            // A command is sent again only if it never left; a staged upload
+            // unless its 2xx came (its bytes are there).
+            const resend = spec.retry === 'safe' || (spec.retry === 'exec' && unsentAttempt) || (spec.retry === 'staged' && !cut);
             if (!resend || attempt >= config.maxRetries)
                 throw raised(failure, said, acted, effect, cut ? outcome.status : null);
             acted = acted || said !== 'never';
@@ -500,7 +675,8 @@ export async function request(config, spec) {
                 }
             }
             if (answer.status >= 300 && answer.status < 400) {
-                throw failed(new PrizedError('unexpected_redirect', null, { status: answer.status, sandboxId }));
+                // A refusal; worded only when an earlier copy of a keyed start may have arrived.
+                throw raised(failed(new PrizedError('unexpected_redirect', null, { status: answer.status, sandboxId })), null, acted, effect);
             }
             const retryAfter = parseRetryAfter(answer.headers.get('retry-after'), config.now());
             failure = failed(errorFromResponse(answer.status, answer.text, retryAfter, sandboxId, urlPath(url)));

package/dist/esm/index.d.ts

@@ -4,9 +4,9 @@ export { CommandHandle, DEFAULT_EXEC_TIMEOUT_MS, MAX_BLOCKING_EXEC_MS } from './
 export type { CommandStatus, ExecOptions, WaitOptions } from './commands.js';
 export { Files } from './files.js';
 export type { FileData, WriteOptions } from './files.js';
-export { CommandTimeoutError, PrizedError } from './errors.js';
-export type { PrizedErrorInit } from './errors.js';
+export { CommandTimeoutError, OutputReadError, PrizedError } from './errors.js';
+export type { OutputReadErrorInit, PrizedErrorInit } from './errors.js';
 export { DEFAULT_BASE_URL, DEFAULT_EDGE_URL } from './http.js';
 export type { ClientOptions } from './http.js';
-export type { ExecResult, FileInfo, Resources, ResourcesInput, SandboxInfo, SandboxState, Template, WriteInfo, } from './types.js';
+export type { ExecResult, FileInfo, Resources, ResourcesInput, SandboxInfo, SandboxState, Template, TruncatedReason, WriteInfo, } from './types.js';
 export { VERSION } from './version.js';

package/dist/esm/index.js

@@ -2,6 +2,6 @@
 export { Sandbox, DEFAULT_TEMPLATE, PREVIEW_KEY_HEADER } from './sandbox.js';
 export { CommandHandle, DEFAULT_EXEC_TIMEOUT_MS, MAX_BLOCKING_EXEC_MS } from './commands.js';
 export { Files } from './files.js';
-export { CommandTimeoutError, PrizedError } from './errors.js';
+export { CommandTimeoutError, OutputReadError, PrizedError } from './errors.js';
 export { DEFAULT_BASE_URL, DEFAULT_EDGE_URL } from './http.js';
 export { VERSION } from './version.js';

package/dist/esm/outcome.d.ts

@@ -30,11 +30,12 @@ export declare function helperEffect(): Effect;
 export type Outcome = 'never' | 'maybe' | 'did' | null;
 /** Whether withOutcome said the sandbox may have acted on the request. */
 export declare function mayHaveActed(error: unknown): error is PrizedError;
-/** `error` with another message (and, given, another status, code, sandbox or cause), every other field kept. */
+/** `error` with another message (and, given, another status, code, sandbox, exit code or cause), every other field kept. */
 export declare function restate(error: PrizedError, message: string, init?: {
     status?: number;
     code?: string;
     sandboxId?: string;
+    exitCode?: number;
     cause?: unknown;
 }): PrizedError;
 /** `error` (same code, status and body), its message saying what it means for `effect`. */
@@ -48,6 +49,15 @@ export declare function withOutcome(error: PrizedError, effect: Effect, outcome:
  * connection closes. TypeScript only: the Python SDK takes no signal.
  */
 export declare function withAbort(error: PrizedError, effect: Effect, outcome: 'never' | 'maybe' | 'did'): PrizedError;
+/**
+ * What a start that gave up throws when the failure it gives up with
+ * (`failure`, Outage's pick) is not the last copy's own: an earlier copy's,
+ * worded before a later copy may have reached the sandbox, or what a copy
+ * cut short by the window met, not yet worded. Worded for the start: as one
+ * that may have started when any copy may have reached the sandbox
+ * (`anyActed`), else as one that never did. The Python SDK's start_gave_up.
+ */
+export declare function startGaveUp(failure: PrizedError, anyActed: boolean): PrizedError;
 /**
  * A background start that may have started (`error`, from withOutcome or
  * withAbort) and that the SDK then stopped by its run id (`stopped`: the

package/dist/esm/outcome.js

@@ -1,7 +1,9 @@
 // What an error says about a command that may have run. A command, a file
-// write, a remove or a signal (`exec` retry mode) is never sent again once it
-// may have reached the sandbox, so its error has to say what the caller cannot
-// see: whether it happened. The Python SDK words these the same (_core.py).
+// write's rename, a remove or a signal (`exec` retry mode) is never sent again
+// once it may have reached the sandbox, so its error has to say what the
+// caller cannot see: whether it happened. A write's staged upload (`staged`)
+// may have been sent again, and its error says whether a copy may have
+// reached the sandbox. The Python SDK words these the same (_core.py).
 import { defaultMessage, PrizedError } from './errors.js';
 const NOT_SENT_AGAIN = 'It was not sent again';
 export function commandEffect() {
@@ -50,7 +52,7 @@ const acted = new WeakSet();
 export function mayHaveActed(error) {
     return error instanceof PrizedError && acted.has(error);
 }
-/** `error` with another message (and, given, another status, code, sandbox or cause), every other field kept. */
+/** `error` with another message (and, given, another status, code, sandbox, exit code or cause), every other field kept. */
 export function restate(error, message, init = {}) {
     return new PrizedError(init.code ?? error.code, message, {
         status: init.status ?? error.status,
@@ -58,6 +60,7 @@ export function restate(error, message, init = {}) {
         sandboxId: error.sandboxId ?? init.sandboxId ?? null,
         body: error.body,
         retryAfter: error.retryAfter,
+        exitCode: init.exitCode ?? error.exitCode,
         cause: 'cause' in init ? init.cause : error.cause,
     });
 }
@@ -87,12 +90,14 @@ function maybeTail(effect, closed) {
         tail += ` ${effect.check}`;
     return tail;
 }
+/** How an error says its request never reached the sandbox (withOutcome). */
+const NEVER_TAIL = ' It never reached the sandbox, so it had no effect.';
 /** `error` (same code, status and body), its message saying what it means for `effect`. */
 export function withOutcome(error, effect, outcome) {
     if (outcome === null)
         return error;
     if (outcome === 'never')
-        return restate(error, `${trimmed(error.message)}. It never reached the sandbox, so it had no effect.`);
+        return restate(error, `${trimmed(error.message)}.${NEVER_TAIL}`);
     if (outcome === 'did')
         return acting(error, `${effect.did}, but the answer could not be read (${detail(error)}).`);
     return acting(error, `No clear answer came back (${detail(error)}), so ${maybeTail(effect, false)}`);
@@ -116,6 +121,23 @@ function stopTail(runId, stopped) {
         ? ` The SDK stopped ${runId}, or it had already ended.`
         : ` The SDK could not confirm it stopped: it may still be running as ${runId} (exec('ps -ef | grep ${runId}') finds it).`;
 }
+/**
+ * What a start that gave up throws when the failure it gives up with
+ * (`failure`, Outage's pick) is not the last copy's own: an earlier copy's,
+ * worded before a later copy may have reached the sandbox, or what a copy
+ * cut short by the window met, not yet worded. Worded for the start: as one
+ * that may have started when any copy may have reached the sandbox
+ * (`anyActed`), else as one that never did. The Python SDK's start_gave_up.
+ */
+export function startGaveUp(failure, anyActed) {
+    if (acted.has(failure))
+        return failure;
+    const never = failure.message.endsWith(NEVER_TAIL);
+    if (never && !anyActed)
+        return failure;
+    const plain = never ? restate(failure, failure.message.slice(0, -NEVER_TAIL.length)) : failure;
+    return withOutcome(plain, startEffect(), anyActed ? 'maybe' : 'never');
+}
 /**
  * A background start that may have started (`error`, from withOutcome or
  * withAbort) and that the SDK then stopped by its run id (`stopped`: the

package/dist/esm/output.d.ts

@@ -1,5 +1,5 @@
 import { type Toolbox } from './toolbox.js';
-import type { ExecResult } from './types.js';
+import type { ExecResult, TruncatedReason } from './types.js';
 export declare const OUTPUT_DIR = "/home/prized/.prized/exec";
 export declare const OUTPUT_ID_RE: RegExp;
 /** Each stream of a fullOutput command keeps at most this many bytes: one download. */
@@ -22,17 +22,22 @@ export declare const RUN_SCRIPT = "eval \"${PRIZED_EXEC_SCRIPT:?}\"";
  * Nothing is assigned before it runs but the positional parameters, so every
  * variable the caller's env sets reaches it unchanged, PATH included; and
  * every step holds under an errexit the env may switch on (SHELLOPTS). As in
- * a plain exec, the readers stop 5 s after the command ends if a process it
+ * a plain exec, the relays stop 5 s after the command ends if a process it
  * left running still holds its output, keeping what came through. A command
- * a signal ends exits 128+n, as a background command does. Without tee,
- * setsid or a directory to write to, the command runs as a plain exec.
+ * a signal ends exits 128+n, as a background command does. A reader that
+ * could not write its file (failedLines) sends the output to the files API
+ * whatever its size, with the marker saying which. Without /bin/sh, setsid,
+ * cat or a directory to write to, the command runs as a plain exec.
  */
 export declare function captureScript(id: string): string;
 /**
  * What a fullOutput command left when the script could not print it (its
  * time limit, or a signal, ended the script): the marker line, or `gone`,
  * with the directory removed, when there is nothing to read (it was never
- * made, or its output was already printed back).
+ * made, or its output was already printed back). A failed write is read from
+ * the reader's flag, before the size, which is final once the flag is there
+ * (the script's wait for the reader's exit status went with the script); a
+ * reader killed, or one that could not make its flag, is not seen here.
  */
 export declare function collectScript(id: string): string;
 /**
@@ -41,11 +46,17 @@ export declare function collectScript(id: string): string;
  * answer to remove its own.
  */
 export declare function removeOutputScript(id: string): string;
-/** The marker's byte counts (a stream cut at FULL_OUTPUT_BYTES reads more), `gone`, or null for no marker. */
-export declare function parseMarker(stdout: string, id: string): {
+/** What the marker line says: each stream's byte count (one cut at FULL_OUTPUT_BYTES reads more), and whether its reader failed to write it. */
+export interface Marker {
     out: number;
     err: number;
-} | 'gone' | null;
+    outFailed: boolean;
+    errFailed: boolean;
+}
+/** The marker (one without failure flags, as an earlier SDK's collect printed, has none), `gone`, or null for no marker. */
+export declare function parseMarker(stdout: string, id: string): Marker | 'gone' | null;
+/** Why the read-back output is cut, if it is: a failed write first, since it is the one the caller cannot foresee. */
+export declare function markerTruncation(marker: Marker): TruncatedReason | null;
 /**
  * A blocking exec that keeps the whole output (up to FULL_OUTPUT_BYTES of
  * each stream). The result is a plain exec's, timeouts included: the caller