@prized/sdk 0.1.0 → 0.1.1

package/dist/cjs/output.js

@@ -5,22 +5,25 @@ exports.captureScript = captureScript;
 exports.collectScript = collectScript;
 exports.removeOutputScript = removeOutputScript;
 exports.parseMarker = parseMarker;
+exports.markerTruncation = markerTruncation;
 exports.execFullOutput = execFullOutput;
 // exec(..., { fullOutput: true }): one call that keeps a command's whole
 // output, not just the first 4 MiB of each stream the sandbox answers with.
 //
-// The command's stdout and stderr stay pipes, as in a plain exec. A reader on
-// each copies what comes through to a file in the exec's own directory, at a
-// fixed path under the sandbox user's home, and drops what passes 100 MiB, so
-// a runaway command cannot fill the disk:
+// The command's stdout and stderr stay pipes, as in a plain exec. A relay on
+// each passes what comes through to a reader that copies it to a file in the
+// exec's own directory, at a fixed path under the sandbox user's home, and
+// drops what passes 100 MiB, so a runaway command cannot fill the disk:
 //
 //   ~/.prized/exec/<exec id>/stdout
 //   ~/.prized/exec/<exec id>/stderr
 //
 // Both under 4 MiB: the script prints them back and removes the directory,
-// so the answer carries the same output a plain exec's does. Bigger: it
-// prints one marker line instead, and the SDK downloads both files through
-// the files API and removes the directory. The scripts are the Python SDK's
+// so the answer carries the same output a plain exec's does. Bigger, or a
+// reader that could not write its file (a full disk): it prints one marker
+// line instead, and the SDK downloads both files through the files API and
+// removes the directory. A stream whose write failed comes back as far as it
+// got, `truncated` with `truncatedReason: 'write_failed'`. The scripts are the Python SDK's
 // (sdk/python/src/prized/_output.py), rendered the same; both SDKs check
 // them against sdk/output-scripts/.
 const errors_js_1 = require("./errors.js");
