@molecule/api-code-sandbox-flyio 1.2.8 → 1.2.10

package/dist/api.d.ts

@@ -125,7 +125,12 @@ export declare class FlyApiClient {
     private readonly baseUrl;
     private readonly timeoutMs;
     private readonly fetchImpl;
-    private readonly sleep;
+    /**
+     * Injectable delay, shared with the provider: a retry that a CALLER drives
+     * (the provider's exec-precondition backoff) waits on the same injected clock
+     * the client's own retries use, so tests collapse every wait in one place.
+     */
+    readonly sleep: (ms: number) => Promise<void>;
     /**
      * Creates a Fly Machines API client.
      * @param options - Token resolver, base URL, and injectable fetch/sleep.

package/dist/api.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAgBH;;;;GAIG;AACH,qBAAa,WAAY,SAAQ,KAAK;IACpC,kFAAkF;IAClF,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,sEAAsE;IACtE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,yCAAyC;IACzC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,oDAAoD;IACpD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IAErB;;;;;;;OAOG;gBAED,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;CAgBhC;AAED,4CAA4C;AAC5C,MAAM,WAAW,iBAAiB;IAChC,sCAAsC;IACtC,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,0DAA0D;IAC1D,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,8EAA8E;IAC9E,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,sFAAsF;IACtF,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,EAAE,CAAA;IACjB;;;;;OAKG;IACH,aAAa,CAAC,EAAE,MAAM,EAAE,CAAA;CACzB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAEzD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAQhF;AAED;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAoBjE;AAED,oDAAoD;AACpD,MAAM,WAAW,mBAAmB;IAClC,gFAAgF;IAChF,KAAK,EAAE,MAAM,MAAM,GAAG,SAAS,CAAA;IAC/B,gCAAgC;IAChC,OAAO,EAAE,MAAM,CAAA;IACf,wCAAwC;IACxC,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,mEAAmE;IACnE,SAAS,CAAC,EAAE,OAAO,KAAK,CAAA;IACxB,6DAA6D;IAC7D,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;CACtC;AAgDD,kFAAkF;AAClF,wBAAgB,qBAAqB,IAAI,IAAI,CAG5C;AAED;;;;GAIG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA0B;IAChD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAQ;IAChC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAQ;IAClC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAc;IACxC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA+B;IAErD;;;OAGG;gBACS,OAAO,EAAE,mBAAmB;IASxC;;;;;;;;;;OAUG;IACG,OAAO,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,iBAAsB,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC;CAiFnF"}
+{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAgBH;;;;GAIG;AACH,qBAAa,WAAY,SAAQ,KAAK;IACpC,kFAAkF;IAClF,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,sEAAsE;IACtE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,yCAAyC;IACzC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,oDAAoD;IACpD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IAErB;;;;;;;OAOG;gBAED,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;CAgBhC;AAED,4CAA4C;AAC5C,MAAM,WAAW,iBAAiB;IAChC,sCAAsC;IACtC,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,0DAA0D;IAC1D,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,8EAA8E;IAC9E,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,sFAAsF;IACtF,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,EAAE,CAAA;IACjB;;;;;OAKG;IACH,aAAa,CAAC,EAAE,MAAM,EAAE,CAAA;CACzB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAEzD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAQhF;AAED;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAoBjE;AAED,oDAAoD;AACpD,MAAM,WAAW,mBAAmB;IAClC,gFAAgF;IAChF,KAAK,EAAE,MAAM,MAAM,GAAG,SAAS,CAAA;IAC/B,gCAAgC;IAChC,OAAO,EAAE,MAAM,CAAA;IACf,wCAAwC;IACxC,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,mEAAmE;IACnE,SAAS,CAAC,EAAE,OAAO,KAAK,CAAA;IACxB,6DAA6D;IAC7D,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;CACtC;AAgDD,kFAAkF;AAClF,wBAAgB,qBAAqB,IAAI,IAAI,CAG5C;AAED;;;;GAIG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA0B;IAChD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAQ;IAChC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAQ;IAClC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAc;IACxC;;;;OAIG;IACH,QAAQ,CAAC,KAAK,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IAE7C;;;OAGG;gBACS,OAAO,EAAE,mBAAmB;IASxC;;;;;;;;;;OAUG;IACG,OAAO,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,iBAAsB,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC;CAiFnF"}

package/dist/api.js

@@ -176,6 +176,11 @@ export class FlyApiClient {
     baseUrl;
     timeoutMs;
     fetchImpl;
+    /**
+     * Injectable delay, shared with the provider: a retry that a CALLER drives
+     * (the provider's exec-precondition backoff) waits on the same injected clock
+     * the client's own retries use, so tests collapse every wait in one place.
+     */
     sleep;
     /**
      * Creates a Fly Machines API client.

package/dist/index.d.ts

@@ -315,12 +315,26 @@
  * short-term burst limit up to 3 req/s, per action", scoped "per-action,
  * per-machine … That might be Machine ID or App ID, depending on the type of
  * request", with Get Machine at 5 req/s and app deletions capped at 100 per
- * minute. `429` and `5xx` are retried with `Retry-After`-aware backoff; other
- * `4xx` responses are real answers and are never retried. The consequence to
- * plan for is that EVERY file operation is an exec API call, so one sandbox's
- * reads and writes serialize at roughly one per second and a multi-megabyte
- * `writeFile` (chunked at ~45 KB decoded) takes tens of seconds. An agent that
- * edits files in a tight loop will feel this; batch where you can.
+ * minute. `429` and `5xx` are retried with `Retry-After`-aware backoff, plus the
+ * `404` an app-propagation lag answers the Machine create with; every other
+ * `4xx` is a real answer and is never retried. The consequence to plan for is
+ * that EVERY file operation is an exec API call, so one sandbox's reads and
+ * writes serialize at roughly one per second and a multi-megabyte `writeFile`
+ * (chunked at ~45 KB decoded) takes tens of seconds. An agent that edits files
+ * in a tight loop will feel this; batch where you can.
+ *
+ * **A refused exec that dropped the connection is retried; a refused exec that
+ * names a Machine state is not.** Fly answers `412 failed_precondition: exec
+ * request failed: EOF` when the request reached a `started` Machine's exec agent
+ * and the connection died before the command ran — a Machine seconds past boot,
+ * or Fly's own exec burst. `exec` retries that one at the transport (up to four
+ * attempts, ~11 s of backoff, each preceded by a Machine-state read and a wait
+ * for `started` when it has not got there), because every caller's alternative
+ * is to throw away a whole boot or deploy and start over. The OTHER `412`,
+ * `failed_precondition: machine not running`, is a real state and is not
+ * repeated: `start()`/`wake()` wait it out before the first exec. A 412 that is
+ * not retried comes back with the Machine's current state appended to its
+ * message, and a 412 the retries could not clear carries the state it ended in.
  *
  * **`create()` launches the Machine, and `start()`/`wake()` WAIT for it.** Unlike
  * Docker's create-then-start, the Machines API starts a Machine as part of

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqVG;AAEH,cAAc,UAAU,CAAA;AACxB,cAAc,oBAAoB,CAAA;AAClC,cAAc,aAAa,CAAA;AAC3B,cAAc,WAAW,CAAA;AACzB,cAAc,cAAc,CAAA;AAC5B,cAAc,UAAU,CAAA;AACxB,cAAc,eAAe,CAAA;AAC7B,cAAc,cAAc,CAAA;AAC5B,cAAc,gBAAgB,CAAA;AAC9B,cAAc,YAAY,CAAA;AAC1B,cAAc,gBAAgB,CAAA;AAE9B,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAA;AAMjE;;GAEG;AACH,eAAO,MAAM,QAAQ,EAAE,eAUrB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmWG;AAEH,cAAc,UAAU,CAAA;AACxB,cAAc,oBAAoB,CAAA;AAClC,cAAc,aAAa,CAAA;AAC3B,cAAc,WAAW,CAAA;AACzB,cAAc,cAAc,CAAA;AAC5B,cAAc,UAAU,CAAA;AACxB,cAAc,eAAe,CAAA;AAC7B,cAAc,cAAc,CAAA;AAC5B,cAAc,gBAAgB,CAAA;AAC9B,cAAc,YAAY,CAAA;AAC1B,cAAc,gBAAgB,CAAA;AAE9B,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAA;AAMjE;;GAEG;AACH,eAAO,MAAM,QAAQ,EAAE,eAUrB,CAAA"}

package/dist/index.js

@@ -315,12 +315,26 @@
  * short-term burst limit up to 3 req/s, per action", scoped "per-action,
  * per-machine … That might be Machine ID or App ID, depending on the type of
  * request", with Get Machine at 5 req/s and app deletions capped at 100 per
- * minute. `429` and `5xx` are retried with `Retry-After`-aware backoff; other
- * `4xx` responses are real answers and are never retried. The consequence to
- * plan for is that EVERY file operation is an exec API call, so one sandbox's
- * reads and writes serialize at roughly one per second and a multi-megabyte
- * `writeFile` (chunked at ~45 KB decoded) takes tens of seconds. An agent that
- * edits files in a tight loop will feel this; batch where you can.
+ * minute. `429` and `5xx` are retried with `Retry-After`-aware backoff, plus the
+ * `404` an app-propagation lag answers the Machine create with; every other
+ * `4xx` is a real answer and is never retried. The consequence to plan for is
+ * that EVERY file operation is an exec API call, so one sandbox's reads and
+ * writes serialize at roughly one per second and a multi-megabyte `writeFile`
+ * (chunked at ~45 KB decoded) takes tens of seconds. An agent that edits files
+ * in a tight loop will feel this; batch where you can.
+ *
+ * **A refused exec that dropped the connection is retried; a refused exec that
+ * names a Machine state is not.** Fly answers `412 failed_precondition: exec
+ * request failed: EOF` when the request reached a `started` Machine's exec agent
+ * and the connection died before the command ran — a Machine seconds past boot,
+ * or Fly's own exec burst. `exec` retries that one at the transport (up to four
+ * attempts, ~11 s of backoff, each preceded by a Machine-state read and a wait
+ * for `started` when it has not got there), because every caller's alternative
+ * is to throw away a whole boot or deploy and start over. The OTHER `412`,
+ * `failed_precondition: machine not running`, is a real state and is not
+ * repeated: `start()`/`wake()` wait it out before the first exec. A 412 that is
+ * not retried comes back with the Machine's current state appended to its
+ * message, and a 412 the retries could not clear carries the state it ended in.
  *
  * **`create()` launches the Machine, and `start()`/`wake()` WAIT for it.** Unlike
  * Docker's create-then-start, the Machines API starts a Machine as part of

package/dist/provider.d.ts

@@ -10,6 +10,50 @@ import type { SandboxProvider } from '@molecule/api-code-sandbox';
 import { FlyApiClient } from './api.js';
 import { type ObjectStore } from './storage.js';
 import type { FlyioConfig } from './types.js';
+/**
+ * Whether a failed exec is Fly's TRANSIENT precondition — one a repeat (after a
+ * short wait) can clear, rather than a Machine state the exec has to wait out.
+ *
+ * Fly answers the exec endpoint with 412 in two different situations, and only
+ * the BODY and the Machine's own reported state separate them:
+ *
+ * 1. `failed_precondition: exec request failed: EOF` — the request reached the
+ *    Machine's exec agent and the connection dropped before the command ran.
+ *    Always transient: the Machine is `started` and its agent recovers in
+ *    seconds.
+ * 2. `failed_precondition: machine not running` — transient ONLY while Fly's
+ *    own Machines API reports the Machine `started`, `starting` or `replacing`
+ *    (`machineState`). The exec endpoint lags the state Fly reports: a Machine
+ *    whose config or image was just updated, or that is seconds past boot,
+ *    reads `started` in `GET /machines/{id}` while its exec endpoint still
+ *    refuses requests. Against a Machine Fly reports `stopped`/`suspended`/
+ *    `destroyed` the same body is the REAL precondition — the Machine is not
+ *    running, and {@link FlyioSandboxProvider.startMachine} is what answers it;
+ *    repeating the exec would only burn the caller's budget.
+ *
+ * @param error - The failure an exec attempt raised.
+ * @param machineState - The state `GET /machines/{id}` reports for the Machine,
+ *   or `null`/`undefined` when it could not be read (which classifies case 2 as
+ *   NOT transient — an unknown state is never assumed recoverable).
+ * @returns `true` when repeating the exec is the right recovery.
+ */
+export declare function isTransientExecPrecondition(error: unknown, machineState?: string | null): boolean;
+/**
+ * Whether a state Fly reports for a Machine means the Machine is up, or on its
+ * way up — the states in which an exec that was refused for `machine not
+ * running` is the exec endpoint lagging the state, not the truth.
+ *
+ * A deliberate allow-list rather than "anything but stopped/suspended": the
+ * three states here are the ones a refused exec was observed to recover from,
+ * and every other state — `stopped`, `suspended`, `destroyed`, `failed`,
+ * `created`, unreadable — keeps today's immediate throw. Widening it without
+ * that evidence would turn a real precondition into a retry budget spent
+ * against a Machine that is not coming up.
+ *
+ * @param state - The Machine state from `GET /machines/{id}`, if readable.
+ * @returns `true` when waiting and repeating the exec can clear the refusal.
+ */
+export declare function isMachineWarmingUp(state: string | null | undefined): boolean;
 /**
  * Creates a Fly.io Machines sandbox provider.
  * @param config - Optional Fly configuration: API token/URL, org slug, app

package/dist/provider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAMH,OAAO,KAAK,EAWV,eAAe,EAGhB,MAAM,4BAA4B,CAAA;AAGnC,OAAO,EAAE,YAAY,EAAgC,MAAM,UAAU,CAAA;AAwBrE,OAAO,EAAmD,KAAK,WAAW,EAAE,MAAM,cAAc,CAAA;AAEhG,OAAO,KAAK,EAIV,WAAW,EAUZ,MAAM,YAAY,CAAA;AAsgFnB;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAC5B,MAAM,CAAC,EAAE,WAAW,EACpB,MAAM,CAAC,EAAE,YAAY,EACrB,KAAK,CAAC,EAAE,WAAW,GAAG,IAAI,GACzB,eAAe,CAEjB"}
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAMH,OAAO,KAAK,EAWV,eAAe,EAGhB,MAAM,4BAA4B,CAAA;AAGnC,OAAO,EAAE,YAAY,EAAgC,MAAM,UAAU,CAAA;AAwBrE,OAAO,EAAmD,KAAK,WAAW,EAAE,MAAM,cAAc,CAAA;AAEhG,OAAO,KAAK,EAIV,WAAW,EAUZ,MAAM,YAAY,CAAA;AAkBnB;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,OAAO,EAAE,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAIjG;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,CAE5E;AAksFD;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAC5B,MAAM,CAAC,EAAE,WAAW,EACpB,MAAM,CAAC,EAAE,YAAY,EACrB,KAAK,CAAC,EAAE,WAAW,GAAG,IAAI,GACzB,eAAe,CAEjB"}

package/dist/provider.js

@@ -31,6 +31,58 @@ function describeDestroyFailure(step, id, error) {
     const reason = error instanceof Error ? error.message : String(error);
     return `Fly sandbox destroy failed at the ${step} for ${id} (${status}): ${reason}`;
 }
+/**
+ * Whether a failed exec is Fly's TRANSIENT precondition — one a repeat (after a
+ * short wait) can clear, rather than a Machine state the exec has to wait out.
+ *
+ * Fly answers the exec endpoint with 412 in two different situations, and only
+ * the BODY and the Machine's own reported state separate them:
+ *
+ * 1. `failed_precondition: exec request failed: EOF` — the request reached the
+ *    Machine's exec agent and the connection dropped before the command ran.
+ *    Always transient: the Machine is `started` and its agent recovers in
+ *    seconds.
+ * 2. `failed_precondition: machine not running` — transient ONLY while Fly's
+ *    own Machines API reports the Machine `started`, `starting` or `replacing`
+ *    (`machineState`). The exec endpoint lags the state Fly reports: a Machine
+ *    whose config or image was just updated, or that is seconds past boot,
+ *    reads `started` in `GET /machines/{id}` while its exec endpoint still
+ *    refuses requests. Against a Machine Fly reports `stopped`/`suspended`/
+ *    `destroyed` the same body is the REAL precondition — the Machine is not
+ *    running, and {@link FlyioSandboxProvider.startMachine} is what answers it;
+ *    repeating the exec would only burn the caller's budget.
+ *
+ * @param error - The failure an exec attempt raised.
+ * @param machineState - The state `GET /machines/{id}` reports for the Machine,
+ *   or `null`/`undefined` when it could not be read (which classifies case 2 as
+ *   NOT transient — an unknown state is never assumed recoverable).
+ * @returns `true` when repeating the exec is the right recovery.
+ */
+export function isTransientExecPrecondition(error, machineState) {
+    if (!(error instanceof FlyApiError) || error.status !== 412)
+        return false;
+    if (EXEC_BODY_DROPPED_CONNECTION.test(error.body))
+        return true;
+    return EXEC_BODY_MACHINE_NOT_RUNNING.test(error.body) && isMachineWarmingUp(machineState);
+}
+/**
+ * Whether a state Fly reports for a Machine means the Machine is up, or on its
+ * way up — the states in which an exec that was refused for `machine not
+ * running` is the exec endpoint lagging the state, not the truth.
+ *
+ * A deliberate allow-list rather than "anything but stopped/suspended": the
+ * three states here are the ones a refused exec was observed to recover from,
+ * and every other state — `stopped`, `suspended`, `destroyed`, `failed`,
+ * `created`, unreadable — keeps today's immediate throw. Widening it without
+ * that evidence would turn a real precondition into a retry budget spent
+ * against a Machine that is not coming up.
+ *
+ * @param state - The Machine state from `GET /machines/{id}`, if readable.
+ * @returns `true` when waiting and repeating the exec can clear the refusal.
+ */
+export function isMachineWarmingUp(state) {
+    return state === 'started' || state === 'starting' || state === 'replacing';
+}
 /**
  * Default sandbox image. Fly pulls images itself, so this MUST be a reference
  * Fly can resolve — a tag in the org's `registry.fly.io` repository or a public
@@ -158,6 +210,54 @@ const MACHINE_CREATE_ATTEMPTS = 6;
  * default retryable set; neither retry can double-create.
  */
 const MACHINE_CREATE_RETRY_STATUSES = [404, 412];
+/**
+ * What Fly answers when it reached the exec endpoint but the connection to the
+ * Machine's exec agent died before the command ran: `412 {"error":
+ * "failed_precondition: exec request failed: EOF"}`. The Machine is `started`;
+ * the agent inside it dropped the request (a Machine seconds past boot, or
+ * Fly's own exec burst).
+ */
+const EXEC_BODY_DROPPED_CONNECTION = /exec request failed/i;
+/**
+ * The OTHER 412 the exec endpoint answers — `{"error":"failed_precondition:
+ * machine not running"}`. Whether that is the real precondition or the exec
+ * endpoint lagging a Machine that is up cannot be read off the body, so it is
+ * settled by the state Fly reports for the Machine at that moment
+ * ({@link isMachineWarmingUp}).
+ */
+const EXEC_BODY_MACHINE_NOT_RUNNING = /machine not running/i;
+/**
+ * Attempts for one exec when Fly answers a transient 412 — either body of
+ * {@link isTransientExecPrecondition}. Four attempts over the three backoffs
+ * below is under 12 s of waiting, against the ~75 s each fresh production
+ * deploy costs when this is left to a caller: X1 run flash-m85 (2026-10-16)
+ * lost three consecutive deploys, and the run, to the dropped connection;
+ * flash-m94 (2026-10-16) lost 65 s and a whole redeploy to the same budget not
+ * covering `machine not running` on a Machine Fly reported `started`.
+ */
+const EXEC_PRECONDITION_ATTEMPTS = 4;
+/**
+ * Backoff before each exec retry (ms), indexed by the failed attempt number.
+ * Short on purpose: the Machine is up, and the agent recovers in seconds —
+ * nothing here is waiting on a boot.
+ */
+const EXEC_PRECONDITION_BACKOFF_MS = [1_000, 3_000, 7_000];
+/**
+ * Wall-clock ceiling on {@link EXEC_PRECONDITION_ATTEMPTS}, so a Machine whose
+ * exec agent keeps dropping requests cannot hold a caller for the whole budget
+ * while the rest of the backoff ladder runs. Measured from the first attempt.
+ */
+const EXEC_PRECONDITION_BUDGET_MS = 60_000;
+/**
+ * The backoff before an exec retry, clamped to the last rung so an attempt
+ * count raised past the ladder's length cannot read off the end of it.
+ * @param attempt - The 1-based number of the attempt that just failed.
+ * @returns The delay in milliseconds.
+ */
+function execPreconditionBackoffMs(attempt) {
+    const last = EXEC_PRECONDITION_BACKOFF_MS.length - 1;
+    return EXEC_PRECONDITION_BACKOFF_MS[Math.min(Math.max(attempt - 1, 0), last)];
+}
 /**
  * Base64 chunk size for {@link Sandbox.importFiles}'s temp-file write. Bounded by
  * the same Fly exec payload limit as `WRITE_CHUNK_BASE64` (~15 KB, silently
@@ -1772,28 +1872,166 @@ class FlyioSandboxProvider {
     // ---------------------------------------------------------------------------
     // Sandbox
     // ---------------------------------------------------------------------------
+    /**
+     * Reads the state Fly reports for a Machine, or `null` when it cannot be read.
+     *
+     * Best-effort on purpose: this runs both on the failure path and just before a
+     * retry, and a failed diagnostic read must not replace the failure it is
+     * describing. `null` is meaningful — it never classifies a refusal as
+     * recoverable (see {@link isTransientExecPrecondition}).
+     *
+     * @param app - The Fly app name.
+     * @param machineId - The Fly Machine id.
+     * @returns The Machine's state, or `null` when the read failed or 404'd.
+     */
+    async readMachineState(app, machineId) {
+        try {
+            const machine = await this.client.request(`/apps/${app}/machines/${machineId}`, {
+                nullOn: [404],
+            });
+            return machine?.state ?? null;
+        }
+        catch (error) {
+            logger.debug('Could not read the Machine state while an exec was refused', {
+                app,
+                machineId,
+                error,
+            });
+            return null;
+        }
+    }
     /**
      * Issues one Fly exec call against a Machine.
+     *
+     * A transient 412 (see {@link isTransientExecPrecondition}) is retried here, at
+     * the transport, because everywhere it surfaces — a boot, the production
+     * artifact copy, the boot script, a health probe — the caller's alternative is
+     * to throw the whole operation away and start over, which costs tens of seconds
+     * or minutes. Before the retry the Machine's state is re-read (and waited on
+     * when it is not yet `started`), so a Machine that really is still coming up is
+     * not hammered.
+     *
+     * A 412 that is NOT that condition is never retried, and its message carries
+     * the Machine's current state — the caller is told which state the exec was
+     * refused in rather than a bare `failed_precondition`.
+     *
      * @param app - The Fly app name.
      * @param machineId - The Fly Machine id.
      * @returns A transport callback for {@link execCommand}.
      */
     rawExec(app, machineId) {
         return async (command, timeoutSeconds) => {
-            const response = await this.client.request(`/apps/${app}/machines/${machineId}/exec`, {
-                method: 'POST',
-                body: { command, timeout: timeoutSeconds },
-                // The API's own timeout bounds the command; allow the HTTP request a
-                // little longer so the transport never fires first.
-                timeoutMs: (timeoutSeconds + 15) * 1000,
-                // A 404 on a Machine we created and are actively driving (e.g. the
-                // exec burst importFiles issues) is Fly API inconsistency under load,
-                // not a real absence — retry it alongside the default 429/5xx.
-                retryStatuses: [404],
-            });
-            return response ?? {};
+            const deadline = Date.now() + EXEC_PRECONDITION_BUDGET_MS;
+            for (let attempt = 1;; attempt++) {
+                try {
+                    const response = await this.client.request(`/apps/${app}/machines/${machineId}/exec`, {
+                        method: 'POST',
+                        body: { command, timeout: timeoutSeconds },
+                        // The API's own timeout bounds the command; allow the HTTP request a
+                        // little longer so the transport never fires first.
+                        timeoutMs: (timeoutSeconds + 15) * 1000,
+                        // A 404 on a Machine we created and are actively driving (e.g. the
+                        // exec burst importFiles issues) is Fly API inconsistency under load,
+                        // not a real absence — retry it alongside the default 429/5xx.
+                        retryStatuses: [404],
+                    });
+                    return response ?? {};
+                }
+                catch (error) {
+                    // Which 412 this is cannot be read off the body alone: `machine not
+                    // running` is transient against a Machine Fly reports `started` and the
+                    // real precondition against one it reports `stopped`. So the state is
+                    // read here, once, and the same read decides the classification, the
+                    // wait below, and the state the error finally names.
+                    const state = error instanceof FlyApiError && error.status === 412
+                        ? await this.readMachineState(app, machineId)
+                        : null;
+                    if (!isTransientExecPrecondition(error, state)) {
+                        throw await this.withMachineState(error, app, machineId, state);
+                    }
+                    if (attempt >= EXEC_PRECONDITION_ATTEMPTS || Date.now() >= deadline) {
+                        logger.warn('Fly kept refusing the exec with a transient precondition', {
+                            app,
+                            machineId,
+                            attempt,
+                            state: state ?? 'unreadable',
+                        });
+                        throw await this.withMachineState(error, app, machineId, state);
+                    }
+                    logger.warn('Fly refused the exec with a transient precondition; retrying', {
+                        app,
+                        machineId,
+                        attempt,
+                        attempts: EXEC_PRECONDITION_ATTEMPTS,
+                        state: state ?? 'unreadable',
+                    });
+                    // The Machine is up (that is what makes this 412 the transient one), but
+                    // re-read it anyway: `stop`/`suspend` can land between attempts, and
+                    // retrying an exec against a Machine that is not running would repeat a
+                    // 412 that waiting — not repeating — is what answers.
+                    await this.waitForExecReady(app, machineId, state);
+                    await this.client.sleep(execPreconditionBackoffMs(attempt));
+                }
+            }
         };
     }
+    /**
+     * Confirms the Machine is in a state an exec can run in, waiting for `started`
+     * when it is still on its way up.
+     *
+     * A wait that does not reach `started` is logged and the exec is retried
+     * anyway: the retry is the recovery this path exists for, and turning a
+     * recoverable refusal into a start-timeout error would hide the condition the
+     * caller's error message is supposed to name.
+     *
+     * @param app - The Fly app name.
+     * @param machineId - The Fly Machine id.
+     * @param state - The state already read for this Machine, when the caller read
+     *   one (the exec retry does); read again when omitted.
+     */
+    async waitForExecReady(app, machineId, state) {
+        const machineState = state === undefined ? await this.readMachineState(app, machineId) : state;
+        if (machineState === 'started')
+            return;
+        try {
+            await this.waitForStarted(app, machineId);
+        }
+        catch (error) {
+            logger.warn('The Machine did not report started after a refused exec; retrying the exec', {
+                app,
+                machineId,
+                state: machineState ?? 'unknown',
+                error,
+            });
+        }
+    }
+    /**
+     * Names the Machine's state on an exec 412, so the caller is told WHICH state
+     * the exec was refused in. Fly's own body says only `failed_precondition`.
+     *
+     * A state that cannot be read is reported as such rather than guessed, and any
+     * non-412 error (or an error that already carries the state) is returned
+     * untouched — this runs on the failure path, where a diagnostic must never
+     * replace the failure it is describing.
+     *
+     * @param error - The failure to annotate.
+     * @param app - The Fly app name.
+     * @param machineId - The Fly Machine id.
+     * @param knownState - The state already read for this Machine, when the caller
+     *   read one (the exec retry does); read again when omitted.
+     * @returns The original error, or a 412 carrying the Machine's state.
+     */
+    async withMachineState(error, app, machineId, knownState) {
+        if (!(error instanceof Error))
+            return new Error(String(error));
+        if (!(error instanceof FlyApiError) || error.status !== 412)
+            return error;
+        if (/machine state:/i.test(error.message))
+            return error;
+        const read = knownState === undefined ? await this.readMachineState(app, machineId) : knownState;
+        const state = read ?? 'unreadable';
+        return new FlyApiError(error.method, error.path, error.status, `${error.body} (machine ${machineId} state: ${state})`, { cause: error });
+    }
     /**
      * Starts (or resumes) a Machine, tolerating the case where it is already up.
      *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@molecule/api-code-sandbox-flyio",
-  "version": "1.2.8",
+  "version": "1.2.10",
   "description": "Fly.io Machines (Firecracker microVM) code sandbox provider",
   "type": "module",
   "main": "dist/index.js",