@prized/sdk 0.1.0 → 0.1.2

package/README.md

@@ -47,7 +47,9 @@ No runtime dependencies. ESM and CommonJS, with type declarations.
 Make an API key on the [API keys page](https://prized.dev/dashboard/workspace/api-keys)
 and put it in `PRIZED_API_KEY`, or pass it in. New to Prized?
 [Open Sandboxes](https://prized.dev/onboarding/sandboxes) signs you up (free
-credit, no card) and makes one.
+credit, no card) and makes one. Or your coding agent can sign you up itself
+with your email and a 6-digit code: have it follow
+[prized.dev/auth.md](https://prized.dev/auth.md).
 
 ```ts
 const sandbox = await Sandbox.create({ apiKey: 'dcp_…' });
@@ -58,19 +60,31 @@ to fewer permissions needs **Sandboxes: Write** to create, run commands and
 move files; **Sandboxes: Read** is enough for `list`, `connect`, `refresh` and
 `templates`.
 
+Your coding agent can install the Prized skill with `npx skills add prized-dev/skills -g -y` (it should ask you first), so it knows when and how to use Prized the next time you ask for a sandbox.
+
 Every entry point (`create`, `connect`, `list`, `deleteByLabels`, `templates`) takes the same
 client options:
 
 | Option | Default | |
 |---|---|---|
 | `apiKey` | `process.env.PRIZED_API_KEY` | |
-| `baseUrl` | `https://api.prized.dev` | The API origin. |
-| `edgeUrl` | the sandbox's own `toolboxBase` | Where commands and files go. |
+| `baseUrl` | `https://api.prized.dev` | The API origin: `https`, or plain `http` on `localhost`, `127.0.0.1` or `[::1]`. |
+| `edgeUrl` | the sandbox's own `toolboxBase` | Where commands and files go, by the same rule. Pass it for another deployment whose API names its command endpoint on another host. |
 | `fetch` | global `fetch` | Bring your own (for a proxy, custom agent, tests). |
 | `maxRetries` | `3` | See [Retries](#retries-and-timeouts). |
 | `requestTimeoutMs` | `60000` | Per API request. |
 | `pollIntervalMs` | `500` | The longest the SDK's own polling goes between checks of the sandbox (the first come sooner). It does not cover the request itself, or the time the API holds a create, pause or resume for you (up to 8 seconds). |
-| `pollOutageMs` | `120000` | How long a streamed or long `exec` keeps polling through a dropped connection (or a 5xx, or a rate limit) before it stops the command. `exec` takes it per call too. |
+| `pollOutageMs` | `120000` | How long a wait keeps polling through a dropped connection (or a 5xx, or a rate limit) before it gives up: a streamed or long `exec` then stops the command, a handle's `wait()` throws. A background, streamed or long `exec` keeps sending its start for as long. `exec` and `wait()` take it per call too. |
+
+Your API key goes with every request, so a plain `http` URL to a host other
+than this machine is refused with `invalid_argument` before anything is sent,
+whatever `fetch` you pass. Without `edgeUrl`, a sandbox's `toolboxBase` is used
+only on the API's own host, on Prized's own hosts beside Prized's API, or on
+this machine beside a local API. Otherwise commands and files go to Prized's
+edge for Prized's API; for any other API they throw `edge_unknown`, so its key
+never reaches Prized's edge. Take `baseUrl`, `edgeUrl` and `fetch` only from
+configuration you trust: what they name gets your key, your commands and your
+files.
 
 A sandbox remembers the options it was made with: its methods need none.
 
@@ -169,8 +183,10 @@ await Promise.all(mine.map((s) => s.delete()));
 ### `Sandbox.deleteByLabels(labels, options?)`
 
 Deletes every sandbox carrying all of `labels` (at least one) in one call and
-resolves with their ids. It is safe to repeat (one already deleting is listed
-again; none matching resolves `[]`). A sandbox being deleted still counts
+resolves with their ids. Each request selects the current matches, including
+sandboxes created since an earlier request. If an answer is lost, the SDK
+throws without repeating the delete; list the matches before deleting again.
+A sandbox being deleted still counts
 toward your quota until `Sandbox.list({ labels })` no longer returns it.
 
 ```ts
@@ -212,6 +228,7 @@ r.stderr;      // string, kept separate
 r.exitCode;    // number
 r.durationMs;
 r.truncated;   // true if stdout or stderr hit the 4 MiB per-call cap
+r.truncatedReason; // why, when truncated: 'output_limit' or 'write_failed'
 
 await sandbox.exec(['git', 'commit', '-m', "it's done"]); // quoted for you
 ```
@@ -225,6 +242,14 @@ small; past 4 MiB the SDK reads it back from files in
 ends gets `exitCode` 128+n (a plain exec may give -1), as a background command
 does.
 
+`truncatedReason` says why a result is cut: `output_limit` for a stream
+that reached its cap, `write_failed` when the sandbox could not save a
+stream as the command printed it (most often a full disk), so it stops where
+the write failed. If the output can't be read back afterwards, the call
+throws `OutputReadError` (`code` `output_read_failed`): the command ran
+(`err.exitCode`), `err.reason` says what stopped the read, and the output
+stays at `err.stdoutPath` and `err.stderrPath` for an hour.
+
 ```ts
 const { stdout, exitCode } = await sandbox.exec('npm test', { timeoutMs: 180_000, fullOutput: true });
 ```
@@ -266,7 +291,9 @@ off by an idle connection and its output is never truncated. The result is
 the same either way. If the connection drops meanwhile, the SDK keeps
 polling for up to 2 minutes (`pollOutageMs`, on the call or the client)
 before it gives up and stops the command; a refused key, or an answer that
-settles it (the sandbox deleted or not running), stops it at once.
+settles it (the sandbox deleted or not running), stops it at once. Its
+start rides one out the same way: it is sent again for up to `pollOutageMs`,
+and a resend finds the first start, so the command runs once.
 Background and streamed commands run with `PYTHONUNBUFFERED=1` unless
 their environment already sets it (`env: { PYTHONUNBUFFERED: '' }` keeps
 Python's buffering), so a Python program's output arrives as it prints.
@@ -280,7 +307,11 @@ you need into your home: Python packages into a venv
 
 ## Background commands
 
-`background: true` starts the command and returns a `CommandHandle` at once.
+`background: true` starts the command and returns a `CommandHandle` once it
+has started. A start that meets a dropped connection or a 5xx is sent again
+for up to `pollOutageMs` once its own retries run out (a resend finds the
+first start, so the command runs once), so the call can take that long while
+the connection is down.
 The command runs in its own session: it keeps running after your process
 exits, survives a pause and resume, and while it runs, a kill reaches every
 process it started (not one that left its process group, such as a daemon).
@@ -306,6 +337,13 @@ result.exitCode;
 await job.cleanup();  // remove its output files from the sandbox
 ```
 
+`wait()` rides out a dropped connection too: while its polls fail (no
+answer, a 5xx, a rate limit) it keeps polling for up to `pollOutageMs` (2
+minutes by default, on the call or the client; while the command runs,
+never past its `timeoutMs`) before it throws what they met. A refused key,
+or an answer that settles the run, throws at once. Either way the command
+keeps running and the handle stays good: call `wait()` again.
+
 A background command has no time limit unless you give `timeoutMs`
 (enforced to the second: the command gets SIGTERM, then SIGKILL five seconds
 later, and `wait()` throws `CommandTimeoutError`). Its output is kept under
@@ -321,9 +359,10 @@ sandbox's disk there, so redirect such output yourself.
 ## Files
 
 `sandbox.files` reads and writes the sandbox's disk. Paths are absolute or
-relative to `/home/prized/work`. Writes, reads, uploads and downloads must
-stay inside `/home/prized`, are at most 100 MiB each, and do not follow
-symbolic links. A write replaces the file whole, and a file it replaces keeps
+relative to `/home/prized/work`. Writes, reads, uploads and downloads are at
+most 100 MiB each, and their paths in the sandbox must stay inside
+`/home/prized` and not go through a symbolic link (`symlink_not_allowed`).
+A write replaces the file whole, and a file it replaces keeps
 its mode, so a script made executable stays executable; a new file gets the
 sandbox's default (`0600` in `prized-base-v1` and `prized-agent-v1`). `mode` sets the permission
 bits.
@@ -511,12 +550,14 @@ try {
 | `file_too_large` | 413 | Over the 100 MiB transfer limit. |
 | `idempotency_conflict` | 409 | The idempotency key was used for a different request. |
 | `sandbox_error` | | The sandbox failed while you waited; `reason` says why. |
-| `sandbox_deleted` | 410 | The sandbox was deleted before or while a command or file call ran; a command that was running stopped with it. `pause()` and `resume()` of a sandbox being deleted throw it too. Not retried. A wait that finds the sandbox deleted throws it too, with no status. |
+| `sandbox_deleted` | 410 | The sandbox was deleted before or while a command or file call ran; a command that was running stopped with it. `pause()` and `resume()` of a sandbox being deleted throw it too. Not retried. A wait that finds the sandbox deleted throws it too, with no status. When a `fullOutput` command ran and the sandbox went before its output was read back, `err.exitCode` is the command's exit code (null otherwise): it ran, so don't run it again blindly in a new sandbox. |
 | `command_timeout` | | A command ran past its own `timeoutMs` and was killed. Thrown as `CommandTimeoutError`; `err.result` has what it printed. |
+| `output_read_failed` | | A `fullOutput` command ran, but its output could not be read back. Thrown as `OutputReadError`: `err.exitCode` is the command's, `err.reason` the code of what stopped the read (also in `cause`), and the output stays at `err.stdoutPath` / `err.stderrPath` for an hour. The sandbox is not known to be gone (a deleted one throws `sandbox_deleted`); don't run the command again blindly. |
 | `timeout` | | A wait ran past its `timeoutMs`, or a call past its bound ([Retries](#retries-and-timeouts)). One that ended because a retry could not start in time says what the last attempt met (also in `cause`). |
 | `network_error` | | No answer: the API or the sandbox could not be reached, or the connection dropped. |
 | `bad_response` | 2xx | An answer the SDK could not read. For a command or file write it did happen, and the message says so. |
 | `missing_api_key` / `invalid_api_key` / `invalid_argument` | | Fix the call. `invalid_api_key`: the key has characters no key has (the docs' placeholder, a stray character); it is never quoted back. |
+| `edge_unknown` | | A `baseUrl` other than Prized's whose API named no command endpoint the SDK trusts (on the API's own host, or on this machine beside a local API): pass `edgeUrl`. The command or file call was not sent. |
 | `command_failed` | | A file helper (`list`, `remove`, `exists`) failed in the sandbox; `message` has its stderr. |
 
 ## Retries and timeouts
@@ -534,15 +575,23 @@ try {
   `resume`, `fork` and `delete` (the request, its retries and the wait, its
   polls included; with `wait: false` too), twice `requestTimeoutMs` (2
   minutes by default) for `connect`, `list`, `templates`, `refresh` and
-  `keepAlive`, and 10 minutes for a file transfer. `Retry-After` is honoured
+  `keepAlive`, and 10 minutes for a file transfer, whose attempt is given up
+  after 2 minutes with no bytes moving (a dropped connection) and sent again
+  by the rules below (on Node's own `fetch`; elsewhere, or with a `fetch` you
+  pass, an upload is watched only once its answer starts). `Retry-After` is honoured
   up to a minute. A retry that could not start in time is not sent: the call
   throws `timeout`. A wait's last poll goes out just before its deadline.
-- A command, an upload (`files.write`, `files.upload`), a `files.remove` or
-  a `kill` is sent again only when it provably never arrived: the connection never
-  opened, or the answer says so (rate limited, the sandbox not ready). If an
-  answer is lost after it was delivered, the SDK throws
-  (`sandbox_unreachable`, `network_error`, `timeout`) rather than risk running a command
-  twice or overwriting what the sandbox wrote to the file since.
+- A command, a `files.remove`, a `kill` or `deleteByLabels` is sent again only when it
+  provably never arrived: the connection never opened, or the answer says so
+  (rate limited, the sandbox not ready). If an answer is lost after it was
+  delivered, the SDK throws (`sandbox_unreachable`, `network_error`,
+  `timeout`) rather than risk repeating the operation on work that changed.
+- A file write (`files.write`, `files.upload`) goes up under a temporary name
+  beside the file, which is sent again like a read (a lost answer, a 502, 503
+  or 504, 2 minutes with no bytes moving), every copy to the same name and
+  none after the transfer's 10 minutes. One command that is never
+  sent again then puts it in place: if that command's answer is lost, the SDK
+  throws rather than risk overwriting what the sandbox wrote to the file since.
 - Did it run? When a command answered in one call (`exec` without
   `background`, `onStdout` or `onStderr`, and a `timeoutMs` other than 0 and
   at most 4 minutes), a file write or a `files.remove` fails without a plain refusal,
@@ -552,10 +601,14 @@ try {
   clear answer came back (a dropped connection, a timeout, or any other 5xx):
   it may or may not have run, and the message says how to check (read the
   file back, `files.exists()`). A 2xx came back that could not be read
-  (`bad_response`): it ran. A `kill` says the same of its signal
+  (`bad_response`): it ran. A write whose upload got no clear answer says the file was
+  not changed (its new bytes may have reached the sandbox under the
+  temporary name, which the SDK then removes): write it again. A `kill`
+  says the same of its signal
   (`status()` tells you whether the command is still running). A background
   command (or a streamed or long `exec`, which runs as one) whose start got
-  no clear answer is stopped by the SDK, and the error says so, or, when the
+  no clear answer for longer than `pollOutageMs` is stopped by the SDK, and
+  the error says so, or, when the
   SDK could not confirm the stop, that it may still be running and under
   which run id. So is a streamed or long `exec` whose polling fails while
   it runs (a dropped connection or a 5xx for longer than `pollOutageMs`, a
@@ -563,6 +616,8 @@ try {
   poll's own error as its `cause`, and says whether the SDK stopped the
   command or it may still be running. An error that settles it (the
   sandbox deleted or not running, the run not found) is thrown as it came.
+  A handle's `wait()` whose polls fail for longer than `pollOutageMs` throws
+  the poll's own error; it stops nothing.
 - Deleting what a failed create or fork made (a few seconds) comes on top
   of `timeoutMs`.
 - `create`, `exec` and waits take an `AbortSignal` (`signal`). Aborting a

package/dist/cjs/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. */
@@ -90,16 +104,33 @@ export interface ExecOptions {
      * its polls fail (no answer, a 5xx, a rate limit), in ms, before it gives
      * up and stops the command. Default: the client's `pollOutageMs`
      * (120 000). A refused key, or an answer that settles the run (the
-     * sandbox deleted or not running, the run gone), stops it at once.
+     * sandbox deleted or not running, the run gone), stops it at once. The
+     * start of a background, streamed or long command is sent again for as
+     * long (a resend finds the first start, so the command runs once).
      */
     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 +167,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;
     /**

package/dist/cjs/commands.js

@@ -70,22 +70,42 @@ function ridesOut(error) {
 }
 /**
  * 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.
  */
 class Outage {
     windowMs;
+    waitDeadline;
     end = null;
     last = null;
     tries = 0;
-    room;
-    constructor(windowMs) {
+    room = 0;
+    finished = false;
+    constructor(windowMs, waitDeadline = null) {
         this.windowMs = windowMs;
-        this.room = Math.min(http_js_1.LAST_LOOK_MAX_MS, windowMs / 2);
+        this.waitDeadline = waitDeadline;
+    }
+    /** The command has ended: draining its output, and an outage meanwhile, are not held to the deadline. */
+    finish() {
+        this.finished = true;
+    }
+    /**
+     * 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, now, cut) {
+        if (this.waitDeadline === null || this.finished || error.code !== 'timeout')
+            return false;
+        return this.windowMs <= 0 || (this.end === null && (cut || now >= this.waitDeadline));
     }
     /** 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) {
@@ -109,7 +129,10 @@ class Outage {
     failed(error, sentAt, now, cut, backoff) {
         if (this.windowMs <= 0 || !ridesOut(error))
             return { pause: null, failure: error };
-        this.end ??= now + this.windowMs;
+        if (this.end === null) {
+            this.end = Math.min(now + this.windowMs, this.finished || this.waitDeadline === null ? Infinity : this.waitDeadline);
+            this.room = Math.max(0, Math.min(http_js_1.LAST_LOOK_MAX_MS, (this.end - now) / 2));
+        }
         const met = error.cause instanceof errors_js_1.PrizedError ? error.cause : null;
         if (!cut) {
             this.last = error;
@@ -278,17 +301,20 @@ 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.
      */
     async wait(options = {}) {
-        return finished(await this.waitRaw(options), this.timeoutMs, this.sandboxId);
+        const outageMs = (0, http_js_1.validOutage)(options.pollOutageMs) ?? this.toolbox.config.pollOutageMs;
+        return finished(await this.waitRaw(options, outageMs), this.timeoutMs, this.sandboxId);
     }
     /**
      * @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.
      */
-    async waitRaw(options = {}, outageMs = 0) {
+    async waitRaw(options, outageMs) {
         const config = this.toolbox.config;
         const deadline = options.timeoutMs ? config.now() + options.timeoutMs : null;
         const out = new StreamReader(options.onStdout);
@@ -296,7 +322,7 @@ class CommandHandle {
         let delay = POLL_MIN_MS;
         let finished = false;
         const polls = deadline === null ? null : new http_js_1.Polls(config, deadline);
-        const outage = new Outage(deadline === null ? outageMs : 0);
+        const outage = new Outage(outageMs, deadline);
         for (;;) {
             let report;
             const sentAt = config.now();
@@ -311,13 +337,15 @@ class CommandHandle {
                 polls?.answered();
             }
             catch (error) {
-                if (deadline !== null && error instanceof errors_js_1.PrizedError && error.code === 'timeout')
+                const now = config.now();
+                if (error instanceof errors_js_1.PrizedError && outage.ranOut(error, now, (0, http_js_1.cutByDeadline)(error))) {
                     throw this.waitTimeout(options.timeoutMs);
+                }
                 let failure = error;
                 if (error instanceof errors_js_1.PrizedError && !options.signal?.aborted) {
                     // A dropped connection, an edge restarting: the command may be
                     // fine. Poll again until the window runs out, then give up.
-                    const step = outage.failed(error, sentAt, config.now(), (0, http_js_1.cutByDeadline)(error), (tries) => (0, http_js_1.backoffMs)(config, tries));
+                    const step = outage.failed(error, sentAt, now, (0, http_js_1.cutByDeadline)(error), (tries) => (0, http_js_1.backoffMs)(config, tries));
                     if (step.pause !== null) {
                         await config.sleep(step.pause, options.signal);
                         continue;
@@ -329,8 +357,10 @@ class CommandHandle {
                 throw failure;
             }
             outage.answered();
-            if (report.state !== 'running')
+            if (report.state !== 'running') {
                 finished = true;
+                outage.finish();
+            }
             out.push(report.stdout);
             err.push(report.stderr);
             const more = (report.stdout.length > 0 && out.offset < report.outSize) ||
@@ -447,7 +477,48 @@ async function cleanupOnceGone(toolbox, id) {
         }
     }
 }
-async function startBackground(toolbox, command, cwd, env, timeoutMs, signal, unbuffered) {
+/**
+ * Send a start script. It is keyed by a run id the SDK chose, so a resend
+ * finds the first start instead of starting the command twice. Once one
+ * copy's retries run out, it is sent again through an outage of up to
+ * `outageMs` (pollOutageMs), paced as a wait's polls are (Outage): an edge
+ * that restarts mid-start does not cost the command, as it does not cost a
+ * running one its wait. Each copy's error counts the copies before it
+ * (`acted`), so one that gives up says the command may have started when any
+ * copy may have reached the sandbox. The Python SDK's _send_start.
+ */
+async function sendStart(toolbox, req, signal, outageMs) {
+    const config = toolbox.config;
+    const outage = new Outage(outageMs);
+    // Whether an earlier copy may have reached the sandbox: an abort between
+    // copies then says the command may have started, else that it never did.
+    let acted = false;
+    const aborted = (cause) => (0, outcome_js_1.withAbort)(new errors_js_1.PrizedError('aborted', null, { sandboxId: toolbox.sandboxId, cause }), (0, outcome_js_1.startEffect)(), acted ? 'maybe' : 'never');
+    for (;;) {
+        const sentAt = config.now();
+        try {
+            return await (0, toolbox_js_1.rawExec)(toolbox, req, { retry: 'safe', signal, deadline: outage.deadline(sentAt), effect: (0, outcome_js_1.startEffect)(), acted });
+        }
+        catch (error) {
+            if (!(error instanceof errors_js_1.PrizedError))
+                throw error;
+            acted = acted || (0, outcome_js_1.mayHaveActed)(error);
+            if (signal?.aborted)
+                throw error;
+            const step = outage.failed(error, sentAt, config.now(), (0, http_js_1.cutByDeadline)(error), (tries) => (0, http_js_1.backoffMs)(config, tries));
+            // What a copy met, not the window's cut.
+            if (step.pause === null)
+                throw step.failure === error ? error : (0, outcome_js_1.startGaveUp)(step.failure, acted);
+            try {
+                await config.sleep(step.pause, signal);
+            }
+            catch (abort) {
+                throw abort instanceof errors_js_1.PrizedError && abort.code === 'aborted' ? aborted(step.failure) : abort;
+            }
+        }
+    }
+}
+async function startBackground(toolbox, command, cwd, env, timeoutMs, signal, unbuffered, outageMs) {
     // Nothing sent yet: nothing to stop.
     if (signal?.aborted)
         throw (0, outcome_js_1.withOutcome)(new errors_js_1.PrizedError('aborted', null, { sandboxId: toolbox.sandboxId }), (0, outcome_js_1.startEffect)(), 'never');
@@ -459,10 +530,7 @@ async function startBackground(toolbox, command, cwd, env, timeoutMs, signal, un
     // Launched, but no pid came within the start's own wait: it may yet run.
     let unsettled = false;
     try {
-        const result = await (0, toolbox_js_1.rawExec)(toolbox, { command: (0, shell_js_1.startScript)(id, command, timeoutMs === null ? null : timeoutMs / 1000, unbuffered), cwd, env, timeoutMs: 60_000 }, 
-        // Keyed by a run id this call chose, so a resend finds the first start
-        // instead of starting the command twice.
-        { retry: 'safe', signal, effect: (0, outcome_js_1.startEffect)() });
+        const result = await sendStart(toolbox, { command: (0, shell_js_1.startScript)(id, command, timeoutMs === null ? null : timeoutMs / 1000, unbuffered), cwd, env, timeoutMs: 60_000 }, signal, outageMs);
         pid = Number(result.stdout.trim());
         if (result.exitCode !== 0 || !Number.isInteger(pid) || pid <= 0) {
             unsettled = result.exitCode === shell_js_1.NO_PID_EXIT;
@@ -508,7 +576,7 @@ async function execCommand(toolbox, command, options = {}) {
     const cwd = options.cwd === undefined ? undefined : (0, shell_js_1.sandboxPath)(options.cwd);
     if (options.background) {
         const limit = options.timeoutMs ? options.timeoutMs : null;
-        const handle = await startBackground(toolbox, text, cwd, options.env, limit, options.signal, true);
+        const handle = await startBackground(toolbox, text, cwd, options.env, limit, options.signal, true, outageMs);
         handle.timeoutMs = limit;
         return handle;
     }
@@ -516,7 +584,7 @@ async function execCommand(toolbox, command, options = {}) {
     const streamed = options.onStdout !== undefined || options.onStderr !== undefined;
     if (streamed || timeoutMs === 0 || timeoutMs > exports.MAX_BLOCKING_EXEC_MS) {
         const limit = timeoutMs === 0 ? null : timeoutMs;
-        const handle = await startBackground(toolbox, text, cwd, options.env, limit, options.signal, streamed);
+        const handle = await startBackground(toolbox, text, cwd, options.env, limit, options.signal, streamed, outageMs);
         const waitOptions = {};
         if (options.onStdout)
             waitOptions.onStdout = options.onStdout;

package/dist/cjs/errors.d.ts

@@ -3,6 +3,11 @@ import type { ExecResult } from './types.js';
 export declare const API_KEYS_URL = "https://prized.dev/dashboard/workspace/api-keys";
 /** Where a newcomer signs up (free credit, no card) and gets one. */
 export declare const SIGN_UP_URL = "https://prized.dev/onboarding/sandboxes";
+/** What a coding agent follows to sign its person up and get a key itself:
+ * their email address, then the 6-digit code Prized emails them. The SDK's
+ * own key errors name it; a refused key's 401 carries the API's own line
+ * (`signUp`), which follows the deployment. */
+export declare const AGENT_SIGN_UP_URL = "https://prized.dev/auth.md";
 /** The free tier's limits, and what lifts them. */
 export declare const FREE_TIER_URL = "https://prized.dev/docs/sandboxes#free-tier";
 /** The sentence an error with this code and no message of its own carries. */
@@ -17,6 +22,8 @@ export interface PrizedErrorInit {
     body?: Record<string, unknown> | null;
     /** Seconds the API asked the caller to wait (Retry-After). */
     retryAfter?: number | null;
+    /** The command's exit code, for an error that came after it ran. */
+    exitCode?: number | null;
     cause?: unknown;
 }
 /**
@@ -27,13 +34,21 @@ export interface PrizedErrorInit {
  * - `code`: the API's error string, e.g. `paid_balance_required`,
  *   `insufficient_balance`, `sandbox_quota_exceeded`, `not_found`,
  *   `rate_limited`; or one of the SDK's own: `missing_api_key`,
- *   `invalid_api_key`, `invalid_argument`, `network_error`, `timeout`, `aborted`,
+ *   `invalid_api_key`, `invalid_argument`, `edge_unknown` (another
+ *   deployment's API named no command endpoint this SDK sends the key to),
+ *   `network_error`, `timeout`, `aborted`,
  *   `bad_response`, `http_error`, `sandbox_error`, `sandbox_deleted`,
- *   `command_failed`, `command_timeout` (thrown as CommandTimeoutError).
+ *   `command_failed`, `command_timeout` (thrown as CommandTimeoutError),
+ *   `output_read_failed` (thrown as OutputReadError).
  * - `reason`: the finer-grained reason, when there is one (for
  *   `sandbox_quota_exceeded` it names the quota: `sandbox_limit`,
  *   `paused_limit`, `running_vcpu`, `running_memory`, `retained_disk`,
- *   `max_runtime`).
+ *   `max_runtime`; for `output_read_failed`, the code of the failure that
+ *   stopped the read).
+ * - `exitCode`: the command's exit code when the error came after it ran: a
+ *   `fullOutput` command whose output could not be read back
+ *   (`output_read_failed`, or `sandbox_deleted` when the sandbox was deleted
+ *   first). Don't run such a command again blindly. Null otherwise.
  */
 export declare class PrizedError extends Error {
     readonly status: number | null;
@@ -42,6 +57,7 @@ export declare class PrizedError extends Error {
     readonly sandboxId: string | null;
     readonly body: Record<string, unknown> | null;
     readonly retryAfter: number | null;
+    readonly exitCode: number | null;
     constructor(code: string, message?: string | null, init?: PrizedErrorInit);
     toString(): string;
 }
@@ -61,6 +77,30 @@ export declare class CommandTimeoutError extends PrizedError {
     /** What the command printed to stderr before it was killed. */
     get stderr(): string;
 }
+export interface OutputReadErrorInit {
+    /** The failure that stopped the read: a download's error. */
+    cause: PrizedError;
+    exitCode: number;
+    stdoutPath: string;
+    stderrPath: string;
+}
+/**
+ * A `fullOutput` command ran, but its output could not be read back from the
+ * files it was copied to (`code` is `output_read_failed`). The command did
+ * run (`exitCode` is its exit code), so do not run it again blindly; and the
+ * sandbox is not known to be gone (a deleted one throws `sandbox_deleted`
+ * instead). `reason` is the code of the failure that stopped the read (say
+ * `not_found`, `network_error`), and `cause` is that error, with its HTTP
+ * status; `status` is null, as the command's own call succeeded. The output
+ * stays in the sandbox for an hour at `stdoutPath` and `stderrPath`: read it
+ * with files.read(), then remove their directory.
+ */
+export declare class OutputReadError extends PrizedError {
+    readonly exitCode: number;
+    readonly stdoutPath: string;
+    readonly stderrPath: string;
+    constructor(message: string, init: OutputReadErrorInit);
+}
 /** Retry-After as seconds: delta-seconds or an HTTP date. */
 export declare function parseRetryAfter(value: string | null, nowMs: number): number | null;
 /**