@@ -57,45 +60,102 @@ function checkId(id) {
         throw new Error(`unreachable: bad exec id ${id}`);
 }
 /**
- * The reader on one stream: tee copies it to the file as it comes (each read
- * written at once) until the file reaches FULL_OUTPUT_BYTES and one 512-byte
- * block more, which tells a cut stream from a full one. The file size limit
- * (ulimit -f, in 512-byte blocks in POSIX mode) stops the file there with
- * EFBIG, not SIGXFSZ, and tee goes on draining into /dev/null, so the command
- * never meets a closed pipe and a runaway one cannot fill the disk. One
- * process per stream (exec), in a session of its own (setsid, same pid): a
- * time limit or a `kill 0` that ends the command's process group leaves it to
+ * The reader's own shell (`$1` the file, `$2` its flag): cat writes the file
+ * until a write fails; then the flag, an empty file (it takes no free block),
+ * then the rest drained into /dev/null, and exit 1. `true`, not `:`: a
+ * redirection that fails on a special builtin ends the shell, and with it
+ * the draining.
+ */
+const READER_SHELL = `'cat > "$1" || { true > "$2" || :; cat > /dev/null; exit 1; }'`;
+/**
+ * The reader on one stream: cat copies what the relay passes it to the file
+ * as it comes (each read written at once) until the file reaches
+ * FULL_OUTPUT_BYTES and one 512-byte block more, which tells a cut stream
+ * from a full one. The file size limit (ulimit -f, in 512-byte blocks in
+ * POSIX mode) stops the file there with EFBIG, not SIGXFSZ, and the reader
+ * goes on draining into /dev/null, so the command never meets a closed pipe
+ * and a runaway one cannot fill the disk. A write that fails short of that (a
+ * full disk) stops the file the same way. Either leaves `<name>.failed` at
+ * once, which collect reads when a time limit ended the script before it
+ * could wait for the reader, and the reader exits 1 once its input ends. A
+ * shell per stream (exec), in a session of its own (setsid, same pid): a time
+ * limit or a `kill 0` that ends the command's process group leaves it to
  * drain what the pipe still holds.
  */
 function reader(d, name, fifo) {
     const blocks = exports.FULL_OUTPUT_BYTES / 512 + 1;
     return (`( exec > /dev/null 2>&1; PATH=${shell_js_1.LAUNCH_PATH}; trap '' XFSZ; ( set -o posix ) && set -o posix; ` +
-        `ulimit -f ${blocks} || :; exec setsid tee ${d}/${name} < ${d}/${fifo} ) &`);
+        `ulimit -f ${blocks} || :; exec setsid /bin/sh -c ${READER_SHELL} sh ${d}/${name} ${d}/${name}.failed < ${d}/${fifo} ) &`);
+}
+/**
+ * The relay on one stream: cat reads the command's pipe and passes it on to
+ * the reader's. It is what the watchdog stops, never the reader, so the
+ * reader always ends on the end of its input, and its exit status says
+ * whether every write to its file went through. In a session of its own
+ * (setsid, same pid), as the reader is.
+ */
+function relay(d, from, to) {
+    return `( exec > ${d}/${to} 2> /dev/null < /dev/null; PATH=${shell_js_1.LAUNCH_PATH}; exec setsid cat ${d}/${from} ) &`;
+}
+/**
+ * A shell test: process `pid` (shell text) is this exec's relay on `fifo`,
+ * not another process that reused its pid. Its arguments must be exactly
+ * `cat <fifo>` (as setsid execs it), not merely name the exec's directory
+ * somewhere in the command line, as a process the command started may
+ * (`tail -f ~/.prized/exec/<id>/stdout`). /proc ends each argument with a
+ * NUL; here each is one line (a NUL becomes a newline, a newline a space),
+ * as the run scripts' isRun (shell.ts) reads them.
+ */
+function isRelay(pid, fifo) {
+    return `[ "$(tr "\\0\\n" "\\n " < "/proc/${pid}/cmdline" 2> /dev/null | tr "\\n" " ")" = "cat ${fifo} " ]`;
 }
 /**
  * The bound on waiting for the readers once the command has ended: GRACE_S
- * seconds, as the sandbox waits for a plain exec's pipes, then the readers
- * still running stop (a pid is checked to be this exec's tee first, never
- * one reused since), and a process the command left holding its output
- * meets a closed pipe, as it would there. Stopped early (TERM, once the
- * readers are done), it takes its sleep with it.
+ * seconds, as the sandbox waits for a plain exec's pipes, then the relays
+ * still running stop (each pid checked to be this exec's relay on its own
+ * pipe first, never one reused since): its reader then ends with what came
+ * through, and a process the command left holding its output meets a closed
+ * pipe, as it would there. Stopped early (TERM, once the readers are done),
+ * it takes its sleep with it.
  */
 function watchdog(d) {
     return (`( s=; trap '[ -z "$s" ] || kill "$s" 2> /dev/null; exit 0' TERM; sleep ${GRACE_S} & s=$!; wait "$s" || :; ` +
-        `for p in "$2" "$3"; do if tr "\\0" " " < "/proc/$p/cmdline" 2> /dev/null | grep -qF -- ${d}/; then kill "$p" 2> /dev/null || :; fi; done ) > /dev/null 2>&1 &`);
+        `if ${isRelay('$4', `${d}/o`)}; then kill "$4" 2> /dev/null || :; fi; ` +
+        `if ${isRelay('$5', `${d}/e`)}; then kill "$5" 2> /dev/null || :; fi ) > /dev/null 2>&1 &`);
 }
-/** Sizes, the cut past FULL_OUTPUT_BYTES and the marker line, with `d` set to the directory. */
+/**
+ * Sizes, the cut past FULL_OUTPUT_BYTES and the marker line, with `d` set to
+ * the directory and each reader's write failure in `x` and `y` (1 or 0,
+ * failedLines). A cut leaves `<name>.cut`, so collect sent again still reads
+ * the stream as past the bound (its flag is still there, its size no longer
+ * says so). `true`, not `:`, for the same reason as in READER_SHELL.
+ */
 function reportLines(id) {
     const max = exports.FULL_OUTPUT_BYTES;
     return {
         sizes: ['o=$(stat -c %s "$d/stdout" 2> /dev/null || echo 0)', 'e=$(stat -c %s "$d/stderr" 2> /dev/null || echo 0)'],
         cut: [
-            `if [ "$o" -gt ${max} ]; then truncate -s ${max} "$d/stdout" || :; fi`,
-            `if [ "$e" -gt ${max} ]; then truncate -s ${max} "$d/stderr" || :; fi`,
-            `echo "prized-output ${id} $o $e"`,
+            `if [ "$o" -gt ${max} ]; then truncate -s ${max} "$d/stdout" && true > "$d/stdout.cut" || :; fi`,
+            `if [ "$e" -gt ${max} ]; then truncate -s ${max} "$d/stderr" && true > "$d/stderr.cut" || :; fi`,
+            `echo "prized-output ${id} $o $e $x $y"`,
         ],
     };
 }
+/**
+ * Whether each reader failed to write its file (`x` for stdout, `y` for
+ * stderr: nonzero from its exit status, or its flag, after `sizes`): 1 when
+ * it ended in error short of the bound (a full disk or a quota, a file it
+ * could not create, a reader killed), else 0. Past the bound its error is the
+ * cut (EFBIG). The watchdog stops relays, never readers, so a reader's status
+ * is its own.
+ */
+function failedLines() {
+    const max = exports.FULL_OUTPUT_BYTES;
+    return [
+        `if [ "$x" -eq 0 ] || [ "$o" -gt ${max} ]; then x=0; else x=1; fi`,
+        `if [ "$y" -eq 0 ] || [ "$e" -gt ${max} ]; then y=0; else y=1; fi`,
+    ];
+}
 /**
  * The script a fullOutput exec runs (RUN_SCRIPT, from SCRIPT_VAR). The
  * caller's command, from COMMAND_VAR, runs as a plain exec runs it (`bash
@@ -105,10 +165,12 @@ function reportLines(id) {
  * 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.
  */
 function captureScript(id) {
     checkId(id);
@@ -117,21 +179,28 @@ function captureScript(id) {
     return [
         `set -- "\${${exports.COMMAND_VAR}:?}" /bin/bash; unset ${exports.COMMAND_VAR} ${exports.SCRIPT_VAR}; [ -x "$2" ] || set -- "$1" /bin/sh`,
         `if ( PATH=${shell_js_1.LAUNCH_PATH}; mkdir -p ${exports.OUTPUT_DIR} && mkdir ${d} ) 2> /dev/null; then`,
-        `if ( PATH=${shell_js_1.LAUNCH_PATH}; command -v tee && command -v setsid && mkfifo ${d}/o ${d}/e ) > /dev/null 2>&1; then`,
-        reader(d, 'stdout', 'o'),
+        `if ( PATH=${shell_js_1.LAUNCH_PATH}; [ -x /bin/sh ] && command -v setsid && command -v cat && mkfifo ${d}/o ${d}/e ${d}/p ${d}/q ) > /dev/null 2>&1; then`,
+        // The command writes to o and e; a relay passes each on to p and q, where its reader is.
+        reader(d, 'stdout', 'p'),
         'set -- "$1" "$2" "$!"',
-        reader(d, 'stderr', 'e'),
+        reader(d, 'stderr', 'q'),
         'set -- "$1" "$2" "$3" "$!"',
+        relay(d, 'o', 'p'),
+        'set -- "$1" "$2" "$3" "$4" "$!"',
+        relay(d, 'e', 'q'),
+        'set -- "$1" "$2" "$3" "$4" "$5" "$!"',
         // bash's "Killed" line for a command a signal ended goes to the braces' /dev/null.
-        `if { "$2" -c "$1" > ${d}/o 2> ${d}/e < /dev/null; } 2> /dev/null; then set -- 0 "$3" "$4"; else set -- "$?" "$3" "$4"; fi`,
+        `if { "$2" -c "$1" > ${d}/o 2> ${d}/e < /dev/null; } 2> /dev/null; then set -- 0 "$3" "$4" "$5" "$6"; else set -- "$?" "$3" "$4" "$5" "$6"; fi`,
         `PATH=${shell_js_1.LAUNCH_PATH}`,
         `c=$1; d=${d}`,
         watchdog(d),
         'w=$!',
-        'wait "$2" "$3" 2> /dev/null || :',
+        'if wait "$2" 2> /dev/null; then x=0; else x=$?; fi',
+        'if wait "$3" 2> /dev/null; then y=0; else y=$?; fi',
         'kill "$w" 2> /dev/null || :',
         ...sizes,
-        `if [ "$o" -lt ${toolbox_js_1.MAX_OUTPUT_BYTES} ] && [ "$e" -lt ${toolbox_js_1.MAX_OUTPUT_BYTES} ]; then ` +
+        ...failedLines(),
+        `if [ "$o" -lt ${toolbox_js_1.MAX_OUTPUT_BYTES} ] && [ "$e" -lt ${toolbox_js_1.MAX_OUTPUT_BYTES} ] && [ "$x$y" = 00 ]; then ` +
             'cat "$d/stdout" 2> /dev/null || :; cat "$d/stderr" >&2 2> /dev/null || :; rm -rf "$d" || :; exit "$c"; fi',
         ...cut,
         'exit "$c"',
@@ -145,7 +214,10 @@ function captureScript(id) {
  * 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.
  */
 function collectScript(id) {
     checkId(id);
@@ -154,7 +226,13 @@ function collectScript(id) {
         `d=${exports.OUTPUT_DIR}/${id}`,
         `PATH=${shell_js_1.LAUNCH_PATH}`,
         `if [ ! -f "$d/stdout" ] || [ ! -f "$d/stderr" ]; then rm -rf "$d" || :; echo "prized-output ${id} gone"; exit 0; fi`,
+        'if [ -e "$d/stdout.failed" ]; then x=1; else x=0; fi',
+        'if [ -e "$d/stderr.failed" ]; then y=1; else y=0; fi',
         ...sizes,
+        // Cut by an earlier collect whose answer was lost: as long as a cut stream (the bound and a block).
+        `if [ -e "$d/stdout.cut" ]; then o=$((${exports.FULL_OUTPUT_BYTES} + 512)); fi`,
+        `if [ -e "$d/stderr.cut" ]; then e=$((${exports.FULL_OUTPUT_BYTES} + 512)); fi`,
+        ...failedLines(),
         ...cut,
     ].join('\n');
 }
@@ -168,14 +246,22 @@ function removeOutputScript(id) {
     return (`PATH=${shell_js_1.LAUNCH_PATH}; rm -rf ${exports.OUTPUT_DIR}/${id}; ` +
         `find ${exports.OUTPUT_DIR} -mindepth 1 -maxdepth 1 -name 'exec_*' -mmin +${STALE_MIN} -exec rm -rf -- {} + 2> /dev/null || :`);
 }
-/** The marker's byte counts (a stream cut at FULL_OUTPUT_BYTES reads more), `gone`, or null for no marker. */
+/** The marker (one without failure flags, as an earlier SDK's collect printed, has none), `gone`, or null for no marker. */
 function parseMarker(stdout, id) {
-    const m = new RegExp(`(?:^|\\n)prized-output ${id} (?:([0-9]+) ([0-9]+)|(gone))\\n$`).exec(stdout);
+    const m = new RegExp(`(?:^|\\n)prized-output ${id} (?:([0-9]+) ([0-9]+)(?: ([01]) ([01]))?|(gone))\\n$`).exec(stdout);
     if (m === null)
         return null;
-    if (m[3] === 'gone')
+    if (m[5] === 'gone')
         return 'gone';
-    return { out: Number(m[1]), err: Number(m[2]) };
+    return { out: Number(m[1]), err: Number(m[2]), outFailed: m[3] === '1', errFailed: m[4] === '1' };
+}
+/** Why the read-back output is cut, if it is: a failed write first, since it is the one the caller cannot foresee. */
+function markerTruncation(marker) {
+    if (marker.outFailed || marker.errFailed)
+        return 'write_failed';
+    if (marker.out > exports.FULL_OUTPUT_BYTES || marker.err > exports.FULL_OUTPUT_BYTES)
+        return 'output_limit';
+    return null;
 }
 /** A request the SDK sends on its own to collect or remove the files: best effort, within TEARDOWN_MS. */
 async function teardown(toolbox, script) {
@@ -201,7 +287,7 @@ async function download(toolbox, path, signal) {
     return new TextDecoder('utf-8', { ignoreBOM: true }).decode(result.bytes ?? new Uint8Array(0));
 }
 /** The files' contents in place of the answer's output. */
-async function readBack(toolbox, id, sizes, result, signal) {
+async function readBack(toolbox, id, marker, result, signal) {
     const dir = `${exports.OUTPUT_DIR}/${id}`;
     // Both at once; one that fails stops the other, as the caller's abort stops both.
     const both = new AbortController();
@@ -218,17 +304,17 @@ async function readBack(toolbox, id, sizes, result, signal) {
     let stdout;
     let stderr;
     try {
-        [stdout, stderr] = await Promise.all([read('stdout', sizes.out), read('stderr', sizes.err)]);
+        [stdout, stderr] = await Promise.all([read('stdout', marker.out), read('stderr', marker.err)]);
     }
     finally {
         signal?.removeEventListener('abort', stop);
     }
-    return {
-        ...result,
-        stdout,
-        stderr,
-        truncated: sizes.out > exports.FULL_OUTPUT_BYTES || sizes.err > exports.FULL_OUTPUT_BYTES,
-    };
+    const reason = markerTruncation(marker);
+    const { exitCode, durationMs, timedOut } = result;
+    const full = { stdout, stderr, exitCode, durationMs, timedOut, truncated: reason !== null };
+    if (reason !== null)
+        full.truncatedReason = reason;
+    return full;
 }
 /**
  * A blocking exec that keeps the whole output (up to FULL_OUTPUT_BYTES of
@@ -253,22 +339,22 @@ async function execFullOutput(toolbox, id, req, signal) {
         await teardown(toolbox, removeOutputScript(id));
         throw error;
     }
-    let sizes = parseMarker(result.stdout, id);
-    if (sizes === null && (result.timedOut || result.exitCode === -1)) {
+    let marker = parseMarker(result.stdout, id);
+    if (marker === null && (result.timedOut || result.exitCode === -1)) {
         // Its time limit (or a signal) ended the script with the command, before
         // it printed anything back: what the command printed is in its files.
         const collected = await teardown(toolbox, collectScript(id));
-        sizes = collected === null ? null : parseMarker(collected.stdout, id);
-        if (sizes === null)
+        marker = collected === null ? null : parseMarker(collected.stdout, id);
+        if (marker === null)
             return result; // no answer: nothing more to be done
     }
     // No marker: the output came back in the answer (or the command ran as a
     // plain exec), and the directory is already gone.
-    if (sizes === null || sizes === 'gone')
+    if (marker === null || marker === 'gone')
         return result;
     let full;
     try {
-        full = await readBack(toolbox, id, sizes, result, signal);
+        full = await readBack(toolbox, id, marker, result, signal);
     }
     catch (error) {
         const aborted = !(error instanceof errors_js_1.PrizedError) || error.code === 'aborted';
@@ -279,9 +365,18 @@ async function execFullOutput(toolbox, id, req, signal) {
                 throw error;
             return result;
         }
+        if (error.code === 'sandbox_deleted') {
+            // Nothing is kept: the output went with the sandbox, as its code says for any call on it.
+            // The command ran: its exit code goes on the error too, so a caller
+            // that replaces the sandbox can tell not to run it again.
+            throw (0, outcome_js_1.restate)(error, `The command ran (exit ${result.exitCode}), but the sandbox was deleted before its output could be read back.`, {
+                cause: error,
+                exitCode: result.exitCode,
+            });
+        }
         const dir = `${exports.OUTPUT_DIR}/${id}`;
-        throw (0, outcome_js_1.restate)(error, `The command ran (exit ${result.exitCode}), but its output could not be read back (${error.message.replace(/[.\s]+$/, '')}). ` +
-            `It is kept in ${dir}/stdout and ${dir}/stderr for an hour: read them with files.read(), then remove ${dir}.`);
+        throw new errors_js_1.OutputReadError(`The command ran (exit ${result.exitCode}), but its output could not be read back (${error.message.replace(/[.\s]+$/, '')}). ` +
+            `It is kept in ${dir}/stdout and ${dir}/stderr for an hour: read them with files.read(), then remove ${dir}.`, { cause: error, exitCode: result.exitCode, stdoutPath: `${dir}/stdout`, stderrPath: `${dir}/stderr` });
     }
     await teardown(toolbox, removeOutputScript(id));
     return full;

package/dist/cjs/sandbox.js

@@ -228,6 +228,32 @@ function failedState(info) {
     }
     return null;
 }
+/** How the API's errorReason starts on each copy it deletes because another
+ *  copy of the same fork could not start. */
+const FORK_UNDONE_PREFIX = 'fork undone';
+/**
+ * The error a fork throws when not every copy runs, or null. The API undoes
+ * a fork one of whose copies could not start, deleting every copy, so the
+ * copy that failed may already read `deleting`, with its errorReason, by the
+ * time it is read: the error is that copy's reason (one that is not the
+ * undo's own), else a copy in error, else any non-running copy's state.
+ */
+function forkFailure(copies) {
+    const failed = copies.filter((copy) => copy.state !== 'running');
+    if (failed.length === 0)
+        return null;
+    const cause = failed.find((copy) => copy.errorReason && !copy.errorReason.startsWith(FORK_UNDONE_PREFIX)) ??
+        failed.find((copy) => copy.state === 'error') ??
+        failed.find((copy) => copy.errorReason) ??
+        failed[0];
+    if (cause.errorReason) {
+        return new errors_js_1.PrizedError('sandbox_error', `The sandbox failed: ${cause.errorReason}`, {
+            sandboxId: cause.id,
+            reason: cause.errorReason,
+        });
+    }
+    return failedState(cause) ?? new errors_js_1.PrizedError('sandbox_error', null, { sandboxId: cause.id });
+}
 /**
  * A wait's timeout. One ended by a read its deadline cut short (the retry it
  * was due would have ended past it: a 503's Retry-After, say) may come
@@ -563,9 +589,9 @@ class Sandbox {
             return children;
         try {
             await Sandbox.settle(this.config, children, deadline, timeoutMs, options.signal, this.id);
-            const failed = children.find((child) => child.state !== 'running');
+            const failed = forkFailure(children.map((child) => child.current));
             if (failed)
-                throw failedState(failed.current) ?? new errors_js_1.PrizedError('sandbox_error', null, { sandboxId: failed.id });
+                throw failed;
         }
         catch (error) {
             // All or nothing: copies the caller will never get are not left billing.

package/dist/cjs/toolbox.js

@@ -63,13 +63,15 @@ async function rawExec(toolbox, req, options) {
     }
     const stdout = typeof doc.stdout === 'string' ? doc.stdout : '';
     const stderr = typeof doc.stderr === 'string' ? doc.stderr : '';
+    const truncated = keptBytes(stdout) >= exports.MAX_OUTPUT_BYTES || keptBytes(stderr) >= exports.MAX_OUTPUT_BYTES;
     return {
         stdout,
         stderr,
         exitCode: doc.exitCode,
         durationMs: typeof doc.durationMs === 'number' ? doc.durationMs : 0,
         timedOut: doc.timedOut === true,
-        truncated: keptBytes(stdout) >= exports.MAX_OUTPUT_BYTES || keptBytes(stderr) >= exports.MAX_OUTPUT_BYTES,
+        truncated,
+        ...(truncated ? { truncatedReason: 'output_limit' } : {}),
     };
 }
 /** A helper command the SDK sends itself; a non-zero exit is the caller's to judge. */

package/dist/cjs/types.d.ts

@@ -70,10 +70,22 @@ export interface ExecResult {
      * True when stdout or stderr reached the 4 MiB per-stream cap of a single
      * call: the command kept running, the rest of that stream was dropped.
      * Pass `fullOutput: true` for commands that may print more (it keeps up
-     * to 100 MiB of each stream, and sets this past that).
+     * to 100 MiB of each stream, and sets this past that). `truncatedReason`
+     * says why.
      */
     truncated: boolean;
+    /**
+     * Why `truncated` is true; absent when it is false. `output_limit`: a
+     * stream reached its cap (4 MiB in one call, 100 MiB with `fullOutput`).
+     * `write_failed` (`fullOutput` only): the sandbox could not save a stream
+     * as the command printed it, most often because its disk is full, so that
+     * stream stops where the write failed, however short; free some space and
+     * run it again.
+     */
+    truncatedReason?: TruncatedReason;
 }
+/** Why a command's output was cut: ExecResult.truncatedReason. */
+export type TruncatedReason = 'output_limit' | 'write_failed';
 /** One directory entry, as `sandbox.files.list()` returns it. */
 export interface FileInfo {
     name: string;

package/dist/cjs/version.d.ts

@@ -1,2 +1,2 @@
 /** This package's version; test/version.test.ts holds it equal to package.json. */
-export declare const VERSION = "0.1.0";
+export declare const VERSION = "0.1.1";

package/dist/cjs/version.js

@@ -2,4 +2,4 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.VERSION = void 0;
 /** This package's version; test/version.test.ts holds it equal to package.json. */
-exports.VERSION = '0.1.0';
+exports.VERSION = '0.1.1';

package/dist/esm/commands.d.ts

@@ -19,20 +19,34 @@ export declare const MAX_BLOCKING_EXEC_MS = 240000;
 export declare function ridesOut(error: PrizedError): boolean;
 /**
  * The failed polls of a wait that rides out an outage of up to `windowMs`
- * (exec's pollOutageMs), from when the first poll's retries ran out: polled
- * again with backoff, each poll and its retries ending before the last look,
- * which goes out LAST_LOOK_MAX_MS before the window's end (half the window,
- * for one shorter than twice that) with room for its own retries. So an
- * outage that ends inside the window is always seen to end. The Python
- * SDK's Outage.
+ * (pollOutageMs), from when the first poll's retries ran out, and, while the
+ * command runs, never past the wait's own deadline (`waitDeadline`, epoch
+ * ms; null for none): polled again with backoff, each poll and its retries
+ * ending before the last look, which goes out LAST_LOOK_MAX_MS before the
+ * window's end (half the window, for one shorter than twice that) with room
+ * for its own retries. So an outage that ends inside the window is always
+ * seen to end. The Python SDK's Outage.
  */
 export declare class Outage {
     private readonly windowMs;
+    private readonly waitDeadline;
     private end;
     private last;
     private tries;
-    private readonly room;
-    constructor(windowMs: number);
+    private room;
+    private finished;
+    constructor(windowMs: number, waitDeadline?: number | null);
+    /** The command has ended: draining its output, and an outage meanwhile, are not held to the deadline. */
+    finish(): void;
+    /**
+     * Whether a wait's failed poll (`error`, at `now`; `cut`: its bound cut it
+     * short) means the wait's own time ran out: its deadline cut the poll
+     * short while the command ran, with no outage being ridden out, so the
+     * command was still running when last seen. With no window, any timeout
+     * while it runs says so, as it always has. Never once the command has
+     * ended. The Python SDK's Outage.ran_out.
+     */
+    ranOut(error: PrizedError, now: number, cut: boolean): boolean;
     /** The bound on a poll sent `now`: undefined unless polls are failing; else the last look's start, or the window's end for the last look. */
     deadline(now: number): number | undefined;
     /** A poll was answered: the outage, if any, is over. */
@@ -95,11 +109,26 @@ export interface ExecOptions {
     pollOutageMs?: number;
 }
 export interface WaitOptions {
-    /** Stop waiting after this many ms (the command keeps running). Default: no limit. */
+    /**
+     * Stop waiting after this many ms (the command keeps running). Default: no
+     * limit. Once the command has ended, reading the rest of its output is not
+     * held to it.
+     */
     timeoutMs?: number;
     onStdout?: (chunk: string) => void;
     onStderr?: (chunk: string) => void;
     signal?: AbortSignal;
+    /**
+     * How long the wait keeps polling while its polls fail (no answer, a 5xx,
+     * a rate limit), in ms, before it gives up and throws what the polls met.
+     * While the command runs, never past `timeoutMs`. Default: the client's
+     * `pollOutageMs` (120 000).
+     * `0` gives up once one poll's retries run out. A refused key, or an
+     * answer that settles the run (the sandbox deleted or not running, the
+     * run gone), ends the wait at once. Giving up stops nothing: the command
+     * keeps running, and wait() can be called again.
+     */
+    pollOutageMs?: number;
 }
 export interface CommandStatus {
     running: boolean;
@@ -136,15 +165,17 @@ export declare class CommandHandle {
      * `onStdout`/`onStderr` receive the output as it arrives, from the start.
      * A `timeoutMs` here bounds the wait only; the command keeps running. If
      * the command ran past its own timeout (the one given to exec), it was
-     * killed and this throws CommandTimeoutError with what it printed.
+     * killed and this throws CommandTimeoutError with what it printed. While
+     * polls fail (a dropped connection, a 5xx), it keeps polling for up to
+     * `pollOutageMs` (the client's, 120 000 by default) before it throws.
      */
     wait(options?: WaitOptions): Promise<ExecResult>;
     /**
      * @internal wait() without the timeout check: exec cleans up before it
-     * throws. `outageMs` (exec's pollOutageMs; a wait with no limit only):
-     * how long polls may fail before the wait gives up (Outage).
+     * throws. `outageMs` (pollOutageMs): how long polls may fail before the
+     * wait gives up (Outage), never past the wait's own deadline.
      */
-    waitRaw(options?: WaitOptions, outageMs?: number): Promise<ExecResult>;
+    waitRaw(options: WaitOptions, outageMs: number): Promise<ExecResult>;
     private waitTimeout;
     private result;
     /**