@molecule/api-code-sandbox-flyio 1.2.7 → 1.2.9

package/README.md

@@ -3,7 +3,7 @@ AUTO-GENERATED — DO NOT EDIT THIS FILE.
 Generated by `mlcl sync-docs` from the package's src/index.ts JSDoc + mlcl/registry.json.
 Edits here are overwritten on the next commit (molecule's pre-commit hook regenerates).
 To change this document, edit the module-level JSDoc in src/index.ts.
-Generated: 2026-10-08T03:25:09.946Z
+Generated: 2026-10-16T16:08:45.819Z
 -->
 
 # @molecule/api-code-sandbox-flyio
@@ -82,6 +82,67 @@ npm install @molecule/api-code-sandbox-flyio @aws-sdk/client-s3 @aws-sdk/s3-requ
 
 ### Interfaces
 
+#### `FlyRequestOptions`
+
+Options for a single Fly API request.
+
+```typescript
+interface FlyRequestOptions {
+  /** HTTP method. Defaults to `GET`. */
+  method?: string
+  /** JSON request body. Omitted entirely when undefined. */
+  body?: unknown
+  /** Per-request timeout in ms. Defaults to the client's configured timeout. */
+  timeoutMs?: number
+  /** Max attempts for a retryable failure. Defaults to 4. Pass 1 to disable retries. */
+  attempts?: number
+  /**
+   * Treat these HTTP statuses as a successful `null` result instead of throwing.
+   * Used for idempotent deletes and existence checks (`[404]`).
+   */
+  nullOn?: number[]
+  /**
+   * Extra HTTP statuses to treat as transient (retry) beyond the default
+   * `429`/`5xx`. The exec endpoint passes `[404]`: a machine-not-found for a
+   * Machine we just created and are actively driving is Fly API inconsistency
+   * under exec-burst load, not a real absence, so it is worth repeating.
+   */
+  retryStatuses?: number[]
+}
+```
+
+#### `FlyApiClientOptions`
+
+Constructor options for {@link FlyApiClient}.
+
+```typescript
+interface FlyApiClientOptions {
+  /** Bearer token. Resolved lazily so env/secrets can land after construction. */
+  token: () => string | undefined
+  /** Base URL including `/v1`. */
+  baseUrl: string
+  /** Default per-request timeout (ms). */
+  timeoutMs?: number
+  /** Injectable fetch, for tests. Defaults to the global `fetch`. */
+  fetchImpl?: typeof fetch
+  /** Injectable sleep, for tests. Defaults to `setTimeout`. */
+  sleep?: (ms: number) => Promise<void>
+}
+```
+
+#### `EgressProbeTarget`
+
+One literal host:port the probe attempts a raw TCP connection to.
+
+```typescript
+interface EgressProbeTarget {
+  /** A literal IPv4 or IPv6 address. Never a hostname — see {@link parseEgressProbeTargets}. */
+  host: string
+  /** TCP port. */
+  port: number
+}
+```
+
 #### `EgressProbeContext`
 
 Context {@link verdictForProbeExit} renders its operator-facing messages from.
@@ -115,72 +176,106 @@ interface EgressProbeContext {
 }
 ```
 
-#### `EgressProbeTarget`
+#### `StoredObject`
 
-One literal host:port the probe attempts a raw TCP connection to.
+One object as this bond needs to see it.
 
 ```typescript
-interface EgressProbeTarget {
-  /** A literal IPv4 or IPv6 address. Never a hostname — see {@link parseEgressProbeTargets}. */
-  host: string
-  /** TCP port. */
-  port: number
+interface StoredObject {
+  /** Full key, including the configured prefix. */
+  key: string
+  /** Size in bytes. */
+  size: number
+  /** Last-modified timestamp, ISO 8601, or `null` when the store did not report one. */
+  lastModified: string | null
 }
 ```
 
-#### `FlyApiClientOptions`
-
-Constructor options for {@link FlyApiClient}.
-
-```typescript
-interface FlyApiClientOptions {
-  /** Bearer token. Resolved lazily so env/secrets can land after construction. */
-  token: () => string | undefined
-  /** Base URL including `/v1`. */
-  baseUrl: string
-  /** Default per-request timeout (ms). */
-  timeoutMs?: number
-  /** Injectable fetch, for tests. Defaults to the global `fetch`. */
-  fetchImpl?: typeof fetch
-  /** Injectable sleep, for tests. Defaults to `setTimeout`. */
-  sleep?: (ms: number) => Promise<void>
-}
-```
+#### `ObjectStore`
 
-#### `FlyApp`
+The object-store operations the template capability needs.
 
-An app as returned by `GET /v1/apps?org_slug=…` (the fields this provider reads).
+Declared as an interface so `templates.ts` stays transport-free and its tests
+can drive a fake store, the same way `exec.ts` takes an injected `RawExec`.
 
 ```typescript
-interface FlyApp {
-  id?: string
-  name: string
-  machine_count?: number
+interface ObjectStore {
+  /** Human-readable identification of the store, for error messages. */
+  readonly describe: string
+  /** Bucket holding the templates. Used to render the opaque `SandboxTemplate.ref`. */
+  readonly bucket: string
+  /** Key prefix every template object lives under, with no trailing slash. */
+  readonly prefix: string
+  /**
+   * Every object under a prefix, following pagination to the end.
+   * THROWS on failure — a caller that deletes must never read a failed query as
+   * "nothing is there".
+   */
+  list(prefix: string): Promise<StoredObject[]>
+  /** One object's metadata, or `null` when it does not exist. Throws on any other failure. */
+  head(key: string): Promise<StoredObject | null>
+  /** An object's body as text, or `null` when it does not exist. Throws on any other failure. */
+  getText(key: string): Promise<string | null>
+  /** Write a small text object. */
+  putText(key: string, body: string, contentType: string): Promise<void>
+  /** Delete objects. Deleting a key that is not there is a success. */
+  remove(keys: string[]): Promise<void>
+  /** A presigned URL a sandbox can `PUT` an archive to. */
+  presignPut(key: string, expiresInSeconds: number): Promise<string>
+  /** A presigned URL a sandbox can `GET` an archive from. */
+  presignGet(key: string, expiresInSeconds: number): Promise<string>
 }
 ```
 
-#### `FlyAppList`
+#### `TemplateManifest`
 
-Response body of `GET /v1/apps?org_slug=…`.
+The control-plane-written record of a template. Its existence defines the template's existence.
 
 ```typescript
-interface FlyAppList {
-  /** Total apps in the org, which the returned page may not cover. */
-  total_apps?: number
-  apps?: FlyApp[]
+interface TemplateManifest {
+  /** Schema version of this record. */
+  schema: number
+  /** The caller's template id. */
+  id: string
+  /**
+   * Absolute paths captured, exactly as the caller named them.
+   *
+   * This is the security-relevant field: on restore these become `tar`'s member
+   * selectors, so the extraction surface is control-plane policy rather than
+   * anything the captured sandbox could influence.
+   */
+  capturePaths: string[]
+  /** When the capture completed, ISO 8601. */
+  createdAt: string
+  /** Archive size in bytes as observed in the store at capture time. */
+  sizeBytes: number
+  /** Free-form label recorded at capture time. */
+  label?: string
 }
 ```
 
-#### `FlyExecResponse`
+#### `TemplateContext`
 
-Response body of `POST /v1/apps/{app}/machines/{id}/exec` (`flydv1.ExecResponse`).
+What the template capability needs from the provider.
 
 ```typescript
-interface FlyExecResponse {
-  stdout?: string
-  stderr?: string
-  exit_code?: number
-  exit_signal?: number
+interface TemplateContext {
+  /** The configured object store, or `null` when the operator has not configured one. */
+  store: ObjectStore | null
+  /** Runs a shell command inside a Machine and returns its result. */
+  exec(app: string, machineId: string, command: string, timeoutMs: number): Promise<ExecResult>
+  /** Blocks until a Machine is running, so it can be exec'd into. */
+  ensureStarted(app: string, machineId: string): Promise<void>
+  /** Splits a composite sandbox id into its app and Machine id. */
+  parseSandboxId(id: string): { app: string; machineId: string }
+  /** Lifetime of a presigned capture/restore URL, in seconds. */
+  presignExpirySeconds: number
+  /** Wall-clock budget for a capture or restore transfer, in ms. */
+  transferTimeoutMs: number
+  /** Largest archive this provider will store, in bytes. */
+  maxArchiveBytes: number
+  warn?: (message: string, meta?: Record<string, unknown>) => void
+  debug?: (message: string, meta?: Record<string, unknown>) => void
 }
 ```
 
@@ -351,223 +446,131 @@ interface FlyioConfig {
    * anything publicly — see the `flycast.ts` module description.
    *
    * The declared PORT is load-bearing twice: it is unioned into
-   * {@link FlyioConfig.egressAllowedPorts} so the network policy cannot drop the
-   * connection, and every `.flycast` URL in a sandbox's environment is checked
-   * against it, so a `DATABASE_URL` naming an app nobody declared FAILS the boot
-   * instead of timing out inside the user's project.
-   *
-   * Two things this cannot do for you: the target app needs an `[http_service]`
-   * or `[services]` section (Flycast routes through Fly Proxy), and it must bind
-   * `0.0.0.0` rather than `fly-local-6pn`
-   * (https://fly.io/docs/networking/flycast/).
-   *
-   * Ignored when `appPerProject` is `false` — a shared app sits on the org's
-   * default 6PN, where `<app>.internal` already resolves.
-   */
-  privateServices?: FlyPrivateService[]
-  /**
-   * `type` sent to `POST /apps/{app}/ip_assignments` when allocating a Flycast
-   * address. Defaults to `private_v6`, the value flyctl passes for
-   * `fly ips allocate-v6 --private`. The field has no enum in Fly's OpenAPI
-   * specification, so treat the literal as UNVERIFIED and use this to override
-   * it if Fly renames it.
-   */
-  privateIpAssignmentType?: string
-  /**
-   * Literal `ip:port` targets `verifyEgress()` attempts raw TCP connections to.
-   * IPv6 literals must be bracketed. Falls back to `SANDBOX_EGRESS_PROBE_TARGETS`
-   * (the same variable the Docker bond reads), then to one IPv4 and one IPv6
-   * anycast resolver on 443.
-   */
-  egressProbeTargets?: string[]
-  /** Per-connection timeout for the egress probe, in ms. Falls back to `SANDBOX_EGRESS_PROBE_TIMEOUT_MS`, then 3000. */
-  egressProbeTimeoutMs?: number
-  /**
-   * Image the throwaway `verifyEgress()` probe Machine runs. Must contain `node`
-   * and `sleep`. Defaults to the configured sandbox base image, so the probe
-   * observes egress from the same image real sandboxes run.
-   */
-  egressProbeImage?: string
-  /**
-   * Bucket holding sandbox templates. Falls back to `SANDBOX_TEMPLATE_BUCKET`,
-   * then `BUCKET_NAME` (which `fly storage create` sets).
-   *
-   * Templates are the warm-start capability: Fly cannot commit a running Machine
-   * to an image, so a template is a tar archive in S3-compatible object storage.
-   * Without a bucket (and both credentials) the template methods throw an
-   * actionable error naming these settings, and `SandboxConfig.templateId` fails
-   * rather than silently booting the base image.
-   */
-  templateBucket?: string
-  /**
-   * S3 endpoint for {@link FlyioConfig.templateBucket}, e.g. Tigris's
-   * `https://t3.storage.dev`. Falls back to `SANDBOX_TEMPLATE_ENDPOINT`, then
-   * `AWS_ENDPOINT_URL_S3`. Omit for AWS S3 itself.
-   */
-  templateEndpoint?: string
-  /**
-   * Region used to sign template-store requests. Falls back to
-   * `SANDBOX_TEMPLATE_REGION`, then `AWS_REGION`, then `auto` — which Tigris and
-   * most S3-compatible stores accept, and which the AWS SDK still requires in
-   * order to build a signature.
-   */
-  templateRegion?: string
-  /** Access key for the template store. Falls back to `SANDBOX_TEMPLATE_ACCESS_KEY_ID`, then `AWS_ACCESS_KEY_ID`. */
-  templateAccessKeyId?: string
-  /** Secret key for the template store. Falls back to `SANDBOX_TEMPLATE_SECRET_ACCESS_KEY`, then `AWS_SECRET_ACCESS_KEY`. */
-  templateSecretAccessKey?: string
-  /** Session token for temporary template-store credentials. Falls back to `SANDBOX_TEMPLATE_SESSION_TOKEN`, then `AWS_SESSION_TOKEN`. */
-  templateSessionToken?: string
-  /**
-   * Key prefix every template object lives under. Falls back to
-   * `SANDBOX_TEMPLATE_PREFIX`, then `molecule-sandbox-templates`. Give the
-   * templates their own prefix (or their own bucket): `removeTemplate` deletes
-   * every key under a template's prefix.
-   */
-  templatePrefix?: string
-  /**
-   * Address the template bucket path-style (`https://endpoint/bucket/key`)
-   * instead of virtual-host style. Falls back to
-   * `SANDBOX_TEMPLATE_FORCE_PATH_STYLE=true`. Needed by stores that do not serve
-   * `<bucket>.<endpoint>`; Tigris and AWS S3 do not need it.
-   */
-  templateForcePathStyle?: boolean
+// … truncated — the full declaration is in node_modules/@molecule/api-code-sandbox-flyio/dist/types.d.ts
+```
+
+#### `ProcessEnv`
+
+Environment variables the Fly.io sandbox provider reads. Every one is
+overridden by the matching {@link FlyioConfig} field.
+
+```typescript
+interface ProcessEnv {
+  /** Fly API token. Also accepted as `FLY_ACCESS_TOKEN`. */
+  FLY_API_TOKEN?: string
+  /** Fly API token (flyctl's variable name). Used when `FLY_API_TOKEN` is unset. */
+  FLY_ACCESS_TOKEN?: string
+  /** Machines API base URL. `/v1` is appended when the value carries no path. */
+  FLY_API_HOSTNAME?: string
+  /** Fly organization slug owning the sandbox apps (default `personal`). */
+  FLY_ORG_SLUG?: string
+  /** Shared Fly app name, used only when `FLY_SANDBOX_APP_PER_PROJECT=false`. */
+  FLY_SANDBOX_APP?: string
+  /** Per-project Fly app name prefix (default `mol-sandbox`). */
+  FLY_SANDBOX_APP_PREFIX?: string
+  /** `false` disables per-project apps (refused in production). */
+  FLY_SANDBOX_APP_PER_PROJECT?: string
+  /** Fly region for Machines and volumes (default `iad`). */
+  FLY_REGION?: string
+  /** OCI image for sandbox Machines. */
+  FLY_SANDBOX_IMAGE?: string
   /**
-   * Lifetime of the presigned capture/restore URL handed to a sandbox, in
-   * seconds. Defaults to 3600 and is clamped to AWS's documented 7-day ceiling
-   * for a SigV4 presigned URL. It only has to outlast the START of the transfer:
-   * S3 "checks the expiration date and time of a signed URL at the time of the
-   * HTTP request", so a download already in progress is not cut off.
+   * Comma-separated `protocol:port` pairs a sandbox may open outbound
+   * connections on (e.g. `tcp:3128,udp:53`). Set it to make this provider apply
+   * a Fly network policy to every sandbox app; unset means no policy.
    */
-  templateUrlExpirySeconds?: number
+  FLY_SANDBOX_EGRESS_ALLOWED_PORTS?: string
   /**
-   * Wall-clock budget for one capture or restore transfer, in ms. Defaults to
-   * 900000 (15 min). Also bounds how long a stale restore lease keeps a template
-   * pinned against eviction.
+   * Comma-separated `<fly-app>:<port>` pairs every sandbox must reach across its
+   * per-project 6PN, e.g. `molecule-pg-tenant:5432,molecule-api:3129`. Each one
+   * gets a Flycast private address allocated into the project's network at app
+   * creation and released on destroy. Overridden by `config.privateServices`.
    */
-  templateTransferTimeoutMs?: number
+  FLY_SANDBOX_PRIVATE_SERVICES?: string
   /**
-   * Largest template archive this provider will store, in bytes. Defaults to
-   * and is clamped by S3's 5 GB single-`PUT` ceiling, because the sandbox
-   * uploads with exactly one presigned `PUT`. The capture refuses before
-   * spending the bandwidth.
+   * Comma-separated literal `ip:port` targets the egress probe attempts. Shared
+   * with the Docker bond so a provider swap keeps the same configuration.
    */
-  templateMaxArchiveBytes?: number
-}
-```
-
-#### `FlyIpAssignment`
-
-An IP assignment, as returned by `POST`/`GET /v1/apps/{app}/ip_assignments`
-(`IPAssignment` in https://docs.machines.dev/openapi.json).
-
-Note what is NOT here: the assignment's **network**. Fly's own schema is
-`{created_at, ip, region, service_name, shared}`, so a listing cannot tell you
-which 6PN a private address serves — which is why this provider records the
-addresses it allocated in the sandbox Machine's metadata instead of
-rediscovering them.
-
-```typescript
-interface FlyIpAssignment {
-  /** The allocated address. Required for a later `DELETE .../ip_assignments/{ip}`. */
-  ip?: string
-  /** Region the address was allocated in, when Fly reports one. */
-  region?: string
-  /** Service the address is bound to, when the assignment names one. */
-  service_name?: string
-  /** Whether the address is shared (Anycast v4) rather than dedicated. */
-  shared?: boolean
+  SANDBOX_EGRESS_PROBE_TARGETS?: string
+  /** Per-connection timeout for the egress probe, in ms (default 3000). */
+  SANDBOX_EGRESS_PROBE_TIMEOUT_MS?: string
+  /** Bucket holding sandbox templates. Overridden by `config.templateBucket`. */
+  SANDBOX_TEMPLATE_BUCKET?: string
+  /** Bucket name as exported by `fly storage create`. Used when `SANDBOX_TEMPLATE_BUCKET` is unset. */
+  BUCKET_NAME?: string
+  /** S3 endpoint for the template bucket. Overridden by `config.templateEndpoint`. */
+  SANDBOX_TEMPLATE_ENDPOINT?: string
+  /** S3 endpoint as exported by `fly storage create`. Used when `SANDBOX_TEMPLATE_ENDPOINT` is unset. */
+  AWS_ENDPOINT_URL_S3?: string
+  /** Signing region for the template store (default `auto`). Overridden by `config.templateRegion`. */
+  SANDBOX_TEMPLATE_REGION?: string
+  /** Signing region, standard AWS variable. Used when `SANDBOX_TEMPLATE_REGION` is unset. */
+  AWS_REGION?: string
+  /** Access key for the template store. Overridden by `config.templateAccessKeyId`. */
+  SANDBOX_TEMPLATE_ACCESS_KEY_ID?: string
+  /** Access key, standard AWS variable (also what `fly storage create` sets). */
+  AWS_ACCESS_KEY_ID?: string
+  /** Secret key for the template store. Overridden by `config.templateSecretAccessKey`. */
+  SANDBOX_TEMPLATE_SECRET_ACCESS_KEY?: string
+  /** Secret key, standard AWS variable (also what `fly storage create` sets). */
+  AWS_SECRET_ACCESS_KEY?: string
+  /** Session token for the template store. Overridden by `config.templateSessionToken`. */
+  SANDBOX_TEMPLATE_SESSION_TOKEN?: string
+  /** Session token, standard AWS variable. */
+  AWS_SESSION_TOKEN?: string
+  /** Key prefix for template objects (default `molecule-sandbox-templates`). */
+  SANDBOX_TEMPLATE_PREFIX?: string
+  /** `true` addresses the template bucket path-style rather than virtual-host style. */
+  SANDBOX_TEMPLATE_FORCE_PATH_STYLE?: string
 }
 ```
 
-#### `FlyMachine`
+#### `FlyPrivateService`
 
-A Fly Machine, as returned by the Machines API (fields this provider reads).
+One app made reachable from every sandbox's per-project 6PN through a Flycast
+private address.
+
+See the `flycast.ts` module description for why this exists at all: apps on
+separate 6PNs "can never communicate unless explicitly configured to do so",
+and this declaration IS that explicit configuration.
 
 ```typescript
-interface FlyMachine {
-  id: string
-  name?: string
-  /** Optional so a response that omits it degrades to `created` rather than crashing the mapper. */
-  state?: FlyMachineState
-  region?: string
-  private_ip?: string
-  config?: FlyMachineConfig
-  /** RFC 3339 creation time, as Fly reports it. */
-  created_at?: string
+interface FlyPrivateService {
   /**
-   * Lifecycle events, newest first. The ONLY place Fly records when a Machine
-   * was first started — there is no `started_at` field — which is what
-   * distinguishes a stopped Machine from one that was created and never ran.
+   * The Fly app to allocate a Flycast address ON. The sandbox reaches it at
+   * `<app>.flycast`. It must already exist, must carry a services block, and
+   * must be in the same organization.
    */
-  events?: FlyMachineEvent[]
-}
-```
-
-#### `FlyMachineConfig`
-
-Machine configuration (`fly.MachineConfig`) — the subset this provider writes.
-
-```typescript
-interface FlyMachineConfig {
-  image: string
-  env?: Record<string, string>
-  metadata?: Record<string, string>
-  guest?: { cpus?: number; cpu_kind?: string; memory_mb?: number }
-  mounts?: Array<{ volume?: string; name?: string; path: string }>
-  services?: FlyMachineService[]
-  restart?: { policy?: 'no' | 'always' | 'on-failure' | 'spot-price'; max_retries?: number }
-  auto_destroy?: boolean
-  init?: { exec?: string[]; entrypoint?: string[]; cmd?: string[]; tty?: boolean }
-}
-```
-
-#### `FlyMachineEvent`
-
-One entry of {@link FlyMachine.events}.
-
-```typescript
-interface FlyMachineEvent {
-  /** `start`, `launch`, `exit`, … */
-  type?: string
-  status?: string
-  /** Epoch milliseconds. */
-  timestamp?: number
+  app: string
+  /**
+   * The TCP port a sandbox dials it at. Unioned into the egress network policy,
+   * and checked against every `.flycast` URL in a sandbox's environment.
+   */
+  port: number
 }
 ```
 
-#### `FlyMachineService`
-
-A Fly Proxy service attached to a Machine (`fly.MachineService`).
-
-```typescript
-interface FlyMachineService {
-  protocol: string
-  internal_port: number
-  ports: Array<{ port: number; handlers?: string[]; force_https?: boolean }>
-  autostart?: boolean
-  autostop?: 'off' | 'stop' | 'suspend'
-  min_machines_running?: number
-}
-```
+#### `FlyIpAssignment`
 
-#### `FlyNetworkPolicy`
+An IP assignment, as returned by `POST`/`GET /v1/apps/{app}/ip_assignments`
+(`IPAssignment` in https://docs.machines.dev/openapi.json).
 
-A Fly network policy, as accepted by
-`POST /v1/apps/{app}/network_policies`. The endpoint is documented in Fly's
-guide and announcement but is NOT in its OpenAPI specification, so only the
-fields those two documents show are modelled.
+Note what is NOT here: the assignment's **network**. Fly's own schema is
+`{created_at, ip, region, service_name, shared}`, so a listing cannot tell you
+which 6PN a private address serves — which is why this provider records the
+addresses it allocated in the sandbox Machine's metadata instead of
+rediscovering them.
 
 ```typescript
-interface FlyNetworkPolicy {
-  /** Present to UPDATE an existing policy; omitted to create one. */
-  id?: string
-  /** Policy name, unique per app in practice. */
-  name: string
-  /** Machines the policy applies to. */
-  selector: FlyNetworkPolicySelector
-  /** The allow rules. */
-  rules: FlyNetworkPolicyRule[]
+interface FlyIpAssignment {
+  /** The allocated address. Required for a later `DELETE .../ip_assignments/{ip}`. */
+  ip?: string
+  /** Region the address was allocated in, when Fly reports one. */
+  region?: string
+  /** Service the address is bound to, when the assignment names one. */
+  service_name?: string
+  /** Whether the address is shared (Anycast v4) rather than dedicated. */
+  shared?: boolean
 }
 ```
 
@@ -636,266 +639,169 @@ interface FlyNetworkPolicySelector {
 }
 ```
 
-#### `FlyOrgMachine`
+#### `FlyNetworkPolicy`
 
-A Machine as returned by the org-wide list endpoint (`GET /orgs/{org}/machines`).
+A Fly network policy, as accepted by
+`POST /v1/apps/{app}/network_policies`. The endpoint is documented in Fly's
+guide and announcement but is NOT in its OpenAPI specification, so only the
+fields those two documents show are modelled.
 
 ```typescript
-interface FlyOrgMachine extends FlyMachine {
-  app_name: string
+interface FlyNetworkPolicy {
+  /** Present to UPDATE an existing policy; omitted to create one. */
+  id?: string
+  /** Policy name, unique per app in practice. */
+  name: string
+  /** Machines the policy applies to. */
+  selector: FlyNetworkPolicySelector
+  /** The allow rules. */
+  rules: FlyNetworkPolicyRule[]
 }
 ```
 
-#### `FlyPrivateService`
-
-One app made reachable from every sandbox's per-project 6PN through a Flycast
-private address.
+#### `FlyMachine`
 
-See the `flycast.ts` module description for why this exists at all: apps on
-separate 6PNs "can never communicate unless explicitly configured to do so",
-and this declaration IS that explicit configuration.
+A Fly Machine, as returned by the Machines API (fields this provider reads).
 
 ```typescript
-interface FlyPrivateService {
-  /**
-   * The Fly app to allocate a Flycast address ON. The sandbox reaches it at
-   * `<app>.flycast`. It must already exist, must carry a services block, and
-   * must be in the same organization.
-   */
-  app: string
+interface FlyMachine {
+  id: string
+  name?: string
+  /** Optional so a response that omits it degrades to `created` rather than crashing the mapper. */
+  state?: FlyMachineState
+  region?: string
+  private_ip?: string
+  config?: FlyMachineConfig
+  /** RFC 3339 creation time, as Fly reports it. */
+  created_at?: string
   /**
-   * The TCP port a sandbox dials it at. Unioned into the egress network policy,
-   * and checked against every `.flycast` URL in a sandbox's environment.
+   * Lifecycle events, newest first. The ONLY place Fly records when a Machine
+   * was first started — there is no `started_at` field — which is what
+   * distinguishes a stopped Machine from one that was created and never ran.
    */
-  port: number
+  events?: FlyMachineEvent[]
 }
 ```
 
-#### `FlyRequestOptions`
+#### `FlyMachineEvent`
 
-Options for a single Fly API request.
+One entry of {@link FlyMachine.events}.
 
 ```typescript
-interface FlyRequestOptions {
-  /** HTTP method. Defaults to `GET`. */
-  method?: string
-  /** JSON request body. Omitted entirely when undefined. */
-  body?: unknown
-  /** Per-request timeout in ms. Defaults to the client's configured timeout. */
-  timeoutMs?: number
-  /** Max attempts for a retryable failure. Defaults to 4. Pass 1 to disable retries. */
-  attempts?: number
-  /**
-   * Treat these HTTP statuses as a successful `null` result instead of throwing.
-   * Used for idempotent deletes and existence checks (`[404]`).
-   */
-  nullOn?: number[]
-  /**
-   * Extra HTTP statuses to treat as transient (retry) beyond the default
-   * `429`/`5xx`. The exec endpoint passes `[404]`: a machine-not-found for a
-   * Machine we just created and are actively driving is Fly API inconsistency
-   * under exec-burst load, not a real absence, so it is worth repeating.
-   */
-  retryStatuses?: number[]
+interface FlyMachineEvent {
+  /** `start`, `launch`, `exit`, … */
+  type?: string
+  status?: string
+  /** Epoch milliseconds. */
+  timestamp?: number
 }
 ```
 
-#### `FlyVolume`
+#### `FlyApp`
 
-A Fly volume (fields this provider reads).
+An app as returned by `GET /v1/apps?org_slug=…` (the fields this provider reads).
 
 ```typescript
-interface FlyVolume {
-  id: string
+interface FlyApp {
+  id?: string
   name: string
-  state?: string
-  size_gb?: number
-  region?: string
-  attached_machine_id?: string
+  machine_count?: number
 }
 ```
 
-#### `ObjectStore`
-
-The object-store operations the template capability needs.
+#### `FlyAppList`
 
-Declared as an interface so `templates.ts` stays transport-free and its tests
-can drive a fake store, the same way `exec.ts` takes an injected `RawExec`.
+Response body of `GET /v1/apps?org_slug=…`.
 
 ```typescript
-interface ObjectStore {
-  /** Human-readable identification of the store, for error messages. */
-  readonly describe: string
-  /** Bucket holding the templates. Used to render the opaque `SandboxTemplate.ref`. */
-  readonly bucket: string
-  /** Key prefix every template object lives under, with no trailing slash. */
-  readonly prefix: string
-  /**
-   * Every object under a prefix, following pagination to the end.
-   * THROWS on failure — a caller that deletes must never read a failed query as
-   * "nothing is there".
-   */
-  list(prefix: string): Promise<StoredObject[]>
-  /** One object's metadata, or `null` when it does not exist. Throws on any other failure. */
-  head(key: string): Promise<StoredObject | null>
-  /** An object's body as text, or `null` when it does not exist. Throws on any other failure. */
-  getText(key: string): Promise<string | null>
-  /** Write a small text object. */
-  putText(key: string, body: string, contentType: string): Promise<void>
-  /** Delete objects. Deleting a key that is not there is a success. */
-  remove(keys: string[]): Promise<void>
-  /** A presigned URL a sandbox can `PUT` an archive to. */
-  presignPut(key: string, expiresInSeconds: number): Promise<string>
-  /** A presigned URL a sandbox can `GET` an archive from. */
-  presignGet(key: string, expiresInSeconds: number): Promise<string>
+interface FlyAppList {
+  /** Total apps in the org, which the returned page may not cover. */
+  total_apps?: number
+  apps?: FlyApp[]
 }
 ```
 
-#### `ProcessEnv`
+#### `FlyOrgMachine`
 
-Environment variables the Fly.io sandbox provider reads. Every one is
-overridden by the matching {@link FlyioConfig} field.
+A Machine as returned by the org-wide list endpoint (`GET /orgs/{org}/machines`).
 
 ```typescript
-interface ProcessEnv {
-  /** Fly API token. Also accepted as `FLY_ACCESS_TOKEN`. */
-  FLY_API_TOKEN?: string
-  /** Fly API token (flyctl's variable name). Used when `FLY_API_TOKEN` is unset. */
-  FLY_ACCESS_TOKEN?: string
-  /** Machines API base URL. `/v1` is appended when the value carries no path. */
-  FLY_API_HOSTNAME?: string
-  /** Fly organization slug owning the sandbox apps (default `personal`). */
-  FLY_ORG_SLUG?: string
-  /** Shared Fly app name, used only when `FLY_SANDBOX_APP_PER_PROJECT=false`. */
-  FLY_SANDBOX_APP?: string
-  /** Per-project Fly app name prefix (default `mol-sandbox`). */
-  FLY_SANDBOX_APP_PREFIX?: string
-  /** `false` disables per-project apps (refused in production). */
-  FLY_SANDBOX_APP_PER_PROJECT?: string
-  /** Fly region for Machines and volumes (default `iad`). */
-  FLY_REGION?: string
-  /** OCI image for sandbox Machines. */
-  FLY_SANDBOX_IMAGE?: string
-  /**
-   * Comma-separated `protocol:port` pairs a sandbox may open outbound
-   * connections on (e.g. `tcp:3128,udp:53`). Set it to make this provider apply
-   * a Fly network policy to every sandbox app; unset means no policy.
-   */
-  FLY_SANDBOX_EGRESS_ALLOWED_PORTS?: string
-  /**
-   * Comma-separated `<fly-app>:<port>` pairs every sandbox must reach across its
-   * per-project 6PN, e.g. `molecule-pg-tenant:5432,molecule-api:3129`. Each one
-   * gets a Flycast private address allocated into the project's network at app
-   * creation and released on destroy. Overridden by `config.privateServices`.
-   */
-  FLY_SANDBOX_PRIVATE_SERVICES?: string
-  /**
-   * Comma-separated literal `ip:port` targets the egress probe attempts. Shared
-   * with the Docker bond so a provider swap keeps the same configuration.
-   */
-  SANDBOX_EGRESS_PROBE_TARGETS?: string
-  /** Per-connection timeout for the egress probe, in ms (default 3000). */
-  SANDBOX_EGRESS_PROBE_TIMEOUT_MS?: string
-  /** Bucket holding sandbox templates. Overridden by `config.templateBucket`. */
-  SANDBOX_TEMPLATE_BUCKET?: string
-  /** Bucket name as exported by `fly storage create`. Used when `SANDBOX_TEMPLATE_BUCKET` is unset. */
-  BUCKET_NAME?: string
-  /** S3 endpoint for the template bucket. Overridden by `config.templateEndpoint`. */
-  SANDBOX_TEMPLATE_ENDPOINT?: string
-  /** S3 endpoint as exported by `fly storage create`. Used when `SANDBOX_TEMPLATE_ENDPOINT` is unset. */
-  AWS_ENDPOINT_URL_S3?: string
-  /** Signing region for the template store (default `auto`). Overridden by `config.templateRegion`. */
-  SANDBOX_TEMPLATE_REGION?: string
-  /** Signing region, standard AWS variable. Used when `SANDBOX_TEMPLATE_REGION` is unset. */
-  AWS_REGION?: string
-  /** Access key for the template store. Overridden by `config.templateAccessKeyId`. */
-  SANDBOX_TEMPLATE_ACCESS_KEY_ID?: string
-  /** Access key, standard AWS variable (also what `fly storage create` sets). */
-  AWS_ACCESS_KEY_ID?: string
-  /** Secret key for the template store. Overridden by `config.templateSecretAccessKey`. */
-  SANDBOX_TEMPLATE_SECRET_ACCESS_KEY?: string
-  /** Secret key, standard AWS variable (also what `fly storage create` sets). */
-  AWS_SECRET_ACCESS_KEY?: string
-  /** Session token for the template store. Overridden by `config.templateSessionToken`. */
-  SANDBOX_TEMPLATE_SESSION_TOKEN?: string
-  /** Session token, standard AWS variable. */
-  AWS_SESSION_TOKEN?: string
-  /** Key prefix for template objects (default `molecule-sandbox-templates`). */
-  SANDBOX_TEMPLATE_PREFIX?: string
-  /** `true` addresses the template bucket path-style rather than virtual-host style. */
-  SANDBOX_TEMPLATE_FORCE_PATH_STYLE?: string
+interface FlyOrgMachine extends FlyMachine {
+  app_name: string
 }
 ```
 
-#### `StoredObject`
+#### `FlyMachineConfig`
 
-One object as this bond needs to see it.
+Machine configuration (`fly.MachineConfig`) — the subset this provider writes.
 
 ```typescript
-interface StoredObject {
-  /** Full key, including the configured prefix. */
-  key: string
-  /** Size in bytes. */
-  size: number
-  /** Last-modified timestamp, ISO 8601, or `null` when the store did not report one. */
-  lastModified: string | null
+interface FlyMachineConfig {
+  image: string
+  env?: Record<string, string>
+  metadata?: Record<string, string>
+  guest?: { cpus?: number; cpu_kind?: string; memory_mb?: number }
+  mounts?: Array<{ volume?: string; name?: string; path: string }>
+  services?: FlyMachineService[]
+  restart?: { policy?: 'no' | 'always' | 'on-failure' | 'spot-price'; max_retries?: number }
+  auto_destroy?: boolean
+  init?: { exec?: string[]; entrypoint?: string[]; cmd?: string[]; tty?: boolean }
 }
 ```
 
-#### `TemplateContext`
+#### `FlyMachineService`
 
-What the template capability needs from the provider.
+A Fly Proxy service attached to a Machine (`fly.MachineService`).
 
 ```typescript
-interface TemplateContext {
-  /** The configured object store, or `null` when the operator has not configured one. */
-  store: ObjectStore | null
-  /** Runs a shell command inside a Machine and returns its result. */
-  exec(app: string, machineId: string, command: string, timeoutMs: number): Promise<ExecResult>
-  /** Blocks until a Machine is running, so it can be exec'd into. */
-  ensureStarted(app: string, machineId: string): Promise<void>
-  /** Splits a composite sandbox id into its app and Machine id. */
-  parseSandboxId(id: string): { app: string; machineId: string }
-  /** Lifetime of a presigned capture/restore URL, in seconds. */
-  presignExpirySeconds: number
-  /** Wall-clock budget for a capture or restore transfer, in ms. */
-  transferTimeoutMs: number
-  /** Largest archive this provider will store, in bytes. */
-  maxArchiveBytes: number
-  warn?: (message: string, meta?: Record<string, unknown>) => void
-  debug?: (message: string, meta?: Record<string, unknown>) => void
+interface FlyMachineService {
+  protocol: string
+  internal_port: number
+  ports: Array<{ port: number; handlers?: string[]; force_https?: boolean }>
+  autostart?: boolean
+  autostop?: 'off' | 'stop' | 'suspend'
+  min_machines_running?: number
 }
 ```
 
-#### `TemplateManifest`
+#### `FlyVolume`
 
-The control-plane-written record of a template. Its existence defines the template's existence.
+A Fly volume (fields this provider reads).
 
 ```typescript
-interface TemplateManifest {
-  /** Schema version of this record. */
-  schema: number
-  /** The caller's template id. */
+interface FlyVolume {
   id: string
-  /**
-   * Absolute paths captured, exactly as the caller named them.
-   *
-   * This is the security-relevant field: on restore these become `tar`'s member
-   * selectors, so the extraction surface is control-plane policy rather than
-   * anything the captured sandbox could influence.
-   */
-  capturePaths: string[]
-  /** When the capture completed, ISO 8601. */
-  createdAt: string
-  /** Archive size in bytes as observed in the store at capture time. */
-  sizeBytes: number
-  /** Free-form label recorded at capture time. */
-  label?: string
+  name: string
+  state?: string
+  size_gb?: number
+  region?: string
+  attached_machine_id?: string
+}
+```
+
+#### `FlyExecResponse`
+
+Response body of `POST /v1/apps/{app}/machines/{id}/exec` (`flydv1.ExecResponse`).
+
+```typescript
+interface FlyExecResponse {
+  stdout?: string
+  stderr?: string
+  exit_code?: number
+  exit_signal?: number
 }
 ```
 
 ### Types
 
+#### `RawExec`
+
+Runs one exec call against a Machine. Injected so this module stays transport-free.
+
+```typescript
+type RawExec = (command: string[], timeoutSeconds: number) => Promise<FlyExecResponse>
+```
+
 #### `FlyMachineState`
 
 A Fly Machine state, as documented at https://fly.io/docs/machines/machine-states/.
@@ -924,275 +830,314 @@ type FlyMachineState =
   | (string & {})
 ```
 
-#### `RawExec`
-
-Runs one exec call against a Machine. Injected so this module stays transport-free.
-
-```typescript
-type RawExec = (command: string[], timeoutSeconds: number) => Promise<FlyExecResponse>
-```
-
 ### Classes
 
-#### `FlyApiClient`
-
-Minimal Fly Machines API client: bearer auth, JSON bodies, per-request
-timeout, bounded retries with backoff, and account-wide request pacing via
-{@link paceFlyRequest}.
-
 #### `FlyApiError`
 
 An error from the Fly Machines API. Carries the HTTP status and the raw
 response body so callers can branch on `404` (absent) or `409` (conflict)
 without string-matching a message.
 
-### Functions
-
-#### `acquireRestoreLease(ctx, templateId, leaseId)`
-
-Records that a restore of this template is in flight.
-
-The lease lives in the store rather than in this process, so a second control
-plane enforcing a retention budget can see it. A control plane that dies
-mid-restore leaves the lease behind; it stops counting once it is older than
-the transfer budget, because no live restore can outlast that budget.
-
-```typescript
-function acquireRestoreLease(
-  ctx: TemplateContext,
-  templateId: string,
-  leaseId: string,
-): Promise<string>
-```
-
-- `ctx` — Template context.
-- `templateId` — The caller's identifier.
-- `leaseId` — Unique id for this restore.
-
-**Returns:** The lease's key, for release.
-
-#### `appNameForProject(prefix, projectId)`
-
-Derives a Fly app name for a project.
-
-Fly app names are globally unique DNS labels: lowercase alphanumerics and
-hyphens, no leading/trailing hyphen, at most 63 characters (they become
-`<app>.fly.dev`). Project ids are uuids, so `<prefix>-<uuid>` fits with room
-to spare; longer ids are truncated rather than rejected, and the trailing
-hyphen that truncation can leave is stripped.
-
-```typescript
-function appNameForProject(prefix: string, projectId: string): string
-```
-
-- `prefix` — Configured app-name prefix.
-- `projectId` — The project id from `SandboxConfig`.
-
-**Returns:** A syntactically valid Fly app name.
-
-#### `archiveKey(store, templateId)`
-
-Key of a template's archive object.
-
-```typescript
-function archiveKey(store: ObjectStore, templateId: string): string
-```
-
-#### `archiveMember(path)`
-
-Converts an absolute capture path into the relative member name used in the
-archive, so an archive of `/workspace` holds `workspace/…` and extracts with
-`tar -C /`.
-
 ```typescript
-function archiveMember(path: string): string
-```
-
-- `path` — Absolute capture path.
+class FlyApiError extends Error {
+  /** HTTP status code, or 0 for a transport-level failure (timeout, DNS, reset). */
+  readonly status: number
+  /** Raw response body text, truncated to a sane length for logging. */
+  readonly body: string
+  /** HTTP method of the failed request. */
+  readonly method: string
+  /** API path of the failed request (no base URL). */
+  readonly path: string
 
-**Returns:** The path with its leading and trailing slashes removed.
-
-#### `assertCapturePath(path)`
-
-Validate a path that will be interpolated into a `sh -c` command AND used as a
-`tar` member selector.
-
-```typescript
-function assertCapturePath(path: string): void
+  /**
+   * Creates a Fly API error.
+   * @param method - HTTP method of the failed request.
+   * @param path - API path of the failed request.
+   * @param status - HTTP status code, or 0 for a transport failure.
+   * @param body - Raw response body text.
+   * @param options - Standard error options (used to carry a `cause`).
+   */
+  constructor(
+    method: string,
+    path: string,
+    status: number,
+    body: string,
+    options?: { cause?: unknown },
+  ) {
+    super(
+      t(
+        'codeSandbox.flyio.error.apiError',
+        { method, path, status: String(status), error: body },
+        { defaultValue: `Fly API ${method} ${path}: ${status} ${body}` },
+      ),
+      options,
+    )
+    this.name = 'FlyApiError'
+    this.status = status
+    this.body = body
+    this.method = method
+    this.path = path
+  }
+}
 ```
 
-- `path` — Candidate absolute path inside the sandbox.
-
-#### `assertPrivateRoutesForEnv(env, services)`
-
-Refuses to boot a sandbox that is told to dial a Flycast host this provider
-did not allocate a route for.
-
-This is the check that turns the product-breaking failure into a startup
-error. The control plane bakes `DATABASE_URL` (and the proxy environment) into
-every sandbox; on Fly those must name `<app>.flycast`, and that name resolves
-ONLY because this provider allocated a private address into the project's
-network for that app. Get the two out of step — a `SANDBOX_DB_HOST` pointing
-at an app nobody declared, a port that does not match the one the policy
-allows — and the sandbox boots healthy, the scaffolded app cannot connect, and
-the only symptom is a connection timeout inside someone else's project.
+#### `FlyApiClient`
 
-It is also the guard on the control-plane cluster: reaching
-`molecule-pg-control.flycast` from a sandbox would require an operator to have
-declared it as a private service, which is an explicit act with its own name
-in the configuration — never something this provider arranges on its own.
+Minimal Fly Machines API client: bearer auth, JSON bodies, per-request
+timeout, bounded retries with backoff, and account-wide request pacing via
+{@link paceFlyRequest}.
 
 ```typescript
-function assertPrivateRoutesForEnv(
-  env: Record<string, string> | undefined,
-  services: FlyPrivateService[] | undefined,
-): void
-```
-
-- `env` — The environment the caller is baking into the sandbox.
-- `services` — The declared private services, or `undefined`.
-
-#### `assertTemplateId(templateId)`
+class FlyApiClient {
+  private readonly token: () => string | undefined
+  private readonly baseUrl: string
+  private readonly timeoutMs: number
+  private readonly fetchImpl: typeof fetch
+  /**
+   * 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>
 
-Validate a caller-supplied template id.
+  /**
+   * Creates a Fly Machines API client.
+   * @param options - Token resolver, base URL, and injectable fetch/sleep.
+   */
+  constructor(options: FlyApiClientOptions) {
+    this.token = options.token
+    this.baseUrl = options.baseUrl
+    this.timeoutMs = options.timeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS
+    this.fetchImpl = options.fetchImpl ?? globalThis.fetch
+    this.sleep =
+      options.sleep ?? ((ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms)))
+  }
 
-```typescript
-function assertTemplateId(templateId: string): void
+  /**
+   * Issues a request against the Machines API and parses the JSON response.
+   *
+   * @template T - Expected shape of the parsed response body.
+   * @param path - API path relative to the base URL, e.g. `/apps/foo/machines`.
+   * @param options - Method, body, timeout, attempts, and statuses to null on.
+   * @returns The parsed body, or `null` for an empty body or a status listed in
+   *   `options.nullOn`.
+   * @throws {FlyApiError} On a non-2xx status that is not listed in `nullOn`,
+   *   or when every retryable attempt is exhausted.
+   */
+  async request<T>(path: string, options: FlyRequestOptions = {}): Promise<T | null> {
+    const method = options.method ?? 'GET'
+    const attempts = options.attempts ?? DEFAULT_ATTEMPTS
+    const token = this.token()
+    if (!token) {
+      throw new Error(
+        t('codeSandbox.flyio.error.noToken', undefined, {
+          defaultValue:
+            'No Fly API token — set FLY_API_TOKEN (or FLY_ACCESS_TOKEN), or pass config.apiToken.',
+        }),
+      )
+    }
+
+    let lastError: FlyApiError | undefined
+    for (let attempt = 1; attempt <= attempts; attempt++) {
+      // Pace EVERY network call (including retries) through the process-wide
+      // limiter so a boot's burst of exec calls never trips Fly's account 429.
+      await paceFlyRequest(this.sleep)
+      const controller = new AbortController()
+      const timer = setTimeout(() => controller.abort(), options.timeoutMs ?? this.timeoutMs)
+      // Initialized to 0 ("no answer received"), which is the value that
+      // stands when the request throws before a response arrives.
+      let status = 0
+      let retryAfter: string | null = null
+      try {
+        const response = await this.fetchImpl(`${this.baseUrl}${path}`, {
+          method,
+          headers: {
+            Authorization: `Bearer ${token}`,
+            ...(options.body === undefined ? {} : { 'Content-Type': 'application/json' }),
+          },
+          ...(options.body === undefined ? {} : { body: JSON.stringify(options.body) }),
+          signal: controller.signal,
+        })
+        status = response.status
+        retryAfter = response.headers?.get?.('retry-after') ?? null
+        const text = await response.text()
+
+        if (status >= 200 && status < 300) {
+          if (!text.trim()) return null
+          try {
+            return JSON.parse(text) as T
+          } catch (error) {
+            // A 2xx with a non-JSON body is a real protocol surprise (an
+            // intercepting proxy, an HTML error page behind a 200). Refusing it
+            // loudly beats handing the caller a silently-empty result.
+            throw new FlyApiError(method, path, status, text.slice(0, 500), { cause: error })
+          }
+        }
+        if (options.nullOn?.includes(status)) return null
+        lastError = new FlyApiError(method, path, status, text.slice(0, 500))
+      } catch (error) {
+        if (error instanceof FlyApiError) throw error
+        // Transport-level failure (abort/timeout, DNS, connection reset) — no
+        // status was ever received, so it is modelled as status 0 and retried.
+        lastError = new FlyApiError(
+          method,
+          path,
+          0,
+          error instanceof Error ? error.message : String(error),
+          { cause: error },
+        )
+      } finally {
+        clearTimeout(timer)
+      }
+
+      const retryable =
+        isRetryableStatus(status) || (options.retryStatuses?.includes(status) ?? false)
+      if (!retryable || attempt === attempts) break
+      const delay = retryDelayMs(attempt, retryAfter)
+      logger.warn(`Fly API transient failure on ${method} ${path} — retrying`, {
+        attempt,
+        attempts,
+        status,
+        delay,
+      })
+      await this.sleep(delay)
+    }
+
+    throw lastError ?? new FlyApiError(method, path, 0, 'unknown failure')
+  }
+}
 ```
 
-- `templateId` — The caller's identifier.
-
-#### `buildCaptureCommand(paths, url, maxBytes)`
-
-Builds the in-sandbox capture command: archive the named paths, refuse an
-oversized result, and upload it to a presigned URL.
+### Functions
 
-The archive is written to a file BEFORE the upload rather than piped into
-`curl`, for two reasons that both bite: a pipeline reports only the last
-command's status, so a failed `tar` would upload a truncated archive and
-report success; and an upload from a pipe has no `Content-Length`, so `curl`
-sends `Transfer-Encoding: chunked`, which S3 rejects on a presigned `PUT`.
+#### `isRetryableStatus(status)`
+
+Decides whether a failed attempt is worth repeating.
+
+`429` (the documented per-action rate limit) and `5xx` are transient — the
+request was well-formed and the same call can succeed moments later. Every
+other `4xx` is a real answer (no such app, name taken, bad token) and
+retrying it only wastes the rate-limit budget that the retry exists to
+protect. Status `0` means the transport failed before any answer arrived.
 
 ```typescript
-function buildCaptureCommand(paths: string[], url: string, maxBytes: number): string
+function isRetryableStatus(status: number): boolean
 ```
 
-- `paths` — Absolute capture paths, already validated.
-- `url` — Presigned `PUT` URL for the archive object.
-- `maxBytes` — Largest archive that may be uploaded.
+- `status` — HTTP status, or 0 for a transport-level failure.
 
-**Returns:** A `sh` script.
+**Returns:** `true` when the request should be retried.
 
-#### `buildEgressProbeCommand(targets, timeoutMs)`
+#### `retryDelayMs(attempt, retryAfter)`
 
-Builds the shell command that observes egress from inside a Machine.
+Resolves how long to wait before the next attempt.
 
-Raw `net.connect` on purpose: an HTTP client would honour proxy environment
-variables and report the PROXY's policy instead of the network's. Every target
-is attempted in parallel and the process exits
-{@link EGRESS_PROBE_EXIT_REACHED} if any connected,
-{@link EGRESS_PROBE_EXIT_BLOCKED} if all were refused or timed out.
+Honors a `Retry-After` header when the server sent one (Fly returns it on
+429), clamped to {@link MAX_RETRY_DELAY_MS}; otherwise uses exponential
+backoff from a 500 ms base. Fly's documented budget is one request per second
+per action, so the first backoff step deliberately exceeds a second.
 
 ```typescript
-function buildEgressProbeCommand(targets: EgressProbeTarget[], timeoutMs: number): string
+function retryDelayMs(attempt: number, retryAfter?: string | null): number
 ```
 
-- `targets` — Literal targets to attempt.
-- `timeoutMs` — Per-connection timeout.
+- `attempt` — The 1-based attempt number that just failed.
+- `retryAfter` — Raw `Retry-After` header value, if present.
 
-**Returns:** A `sh`-safe command string.
+**Returns:** The delay in milliseconds before the next attempt.
 
-#### `buildRestoreCommand(paths, url)`
+#### `normalizeApiUrl(value)`
 
-Builds the in-sandbox restore command: download the archive, extract ONLY the
-manifest's paths, and prove no setuid/setgid file survived.
+Normalizes a configured API base into a URL prefix ending in `/v1`.
 
-See the module docs for why each flag is here. The download is to a file
-rather than piped into `tar` so a failed download cannot be reported as a
-successful extraction of a truncated stream.
+`FLY_API_HOSTNAME` is documented as a bare host (`https://api.machines.dev`,
+or `http://_api.internal:4280` from inside a Fly private network), so a value
+with no path gets `/v1` appended. A value that already carries a path is used
+verbatim, which is how an operator points at a proxy or a pinned version.
 
 ```typescript
-function buildRestoreCommand(paths: string[], url: string): string
+function normalizeApiUrl(value: string | undefined): string
 ```
 
-- `paths` — Absolute capture paths from the CONTROL-PLANE manifest.
-- `url` — Presigned `GET` URL for the archive object.
+- `value` — Configured base URL, or undefined.
 
-**Returns:** A `sh` script.
+**Returns:** The base URL with no trailing slash.
 
-#### `buildScript(command, opts, defaultCwd)`
+#### `resetFlyPacerForTests()`
 
-Builds the shell script body for a command: change directory, export the
-requested environment, then run the command.
+Test-only: reset the shared pacer so timing tests start from a clean slate.
 
 ```typescript
-function buildScript(command: string, opts: ExecOptions | undefined, defaultCwd: string): string
+function resetFlyPacerForTests(): void
 ```
 
-- `command` — The shell command to run.
-- `opts` — Optional cwd and environment.
-- `defaultCwd` — Directory used when `opts.cwd` is unset.
-
-**Returns:** The script source, newline separated.
-
-#### `commitTemplate(ctx, options)`
+#### `formatEgressProbeTarget(target)`
 
-Capture a sandbox's filesystem into a reusable template.
+Renders a target the way it is written in configuration, so an operator can
+paste it straight back.
 
 ```typescript
-function commitTemplate(
-  ctx: TemplateContext,
-  options: CommitTemplateOptions,
-): Promise<SandboxTemplate>
+function formatEgressProbeTarget(target: EgressProbeTarget): string
 ```
 
-- `ctx` — Template context.
-- `options` — What to capture and what to call it.
+- `target` — The parsed target.
 
-**Returns:** The template as it now exists.
+**Returns:** `host:port`, with IPv6 hosts bracketed.
 
-#### `createProvider(config, client, store)`
+#### `parseEgressProbeTargets(raw)`
 
-Creates a Fly.io Machines sandbox provider.
+Parses probe targets from configuration.
+
+Only LITERAL addresses are accepted, never hostnames — Fly's own
+troubleshooting guidance for testing a policy is to "use direct IP addresses
+(not hostnames) to test blocked traffic to avoid DNS masking", and a probe
+that failed at name resolution would report a blocked connection it never
+actually attempted.
 
 ```typescript
-function createProvider(
-  config?: FlyioConfig,
-  client?: FlyApiClient,
-  store?: ObjectStore | null,
-): SandboxProvider
+function parseEgressProbeTargets(raw: string | string[] | undefined): EgressProbeTarget[]
 ```
 
-- `config` — Optional Fly configuration: API token/URL, org slug, app naming and isolation mode, region, base image, guest sizing, preview service, and the preview URL template. Every field has an env fallback.
-- `client` — Injectable Machines API client, for tests.
-- `store` — Injectable template object store, for tests. Resolved from the template settings (or their env fallbacks) on first use when omitted.
+- `raw` — Comma-separated `ip:port` string, or an array of them. IPv6 literals must be bracketed (`[2606:4700:4700::1111]:443`).
 
-**Returns:** A `SandboxProvider` backed by Fly Machines.
+**Returns:** The valid targets, in order. Invalid entries are dropped rather than throwing: the caller turns an empty result into an `inconclusive` verdict, which is the honest outcome for "nothing to probe".
 
-#### `createTemplateStore(config)`
+#### `parseEgressAllowedPorts(raw)`
 
-Creates the object store used for templates, or `null` when it is not
-configured.
+Parses an allowed-port list for the egress network policy.
+
+An EMPTY list is deliberately not expressible. Fly documents the deny default
+as a consequence of at least one `allow` rule existing for a direction; what
+an allow rule with zero ports does is not documented anywhere, so a provider
+that sent one would be guessing at a security control. An operator who wants
+near-total denial allows a single port nothing in the sandbox uses.
 
 ```typescript
-function createTemplateStore(config: FlyioConfig): ObjectStore | null
+function parseEgressAllowedPorts(raw: string | undefined): FlyNetworkPolicyPort[] | undefined
 ```
 
-- `config` — Fly provider configuration; every field has an env fallback.
+- `raw` — Comma-separated `protocol:port` pairs, e.g. `tcp:3128,udp:53`. A bare port is treated as TCP.
 
-**Returns:** An {@link ObjectStore}, or `null` when no bucket/credentials are set.
+**Returns:** The parsed ports, or `undefined` when the input is absent or empty (meaning "apply no policy"), which is NOT the same as "deny everything".
 
-#### `decodePrivateRoutes(raw)`
+#### `buildEgressProbeCommand(targets, timeoutMs)`
 
-Decodes the addresses recorded by {@link encodePrivateRoutes}.
+Builds the shell command that observes egress from inside a Machine.
+
+Raw `net.connect` on purpose: an HTTP client would honour proxy environment
+variables and report the PROXY's policy instead of the network's. Every target
+is attempted in parallel and the process exits
+{@link EGRESS_PROBE_EXIT_REACHED} if any connected,
+{@link EGRESS_PROBE_EXIT_BLOCKED} if all were refused or timed out.
 
 ```typescript
-function decodePrivateRoutes(raw: string | undefined): Record<string, string>
+function buildEgressProbeCommand(targets: EgressProbeTarget[], timeoutMs: number): string
 ```
 
-- `raw` — The metadata value, or `undefined` when the Machine carries none.
+- `targets` — Literal targets to attempt.
+- `timeoutMs` — Per-connection timeout.
 
-**Returns:** Target app name → allocated private address. Unparseable entries are skipped: this value only drives cleanup and self-healing, and a malformed entry must not stop either.
+**Returns:** A `sh`-safe command string.
 
 #### `describePublicReach(policyPorts)`
 
@@ -1216,42 +1161,58 @@ function describePublicReach(policyPorts: FlyNetworkPolicyPort[] | undefined): s
 
 **Returns:** A sentence naming the public reach, or `''` when there is nothing to say (no policy, or nothing but UDP/53 — DNS is a documented residual of its own and not a TCP channel).
 
-#### `encodePrivateRoutes(routes)`
+#### `unexpectedPolicyPorts(applied, intended)`
 
-Encodes allocated addresses for storage in Machine metadata.
+Finds ports the policy Fly holds allows that this provider never configured.
+
+The raw-connect probe can only speak for the targets it was handed, so a
+policy widened outside this provider — edited by hand to unblock something, or
+left behind by an older build — is invisible to it: the probe's own port stays
+denied and the verdict stays `filtered` while a port nothing here asked for is
+open to the whole internet. Comparing what Fly holds against what this
+provider intended is the one check that can catch that, and it is why the
+verdict reads the policy back rather than trusting the write.
 
 ```typescript
-function encodePrivateRoutes(routes: Record<string, string>): string
+function unexpectedPolicyPorts(
+  applied: FlyNetworkPolicyPort[] | undefined,
+  intended: FlyNetworkPolicyPort[] | undefined,
+): FlyNetworkPolicyPort[]
 ```
 
-- `routes` — Target app name → allocated private address.
+- `applied` — Ports in the policy Fly actually holds, or `undefined` when the readback found nothing (in which case there is nothing to compare).
+- `intended` — Ports this provider configured, or `undefined` when it applies no policy.
 
-**Returns:** `app=address` pairs joined by commas. An IPv6 literal contains neither `,` nor `=`, so the encoding is unambiguous.
+**Returns:** The applied ports with no counterpart in `intended`, in order.
 
-#### `execCommand(rawExec, command, opts, defaultCwd)`
+#### `verdictForProbeExit(exitCode, context)`
 
-Executes a command on a Machine, choosing the direct or detached strategy
-based on the caller's time budget.
+Maps a probe's exit status onto an {@link EgressVerdict}.
 
-A command too large to pass inline (over {@link FLY_EXEC_MAX_ARG_BYTES}) is
-spilled to a file via chunked writes and run from there, so there is no size
-ceiling the caller must respect.
+The mapping is the whole security contract of this file, so it is total and
+has exactly one path to each state:
+
+| Exit                              | Verdict        | Meaning                                  |
+| --------------------------------- | -------------- | ---------------------------------------- |
+| {@link EGRESS_PROBE_EXIT_REACHED} | `open`         | A raw socket reached a public IP.        |
+| {@link EGRESS_PROBE_EXIT_BLOCKED} | `filtered`     | Every attempt was refused or timed out.  |
+| anything else                     | `inconclusive` | The probe did not complete its attempts. |
+
+Every other outcome — a missing interpreter (127), a killed process, Fly
+returning no status at all (-1), an API failure before the probe ever ran — is
+`inconclusive`. Collapsing any of those into `filtered` is precisely the "I
+could not look" ⇒ "I looked and it is safe" conflation the capability exists
+to prevent, and the caller refuses to boot production on anything but
+`filtered`.
 
 ```typescript
-function execCommand(
-  rawExec: RawExec,
-  command: string,
-  opts: ExecOptions | undefined,
-  defaultCwd: string,
-): Promise<ExecResult>
+function verdictForProbeExit(exitCode: number, context: EgressProbeContext): EgressVerdict
 ```
 
-- `rawExec` — Transport callback issuing one Fly exec call.
-- `command` — The shell command to run.
-- `opts` — Core exec options (cwd, env, timeout in ms).
-- `defaultCwd` — Working directory used when `opts.cwd` is unset.
+- `exitCode` — The probe process's exit status.
+- `context` — App, targets and the policy this provider applied.
 
-**Returns:** The command's stdout, stderr and exit code.
+**Returns:** The verdict.
 
 #### `extractPolicyId(response, name)`
 
@@ -1298,7 +1259,63 @@ function extractPolicyPorts(response: unknown, name: string): FlyNetworkPolicyPo
 - `response` — The raw parsed LIST response.
 - `name` — The policy name to match.
 
-**Returns:** The allowed egress ports, or `undefined` when no policy of that name is present or the shape is unrecognized. `undefined` means "nothing to compare", never "nothing is allowed".
+**Returns:** The allowed egress ports, or `undefined` when no policy of that name is present or the shape is unrecognized. `undefined` means "nothing to compare", never "nothing is allowed".
+
+#### `toExecResult(response)`
+
+Normalizes a Fly exec response into the core `ExecResult`.
+
+Fly reports `exit_signal` separately from `exit_code`; a signalled process has
+no meaningful exit code, so it is rendered the way a POSIX shell does, as
+`128 + signal`.
+
+```typescript
+function toExecResult(response: FlyExecResponse): ExecResult
+```
+
+- `response` — The raw Fly exec response.
+
+**Returns:** The normalized result.
+
+#### `buildScript(command, opts, defaultCwd)`
+
+Builds the shell script body for a command: change directory, export the
+requested environment, then run the command.
+
+```typescript
+function buildScript(command: string, opts: ExecOptions | undefined, defaultCwd: string): string
+```
+
+- `command` — The shell command to run.
+- `opts` — Optional cwd and environment.
+- `defaultCwd` — Directory used when `opts.cwd` is unset.
+
+**Returns:** The script source, newline separated.
+
+#### `execCommand(rawExec, command, opts, defaultCwd)`
+
+Executes a command on a Machine, choosing the direct or detached strategy
+based on the caller's time budget.
+
+A command too large to pass inline (over {@link FLY_EXEC_MAX_ARG_BYTES}) is
+spilled to a file via chunked writes and run from there, so there is no size
+ceiling the caller must respect.
+
+```typescript
+function execCommand(
+  rawExec: RawExec,
+  command: string,
+  opts: ExecOptions | undefined,
+  defaultCwd: string,
+): Promise<ExecResult>
+```
+
+- `rawExec` — Transport callback issuing one Fly exec call.
+- `command` — The shell command to run.
+- `opts` — Core exec options (cwd, env, timeout in ms).
+- `defaultCwd` — Working directory used when `opts.cwd` is unset.
+
+**Returns:** The command's stdout, stderr and exit code.
 
 #### `flycastHost(app)`
 
@@ -1312,115 +1329,161 @@ function flycastHost(app: string): string
 
 **Returns:** `<app>.flycast`.
 
-#### `formatEgressProbeTarget(target)`
+#### `parsePrivateServices(raw)`
 
-Renders a target the way it is written in configuration, so an operator can
-paste it straight back.
+Parses the declared cross-network services.
+
+Each entry is `<app>:<port>` — the Fly app to allocate a Flycast address on,
+and the TCP port a sandbox dials it at. The port is not cosmetic: it is what
+{@link mergeEgressPorts} adds to the Fly network policy, and what
+{@link assertPrivateRoutesForEnv} checks the injected connection URLs against.
 
 ```typescript
-function formatEgressProbeTarget(target: EgressProbeTarget): string
+function parsePrivateServices(raw: string | undefined): FlyPrivateService[] | undefined
 ```
 
-- `target` — The parsed target.
+- `raw` — Comma-separated `app:port` pairs, e.g. `molecule-pg-tenant:5432,molecule-api:3129`.
 
-**Returns:** `host:port`, with IPv6 hosts bracketed.
+**Returns:** The declared services, deduplicated, in order — or `undefined` when the input is absent or empty, meaning "allocate nothing", which is correct for a control plane that shares one 6PN with its sandboxes.
 
-#### `getTemplate(ctx, templateId)`
+#### `mergeEgressPorts(ports, services)`
 
-Read one template by the caller's identifier.
+Adds every declared private-service port to the egress network policy.
+
+A Fly network policy is deny-by-default once any rule exists for a direction,
+so a sandbox told to dial `molecule-pg-tenant.flycast:5432` under a policy
+allowing only `tcp:3128` would fail to connect with no diagnostic beyond a
+timeout. Deriving the port from the declaration — rather than asking the
+operator to keep two lists in step — is what makes that class of outage
+impossible: FLY-OPERATOR-SETUP.md § 9 can keep saying "never widen this list",
+because the operator never has to.
+
+It is deliberately a UNION and never a replacement, so an operator's list is
+still exactly what they wrote plus the ports their own declarations require,
+and the applied policy is logged.
+
+The addition is load-bearing — VERIFIED 2026-08-16, not inferred. Fly states
+"Network policies only apply to traffic directly to and from Machines. They do
+not affect traffic routed through the Fly Proxy"
+(https://fly.io/docs/machines/guides-examples/network-policies/), and Flycast
+traffic IS routed through Fly Proxy, so it was an open question whether these
+ports did anything. Measured on a throwaway app with a Flycast address into
+its own 6PN: under a policy allowing only `udp:53`, `molecule-pg-tenant.flycast`
+and `molecule-api.flycast` both RESOLVED and every TCP connect to them was
+dropped; re-applying the policy with `tcp:443` opened 443 and nothing else.
+Fly's sentence is about INGRESS — a Machine's egress TOWARD a Flycast address
+
+_(description truncated — read the full text in `node_modules/@molecule/api-code-sandbox-flyio/dist/flycast.d.ts`.)_
 
 ```typescript
-function getTemplate(ctx: TemplateContext, templateId: string): Promise<SandboxTemplate | null>
+function mergeEgressPorts(
+  ports: FlyNetworkPolicyPort[] | undefined,
+  services: FlyPrivateService[] | undefined,
+): FlyNetworkPolicyPort[] | undefined
 ```
 
-- `ctx` — Template context.
-- `templateId` — The caller's identifier.
-
-**Returns:** The template, or `null` when no template has that id.
+- `ports` — The operator's configured ports, or `undefined` when no policy is being applied at all.
+- `services` — The declared private services, or `undefined`.
 
-#### `hasLiveLease(leases, ttlMs, now)`
+**Returns:** The union, deduplicated — or `undefined` when `ports` is `undefined`. "No policy" is never turned INTO a policy here: applying one that Fly then uses to drop everything else is not something to infer from an unrelated setting.
 
-Decides whether any lease means a restore is still in flight.
+#### `encodePrivateRoutes(routes)`
 
-A lease with no readable timestamp counts as LIVE. That is the whole rule the
-core states for this field: an unreadable answer resolves to in-use, never to
-free.
+Encodes allocated addresses for storage in Machine metadata.
 
 ```typescript
-function hasLiveLease(leases: StoredObject[], ttlMs: number, now: number): boolean
+function encodePrivateRoutes(routes: Record<string, string>): string
 ```
 
-- `leases` — Lease objects for one template.
-- `ttlMs` — How long a lease can possibly correspond to a live restore.
-- `now` — Current time in ms since the epoch.
+- `routes` — Target app name → allocated private address.
 
-**Returns:** `true` when at least one lease is live.
+**Returns:** `app=address` pairs joined by commas. An IPv6 literal contains neither `,` nor `=`, so the encoding is unambiguous.
 
-#### `isFailedState(state)`
+#### `decodePrivateRoutes(raw)`
 
-Reports whether a Fly Machine state means the Machine errored, rather than
-having been stopped on purpose. {@link mapMachineState} flattens both to
-`stopped` because the core union has no failure status, so this is the only
-way to tell them apart.
+Decodes the addresses recorded by {@link encodePrivateRoutes}.
 
 ```typescript
-function isFailedState(state: FlyMachineState): boolean
+function decodePrivateRoutes(raw: string | undefined): Record<string, string>
 ```
 
-- `state` — Raw Fly Machine state string.
+- `raw` — The metadata value, or `undefined` when the Machine carries none.
 
-**Returns:** `true` for `failed` and `launch_failed`.
+**Returns:** Target app name → allocated private address. Unparseable entries are skipped: this value only drives cleanup and self-healing, and a malformed entry must not stop either.
 
-#### `isRetryableStatus(status)`
+#### `assertPrivateRoutesForEnv(env, services)`
 
-Decides whether a failed attempt is worth repeating.
+Refuses to boot a sandbox that is told to dial a Flycast host this provider
+did not allocate a route for.
 
-`429` (the documented per-action rate limit) and `5xx` are transient — the
-request was well-formed and the same call can succeed moments later. Every
-other `4xx` is a real answer (no such app, name taken, bad token) and
-retrying it only wastes the rate-limit budget that the retry exists to
-protect. Status `0` means the transport failed before any answer arrived.
+This is the check that turns the product-breaking failure into a startup
+error. The control plane bakes `DATABASE_URL` (and the proxy environment) into
+every sandbox; on Fly those must name `<app>.flycast`, and that name resolves
+ONLY because this provider allocated a private address into the project's
+network for that app. Get the two out of step — a `SANDBOX_DB_HOST` pointing
+at an app nobody declared, a port that does not match the one the policy
+allows — and the sandbox boots healthy, the scaffolded app cannot connect, and
+the only symptom is a connection timeout inside someone else's project.
+
+It is also the guard on the control-plane cluster: reaching
+`molecule-pg-control.flycast` from a sandbox would require an operator to have
+declared it as a private service, which is an explicit act with its own name
+in the configuration — never something this provider arranges on its own.
 
 ```typescript
-function isRetryableStatus(status: number): boolean
+function assertPrivateRoutesForEnv(
+  env: Record<string, string> | undefined,
+  services: FlyPrivateService[] | undefined,
+): void
 ```
 
-- `status` — HTTP status, or 0 for a transport-level failure.
-
-**Returns:** `true` when the request should be retried.
+- `env` — The environment the caller is baking into the sandbox.
+- `services` — The declared private services, or `undefined`.
 
-#### `leaseKey(store, templateId, leaseId)`
+#### `toSandboxId(app, machineId)`
 
-Key of one in-flight restore lease.
+Builds the opaque sandbox id addressing one Machine inside one app.
 
 ```typescript
-function leaseKey(store: ObjectStore, templateId: string, leaseId: string): string
+function toSandboxId(app: string, machineId: string): string
 ```
 
-#### `listTemplates(ctx, options)`
+- `app` — Fly app name.
+- `machineId` — Fly Machine id.
 
-Enumerate templates so the caller can apply its retention policy.
+**Returns:** The composite sandbox id.
+
+#### `parseSandboxId(id)`
+
+Splits a composite sandbox id back into its app and Machine id.
 
 ```typescript
-function listTemplates(
-  ctx: TemplateContext,
-  options?: ListTemplatesOptions,
-): Promise<SandboxTemplate[]>
+function parseSandboxId(id: string): { app: string; machineId: string }
 ```
 
-- `ctx` — Template context.
-- `options` — Narrowing by id prefix.
+- `id` — A sandbox id previously produced by {@link toSandboxId}.
 
-**Returns:** Every matching template.
+**Returns:** The app name and Machine id.
 
-#### `manifestKey(store, templateId)`
+#### `appNameForProject(prefix, projectId)`
 
-Key of a template's manifest object.
+Derives a Fly app name for a project.
+
+Fly app names are globally unique DNS labels: lowercase alphanumerics and
+hyphens, no leading/trailing hyphen, at most 63 characters (they become
+`<app>.fly.dev`). Project ids are uuids, so `<prefix>-<uuid>` fits with room
+to spare; longer ids are truncated rather than rejected, and the trailing
+hyphen that truncation can leave is stripped.
 
 ```typescript
-function manifestKey(store: ObjectStore, templateId: string): string
+function appNameForProject(prefix: string, projectId: string): string
 ```
 
+- `prefix` — Configured app-name prefix.
+- `projectId` — The project id from `SandboxConfig`.
+
+**Returns:** A syntactically valid Fly app name.
+
 #### `mapMachineState(state)`
 
 Maps a Fly Machine state onto the core `Sandbox['status']` union.
@@ -1449,197 +1512,163 @@ function mapMachineState(state: FlyMachineState): 'creating' | 'stopped' | 'runn
 
 **Returns:** The core sandbox status.
 
-#### `mergeEgressPorts(ports, services)`
-
-Adds every declared private-service port to the egress network policy.
-
-A Fly network policy is deny-by-default once any rule exists for a direction,
-so a sandbox told to dial `molecule-pg-tenant.flycast:5432` under a policy
-allowing only `tcp:3128` would fail to connect with no diagnostic beyond a
-timeout. Deriving the port from the declaration — rather than asking the
-operator to keep two lists in step — is what makes that class of outage
-impossible: FLY-OPERATOR-SETUP.md § 9 can keep saying "never widen this list",
-because the operator never has to.
-
-It is deliberately a UNION and never a replacement, so an operator's list is
-still exactly what they wrote plus the ports their own declarations require,
-and the applied policy is logged.
-
-The addition is load-bearing — VERIFIED 2026-08-16, not inferred. Fly states
-"Network policies only apply to traffic directly to and from Machines. They do
-not affect traffic routed through the Fly Proxy"
-(https://fly.io/docs/machines/guides-examples/network-policies/), and Flycast
-traffic IS routed through Fly Proxy, so it was an open question whether these
-ports did anything. Measured on a throwaway app with a Flycast address into
-its own 6PN: under a policy allowing only `udp:53`, `molecule-pg-tenant.flycast`
-and `molecule-api.flycast` both RESOLVED and every TCP connect to them was
-dropped; re-applying the policy with `tcp:443` opened 443 and nothing else.
-Fly's sentence is about INGRESS — a Machine's egress TOWARD a Flycast address
-is filtered like any other. Drop a declared service's port and every database
-connection in the fleet goes with it.
+#### `isFailedState(state)`
 
-The cost of each derived port, stated plainly because a Fly policy has no
-destination field of any kind (also measured — see the `egress.ts` module
-description): the port is opened to EVERY host on the internet, not only to
-the private service it was derived for. That residual cannot be closed at this
-layer; it is named in `verifyEgress()`'s verdict and in
-`docs/sandbox-egress-enforcement.md`.
+Reports whether a Fly Machine state means the Machine errored, rather than
+having been stopped on purpose. {@link mapMachineState} flattens both to
+`stopped` because the core union has no failure status, so this is the only
+way to tell them apart.
 
 ```typescript
-function mergeEgressPorts(
-  ports: FlyNetworkPolicyPort[] | undefined,
-  services: FlyPrivateService[] | undefined,
-): FlyNetworkPolicyPort[] | undefined
+function isFailedState(state: FlyMachineState): boolean
 ```
 
-- `ports` — The operator's configured ports, or `undefined` when no policy is being applied at all.
-- `services` — The declared private services, or `undefined`.
+- `state` — Raw Fly Machine state string.
 
-**Returns:** The union, deduplicated — or `undefined` when `ports` is `undefined`. "No policy" is never turned INTO a policy here: applying one that Fly then uses to drop everything else is not something to infer from an unrelated setting.
+**Returns:** `true` for `failed` and `launch_failed`.
 
-#### `normalizeApiUrl(value)`
+#### `isTransientExecPrecondition(error)`
 
-Normalizes a configured API base into a URL prefix ending in `/v1`.
+Whether a failed exec is Fly's TRANSIENT precondition — the request reached
+the Machine's exec agent and the connection was dropped before the command
+ran (`412 failed_precondition: exec request failed: EOF`) — rather than the
+Machine being in a state an exec cannot run in.
 
-`FLY_API_HOSTNAME` is documented as a bare host (`https://api.machines.dev`,
-or `http://_api.internal:4280` from inside a Fly private network), so a value
-with no path gets `/v1` appended. A value that already carries a path is used
-verbatim, which is how an operator points at a proxy or a pinned version.
+The distinction decides what retrying can achieve. A dropped connection is
+worth repeating: the Machine is `started` and its agent recovers in seconds.
+`failed_precondition: machine not running` is NOT — the Machine really is not
+running, and that is what {@link FlyioSandboxProvider.startMachine} waits out
+before the first exec. Repeating the exec there would only burn the caller's
+budget against a condition the wait endpoint already answers.
 
 ```typescript
-function normalizeApiUrl(value: string | undefined): string
+function isTransientExecPrecondition(error: unknown): boolean
 ```
 
-- `value` — Configured base URL, or undefined.
-
-**Returns:** The base URL with no trailing slash.
+- `error` — The failure an exec attempt raised.
 
-#### `parseEgressAllowedPorts(raw)`
+**Returns:** `true` when repeating the exec is the right recovery.
 
-Parses an allowed-port list for the egress network policy.
+#### `createProvider(config, client, store)`
 
-An EMPTY list is deliberately not expressible. Fly documents the deny default
-as a consequence of at least one `allow` rule existing for a direction; what
-an allow rule with zero ports does is not documented anywhere, so a provider
-that sent one would be guessing at a security control. An operator who wants
-near-total denial allows a single port nothing in the sandbox uses.
+Creates a Fly.io Machines sandbox provider.
 
 ```typescript
-function parseEgressAllowedPorts(raw: string | undefined): FlyNetworkPolicyPort[] | undefined
+function createProvider(
+  config?: FlyioConfig,
+  client?: FlyApiClient,
+  store?: ObjectStore | null,
+): SandboxProvider
 ```
 
-- `raw` — Comma-separated `protocol:port` pairs, e.g. `tcp:3128,udp:53`. A bare port is treated as TCP.
+- `config` — Optional Fly configuration: API token/URL, org slug, app naming and isolation mode, region, base image, guest sizing, preview service, and the preview URL template. Every field has an env fallback.
+- `client` — Injectable Machines API client, for tests.
+- `store` — Injectable template object store, for tests. Resolved from the template settings (or their env fallbacks) on first use when omitted.
 
-**Returns:** The parsed ports, or `undefined` when the input is absent or empty (meaning "apply no policy"), which is NOT the same as "deny everything".
+**Returns:** A `SandboxProvider` backed by Fly Machines.
 
-#### `parseEgressProbeTargets(raw)`
+#### `resolveTemplateStorage(config)`
 
-Parses probe targets from configuration.
+Resolves template-storage settings from config and the environment.
 
-Only LITERAL addresses are accepted, never hostnames — Fly's own
-troubleshooting guidance for testing a policy is to "use direct IP addresses
-(not hostnames) to test blocked traffic to avoid DNS masking", and a probe
-that failed at name resolution would report a blocked connection it never
-actually attempted.
+Returns `null` when the store is not configured at all, which the template
+methods turn into an actionable error naming the settings. Partial
+configuration is treated as unconfigured for the same reason: half a
+connection cannot be used, and reporting it as a connection failure would
+point an operator at the network instead of at their settings.
 
 ```typescript
-function parseEgressProbeTargets(raw: string | string[] | undefined): EgressProbeTarget[]
+function resolveTemplateStorage(config: FlyioConfig): ResolvedStorage | null
 ```
 
-- `raw` — Comma-separated `ip:port` string, or an array of them. IPv6 literals must be bracketed (`[2606:4700:4700::1111]:443`).
-
-**Returns:** The valid targets, in order. Invalid entries are dropped rather than throwing: the caller turns an empty result into an `inconclusive` verdict, which is the honest outcome for "nothing to probe".
+- `config` — Fly provider configuration.
 
-#### `parsePrivateServices(raw)`
+**Returns:** The resolved settings, or `null` when storage is not configured.
 
-Parses the declared cross-network services.
+#### `createTemplateStore(config)`
 
-Each entry is `<app>:<port>` — the Fly app to allocate a Flycast address on,
-and the TCP port a sandbox dials it at. The port is not cosmetic: it is what
-{@link mergeEgressPorts} adds to the Fly network policy, and what
-{@link assertPrivateRoutesForEnv} checks the injected connection URLs against.
+Creates the object store used for templates, or `null` when it is not
+configured.
 
 ```typescript
-function parsePrivateServices(raw: string | undefined): FlyPrivateService[] | undefined
+function createTemplateStore(config: FlyioConfig): ObjectStore | null
 ```
 
-- `raw` — Comma-separated `app:port` pairs, e.g. `molecule-pg-tenant:5432,molecule-api:3129`.
+- `config` — Fly provider configuration; every field has an env fallback.
 
-**Returns:** The declared services, deduplicated, in order — or `undefined` when the input is absent or empty, meaning "allocate nothing", which is correct for a control plane that shares one 6PN with its sandboxes.
+**Returns:** An {@link ObjectStore}, or `null` when no bucket/credentials are set.
 
-#### `parseSandboxId(id)`
+#### `assertTemplateId(templateId)`
 
-Splits a composite sandbox id back into its app and Machine id.
+Validate a caller-supplied template id.
 
 ```typescript
-function parseSandboxId(id: string): { app: string; machineId: string }
+function assertTemplateId(templateId: string): void
 ```
 
-- `id` — A sandbox id previously produced by {@link toSandboxId}.
+- `templateId` — The caller's identifier.
 
-**Returns:** The app name and Machine id.
+#### `assertCapturePath(path)`
 
-#### `readTemplate(ctx, templateId)`
+Validate a path that will be interpolated into a `sh -c` command AND used as a
+`tar` member selector.
 
-Read one template, and the manifest behind it, by the caller's identifier.
+```typescript
+function assertCapturePath(path: string): void
+```
 
-Separate from {@link getTemplate} because the restore path needs the
-manifest's `capturePaths` — the extraction surface — and the public shape does
-not carry them.
+- `path` — Candidate absolute path inside the sandbox.
+
+#### `archiveMember(path)`
+
+Converts an absolute capture path into the relative member name used in the
+archive, so an archive of `/workspace` holds `workspace/…` and extracts with
+`tar -C /`.
 
 ```typescript
-function readTemplate(
-  ctx: TemplateContext,
-  templateId: string,
-): Promise<{ template: SandboxTemplate; manifest: TemplateManifest } | null>
+function archiveMember(path: string): string
 ```
 
-- `ctx` — Template context.
-- `templateId` — The caller's identifier.
-
-**Returns:** The template and its manifest, or `null` when no usable template exists.
+- `path` — Absolute capture path.
 
-#### `releaseRestoreLease(ctx, key)`
+**Returns:** The path with its leading and trailing slashes removed.
 
-Releases a restore lease.
+#### `manifestKey(store, templateId)`
 
-Best-effort: the restore has already finished, and a stale lease only delays
-an eviction until it ages out. Failing the boot over it would trade a
-completed sandbox for a bookkeeping error.
+Key of a template's manifest object.
 
 ```typescript
-function releaseRestoreLease(ctx: TemplateContext, key: string): Promise<void>
+function manifestKey(store: ObjectStore, templateId: string): string
 ```
 
-- `ctx` — Template context.
-- `key` — The lease key returned by {@link acquireRestoreLease}.
-
-#### `removeTemplate(ctx, templateId)`
+#### `archiveKey(store, templateId)`
 
-Delete a template, refusing while a restore is still reading it.
+Key of a template's archive object.
 
 ```typescript
-function removeTemplate(ctx: TemplateContext, templateId: string): Promise<void>
+function archiveKey(store: ObjectStore, templateId: string): string
 ```
 
-- `ctx` — Template context.
-- `templateId` — The caller's identifier.
+#### `leaseKey(store, templateId, leaseId)`
 
-#### `renderEnvExports(env)`
+Key of one in-flight restore lease.
 
-Renders `ExecOptions.env` as `export` statements to prepend to a script.
+```typescript
+function leaseKey(store: ObjectStore, templateId: string, leaseId: string): string
+```
 
-Fly's exec endpoint takes no environment map (only `command`, `stdin`,
-`container` and `timeout`), so per-command environment has to be set inside
-the shell script itself.
+#### `templateRef(store, templateId)`
+
+The provider-native reference for a template. OPAQUE to callers.
 
 ```typescript
-function renderEnvExports(env: Record<string, string> | undefined): string[]
+function templateRef(store: ObjectStore, templateId: string): string
 ```
 
-- `env` — Environment variables to set for the command.
+- `store` — The configured object store.
+- `templateId` — The caller's identifier.
 
-**Returns:** One `export NAME='value'` line per variable, in insertion order.
+**Returns:** An `s3://bucket/key` reference to the archive.
 
 #### `requireStore(ctx)`
 
@@ -1658,236 +1687,227 @@ function requireStore(ctx: TemplateContext): ObjectStore
 
 **Returns:** The configured store.
 
-#### `resetFlyPacerForTests()`
+#### `buildCaptureCommand(paths, url, maxBytes)`
 
-Test-only: reset the shared pacer so timing tests start from a clean slate.
+Builds the in-sandbox capture command: archive the named paths, refuse an
+oversized result, and upload it to a presigned URL.
+
+The archive is written to a file BEFORE the upload rather than piped into
+`curl`, for two reasons that both bite: a pipeline reports only the last
+command's status, so a failed `tar` would upload a truncated archive and
+report success; and an upload from a pipe has no `Content-Length`, so `curl`
+sends `Transfer-Encoding: chunked`, which S3 rejects on a presigned `PUT`.
 
 ```typescript
-function resetFlyPacerForTests(): void
+function buildCaptureCommand(paths: string[], url: string, maxBytes: number): string
 ```
 
-#### `resolveTemplateStorage(config)`
+- `paths` — Absolute capture paths, already validated.
+- `url` — Presigned `PUT` URL for the archive object.
+- `maxBytes` — Largest archive that may be uploaded.
 
-Resolves template-storage settings from config and the environment.
+**Returns:** A `sh` script.
 
-Returns `null` when the store is not configured at all, which the template
-methods turn into an actionable error naming the settings. Partial
-configuration is treated as unconfigured for the same reason: half a
-connection cannot be used, and reporting it as a connection failure would
-point an operator at the network instead of at their settings.
+#### `buildRestoreCommand(paths, url)`
+
+Builds the in-sandbox restore command: download the archive, extract ONLY the
+manifest's paths, and prove no setuid/setgid file survived.
+
+See the module docs for why each flag is here. The download is to a file
+rather than piped into `tar` so a failed download cannot be reported as a
+successful extraction of a truncated stream.
 
 ```typescript
-function resolveTemplateStorage(config: FlyioConfig): ResolvedStorage | null
+function buildRestoreCommand(paths: string[], url: string): string
 ```
 
-- `config` — Fly provider configuration.
+- `paths` — Absolute capture paths from the CONTROL-PLANE manifest.
+- `url` — Presigned `GET` URL for the archive object.
 
-**Returns:** The resolved settings, or `null` when storage is not configured.
+**Returns:** A `sh` script.
 
-#### `retryDelayMs(attempt, retryAfter)`
+#### `hasLiveLease(leases, ttlMs, now)`
 
-Resolves how long to wait before the next attempt.
+Decides whether any lease means a restore is still in flight.
 
-Honors a `Retry-After` header when the server sent one (Fly returns it on
-429), clamped to {@link MAX_RETRY_DELAY_MS}; otherwise uses exponential
-backoff from a 500 ms base. Fly's documented budget is one request per second
-per action, so the first backoff step deliberately exceeds a second.
+A lease with no readable timestamp counts as LIVE. That is the whole rule the
+core states for this field: an unreadable answer resolves to in-use, never to
+free.
 
 ```typescript
-function retryDelayMs(attempt: number, retryAfter?: string | null): number
+function hasLiveLease(leases: StoredObject[], ttlMs: number, now: number): boolean
 ```
 
-- `attempt` — The 1-based attempt number that just failed.
-- `retryAfter` — Raw `Retry-After` header value, if present.
+- `leases` — Lease objects for one template.
+- `ttlMs` — How long a lease can possibly correspond to a live restore.
+- `now` — Current time in ms since the epoch.
 
-**Returns:** The delay in milliseconds before the next attempt.
+**Returns:** `true` when at least one lease is live.
 
-#### `shellQuote(value)`
+#### `readTemplate(ctx, templateId)`
 
-Wraps a string in single quotes, escaping any single quotes it contains.
+Read one template, and the manifest behind it, by the caller's identifier.
 
-Every command this provider runs goes through `sh -c`, so an unquoted path or
-value is a command-injection vector. Double quotes are NOT sufficient — `$()`,
-backticks and `!` still expand inside them.
+Separate from {@link getTemplate} because the restore path needs the
+manifest's `capturePaths` — the extraction surface — and the public shape does
+not carry them.
 
 ```typescript
-function shellQuote(value: string): string
+function readTemplate(
+  ctx: TemplateContext,
+  templateId: string,
+): Promise<{ template: SandboxTemplate; manifest: TemplateManifest } | null>
 ```
 
-- `value` — The raw string to embed in a shell command.
+- `ctx` — Template context.
+- `templateId` — The caller's identifier.
 
-**Returns:** A single-quoted, shell-safe token.
+**Returns:** The template and its manifest, or `null` when no usable template exists.
 
-#### `templateRef(store, templateId)`
+#### `getTemplate(ctx, templateId)`
 
-The provider-native reference for a template. OPAQUE to callers.
+Read one template by the caller's identifier.
 
 ```typescript
-function templateRef(store: ObjectStore, templateId: string): string
+function getTemplate(ctx: TemplateContext, templateId: string): Promise<SandboxTemplate | null>
 ```
 
-- `store` — The configured object store.
+- `ctx` — Template context.
 - `templateId` — The caller's identifier.
 
-**Returns:** An `s3://bucket/key` reference to the archive.
-
-#### `toExecResult(response)`
+**Returns:** The template, or `null` when no template has that id.
 
-Normalizes a Fly exec response into the core `ExecResult`.
+#### `listTemplates(ctx, options)`
 
-Fly reports `exit_signal` separately from `exit_code`; a signalled process has
-no meaningful exit code, so it is rendered the way a POSIX shell does, as
-`128 + signal`.
+Enumerate templates so the caller can apply its retention policy.
 
 ```typescript
-function toExecResult(response: FlyExecResponse): ExecResult
+function listTemplates(
+  ctx: TemplateContext,
+  options?: ListTemplatesOptions,
+): Promise<SandboxTemplate[]>
 ```
 
-- `response` — The raw Fly exec response.
+- `ctx` — Template context.
+- `options` — Narrowing by id prefix.
 
-**Returns:** The normalized result.
+**Returns:** Every matching template.
 
-#### `toSandboxId(app, machineId)`
+#### `commitTemplate(ctx, options)`
 
-Builds the opaque sandbox id addressing one Machine inside one app.
+Capture a sandbox's filesystem into a reusable template.
 
 ```typescript
-function toSandboxId(app: string, machineId: string): string
+function commitTemplate(
+  ctx: TemplateContext,
+  options: CommitTemplateOptions,
+): Promise<SandboxTemplate>
 ```
 
-- `app` — Fly app name.
-- `machineId` — Fly Machine id.
-
-**Returns:** The composite sandbox id.
+- `ctx` — Template context.
+- `options` — What to capture and what to call it.
 
-#### `unexpectedPolicyPorts(applied, intended)`
+**Returns:** The template as it now exists.
 
-Finds ports the policy Fly holds allows that this provider never configured.
+#### `removeTemplate(ctx, templateId)`
 
-The raw-connect probe can only speak for the targets it was handed, so a
-policy widened outside this provider — edited by hand to unblock something, or
-left behind by an older build — is invisible to it: the probe's own port stays
-denied and the verdict stays `filtered` while a port nothing here asked for is
-open to the whole internet. Comparing what Fly holds against what this
-provider intended is the one check that can catch that, and it is why the
-verdict reads the policy back rather than trusting the write.
+Delete a template, refusing while a restore is still reading it.
 
 ```typescript
-function unexpectedPolicyPorts(
-  applied: FlyNetworkPolicyPort[] | undefined,
-  intended: FlyNetworkPolicyPort[] | undefined,
-): FlyNetworkPolicyPort[]
+function removeTemplate(ctx: TemplateContext, templateId: string): Promise<void>
 ```
 
-- `applied` — Ports in the policy Fly actually holds, or `undefined` when the readback found nothing (in which case there is nothing to compare).
-- `intended` — Ports this provider configured, or `undefined` when it applies no policy.
-
-**Returns:** The applied ports with no counterpart in `intended`, in order.
-
-#### `verdictForProbeExit(exitCode, context)`
-
-Maps a probe's exit status onto an {@link EgressVerdict}.
-
-The mapping is the whole security contract of this file, so it is total and
-has exactly one path to each state:
+- `ctx` — Template context.
+- `templateId` — The caller's identifier.
 
-| Exit                              | Verdict        | Meaning                                  |
-| --------------------------------- | -------------- | ---------------------------------------- |
-| {@link EGRESS_PROBE_EXIT_REACHED} | `open`         | A raw socket reached a public IP.        |
-| {@link EGRESS_PROBE_EXIT_BLOCKED} | `filtered`     | Every attempt was refused or timed out.  |
-| anything else                     | `inconclusive` | The probe did not complete its attempts. |
+#### `acquireRestoreLease(ctx, templateId, leaseId)`
 
-Every other outcome — a missing interpreter (127), a killed process, Fly
-returning no status at all (-1), an API failure before the probe ever ran — is
-`inconclusive`. Collapsing any of those into `filtered` is precisely the "I
-could not look" ⇒ "I looked and it is safe" conflation the capability exists
-to prevent, and the caller refuses to boot production on anything but
-`filtered`.
+Records that a restore of this template is in flight.
+
+The lease lives in the store rather than in this process, so a second control
+plane enforcing a retention budget can see it. A control plane that dies
+mid-restore leaves the lease behind; it stops counting once it is older than
+the transfer budget, because no live restore can outlast that budget.
 
 ```typescript
-function verdictForProbeExit(exitCode: number, context: EgressProbeContext): EgressVerdict
+function acquireRestoreLease(
+  ctx: TemplateContext,
+  templateId: string,
+  leaseId: string,
+): Promise<string>
 ```
 
-- `exitCode` — The probe process's exit status.
-- `context` — App, targets and the policy this provider applied.
+- `ctx` — Template context.
+- `templateId` — The caller's identifier.
+- `leaseId` — Unique id for this restore.
 
-**Returns:** The verdict.
+**Returns:** The lease's key, for release.
 
-### Constants
+#### `releaseRestoreLease(ctx, key)`
 
-#### `DEFAULT_EGRESS_POLICY_NAME`
+Releases a restore lease.
 
-Default name of the egress policy this provider owns on each sandbox app.
+Best-effort: the restore has already finished, and a stale lease only delays
+an eviction until it ages out. Failing the boot over it would trade a
+completed sandbox for a bookkeeping error.
 
 ```typescript
-const DEFAULT_EGRESS_POLICY_NAME: 'molecule-sandbox-egress'
+function releaseRestoreLease(ctx: TemplateContext, key: string): Promise<void>
 ```
 
-#### `DEFAULT_EGRESS_PROBE_TARGETS`
-
-Default probe targets: one IPv4 and one IPv6 literal, both anycast resolvers
-that answer on 443 from anywhere. IPv6 is included because Fly Machines have
-native public IPv6 egress and "often egress over IPv6 when the destination
-has an AAAA record" (https://fly.io/docs/networking/egress-ips/) — probing
-only IPv4 could miss an open v6 path entirely.
+- `ctx` — Template context.
+- `key` — The lease key returned by {@link acquireRestoreLease}.
 
-```typescript
-const DEFAULT_EGRESS_PROBE_TARGETS: '1.1.1.1:443,[2606:4700:4700::1111]:443'
-```
+#### `shellQuote(value)`
 
-#### `DEFAULT_PRESIGN_EXPIRY_SECONDS`
+Wraps a string in single quotes, escaping any single quotes it contains.
 
-Default lifetime of a presigned capture/restore URL, in seconds.
+Every command this provider runs goes through `sh -c`, so an unquoted path or
+value is a command-injection vector. Double quotes are NOT sufficient — `$()`,
+backticks and `!` still expand inside them.
 
 ```typescript
-const DEFAULT_PRESIGN_EXPIRY_SECONDS: 3600
+function shellQuote(value: string): string
 ```
 
-#### `DEFAULT_PRIVATE_IP_TYPE`
+- `value` — The raw string to embed in a shell command.
 
-`type` sent to `POST /apps/{app}/ip_assignments` for a Flycast address. This
-is the value flyctl passes for `fly ips allocate-v6 --private`; the field has
-no enum in Fly's OpenAPI specification, so it is configurable rather than
-hardcoded.
+**Returns:** A single-quoted, shell-safe token.
 
-```typescript
-const DEFAULT_PRIVATE_IP_TYPE: 'private_v6'
-```
+#### `renderEnvExports(env)`
 
-#### `DEFAULT_TEMPLATE_PREFIX`
+Renders `ExecOptions.env` as `export` statements to prepend to a script.
 
-Default key prefix for every object this bond writes.
+Fly's exec endpoint takes no environment map (only `command`, `stdin`,
+`container` and `timeout`), so per-command environment has to be set inside
+the shell script itself.
 
 ```typescript
-const DEFAULT_TEMPLATE_PREFIX: 'molecule-sandbox-templates'
+function renderEnvExports(env: Record<string, string> | undefined): string[]
 ```
 
-#### `DEFAULT_TEMPLATE_REGION`
+- `env` — Environment variables to set for the command.
 
-Region sent when none is configured. Tigris (and most S3-compatible stores)
-accept `auto`; the AWS SDK requires _some_ region to build a signature, so this
-is not optional even against a store that ignores it.
+**Returns:** One `export NAME='value'` line per variable, in insertion order.
 
-```typescript
-const DEFAULT_TEMPLATE_REGION: 'auto'
-```
+### Constants
 
-#### `DEFAULT_TRANSFER_TIMEOUT_MS`
+#### `DEFAULT_EGRESS_POLICY_NAME`
 
-Default wall-clock budget for a capture or restore transfer, in ms.
+Default name of the egress policy this provider owns on each sandbox app.
 
 ```typescript
-const DEFAULT_TRANSFER_TIMEOUT_MS: 900000
+const DEFAULT_EGRESS_POLICY_NAME: 'molecule-sandbox-egress'
 ```
 
-#### `DIRECT_EXEC_BUDGET_SECONDS`
+#### `EGRESS_PROBE_EXIT_REACHED`
 
-Largest budget still run as a single direct exec, in seconds. Kept below
-{@link FLY_EXEC_MAX_TIMEOUT_SECONDS} so the API's own timeout is never the
-thing that fires first — the caller's timeout should be.
+Probe exit status meaning at least one raw connection to a public IP
+SUCCEEDED. Deliberately not 1, so an interpreter error (which exits 1) can
+never be mistaken for a completed observation.
 
 ```typescript
-const DIRECT_EXEC_BUDGET_SECONDS: 55
+const EGRESS_PROBE_EXIT_REACHED: 9
 ```
 
 #### `EGRESS_PROBE_EXIT_BLOCKED`
@@ -1898,38 +1918,46 @@ Probe exit status meaning every raw connection attempt was refused or timed out.
 const EGRESS_PROBE_EXIT_BLOCKED: 0
 ```
 
-#### `EGRESS_PROBE_EXIT_REACHED`
+#### `DEFAULT_EGRESS_PROBE_TARGETS`
 
-Probe exit status meaning at least one raw connection to a public IP
-SUCCEEDED. Deliberately not 1, so an interpreter error (which exits 1) can
-never be mistaken for a completed observation.
+Default probe targets: one IPv4 and one IPv6 literal, both anycast resolvers
+that answer on 443 from anywhere. IPv6 is included because Fly Machines have
+native public IPv6 egress and "often egress over IPv6 when the destination
+has an AAAA record" (https://fly.io/docs/networking/egress-ips/) — probing
+only IPv4 could miss an open v6 path entirely.
 
 ```typescript
-const EGRESS_PROBE_EXIT_REACHED: 9
+const DEFAULT_EGRESS_PROBE_TARGETS: '1.1.1.1:443,[2606:4700:4700::1111]:443'
 ```
 
-#### `EXIT_ARCHIVE_TOO_LARGE`
+#### `FLY_EXEC_MAX_TIMEOUT_SECONDS`
 
-Exit status the capture script uses when the archive is over the size ceiling.
+Fly's hard ceiling on the exec endpoint's `timeout` field, in seconds.
+Verified against Fly staff guidance (see the module docs); a larger value is
+rejected by the API rather than clamped.
 
 ```typescript
-const EXIT_ARCHIVE_TOO_LARGE: 90
+const FLY_EXEC_MAX_TIMEOUT_SECONDS: 60
 ```
 
-#### `EXIT_SETUID_SURVIVED`
+#### `DIRECT_EXEC_BUDGET_SECONDS`
 
-Exit status the restore script uses when a setuid/setgid file survived the sweep.
+Largest budget still run as a single direct exec, in seconds. Kept below
+{@link FLY_EXEC_MAX_TIMEOUT_SECONDS} so the API's own timeout is never the
+thing that fires first — the caller's timeout should be.
 
 ```typescript
-const EXIT_SETUID_SURVIVED: 91
+const DIRECT_EXEC_BUDGET_SECONDS: 55
 ```
 
-#### `EXIT_TAR_FAILED`
+#### `MAX_CAPTURED_OUTPUT_BYTES`
 
-Exit status the capture script uses when `tar` failed outright (as opposed to warning).
+Cap on captured stdout/stderr per detached command, in bytes. The exec
+response carries output inline as JSON, so an unbounded `cat` of a build log
+would try to materialize the whole thing in one response body.
 
 ```typescript
-const EXIT_TAR_FAILED: 92
+const MAX_CAPTURED_OUTPUT_BYTES: number
 ```
 
 #### `FLY_EXEC_MAX_ARG_BYTES`
@@ -1946,14 +1974,15 @@ ceiling; callers that move bulk data (writeFile, importFiles) chunk beneath it.
 const FLY_EXEC_MAX_ARG_BYTES: 15000
 ```
 
-#### `FLY_EXEC_MAX_TIMEOUT_SECONDS`
+#### `INDETERMINATE_EXIT_CODE`
 
-Fly's hard ceiling on the exec endpoint's `timeout` field, in seconds.
-Verified against Fly staff guidance (see the module docs); a larger value is
-rejected by the API rather than clamped.
+Exit code reported when a command's outcome is genuinely unknown — it was
+still running when the caller's budget expired, or Fly returned no status.
+Distinct from every real shell exit status (0-255), matching the Docker
+provider's convention so callers can tell "unfinished" from "failed".
 
 ```typescript
-const FLY_EXEC_MAX_TIMEOUT_SECONDS: 60
+const INDETERMINATE_EXIT_CODE: -1
 ```
 
 #### `FLYCAST_SUFFIX`
@@ -1966,48 +1995,52 @@ allocated to it, there will be an AAAA record at `my-app-name.flycast`"
 const FLYCAST_SUFFIX: '.flycast'
 ```
 
-#### `INDETERMINATE_EXIT_CODE`
+#### `PRIVATE_ROUTES_METADATA_SUFFIX`
 
-Exit code reported when a command's outcome is genuinely unknown — it was
-still running when the caller's budget expired, or Fly returned no status.
-Distinct from every real shell exit status (0-255), matching the Docker
-provider's convention so callers can tell "unfinished" from "failed".
+Machine-metadata key suffix (after the configured prefix) recording the
+private addresses allocated for a project, so `destroy()` can release exactly
+the ones it created. See consequence 2 in the module description: a listing on
+the target app cannot tell you which network an address serves.
 
 ```typescript
-const INDETERMINATE_EXIT_CODE: -1
+const PRIVATE_ROUTES_METADATA_SUFFIX: 'privateRoutes'
 ```
 
-#### `LEASE_GRACE_MS`
+#### `DEFAULT_PRIVATE_IP_TYPE`
 
-Extra time a restore lease counts as live beyond the transfer budget, covering
-the Machine boot and the API round trips that bracket the transfer itself.
-A lease older than `transferTimeoutMs + this` cannot belong to a live restore,
-because the restore's own exec is bounded by that budget.
+`type` sent to `POST /apps/{app}/ip_assignments` for a Flycast address. This
+is the value flyctl passes for `fly ips allocate-v6 --private`; the field has
+no enum in Fly's OpenAPI specification, so it is configurable rather than
+hardcoded.
 
 ```typescript
-const LEASE_GRACE_MS: 120000
+const DEFAULT_PRIVATE_IP_TYPE: 'private_v6'
 ```
 
-#### `MAX_ARCHIVE_BYTES`
+#### `provider`
 
-Single-`PUT` ceiling: "With a single `PUT` operation, you can upload a single
-object up to 5 GB in size"
-(https://docs.aws.amazon.com/AmazonS3/latest/userguide/upload-objects.html).
-The sandbox uploads with one presigned PUT, so an archive above this cannot be
-stored and the capture refuses before spending the bandwidth.
+The provider implementation.
 
 ```typescript
-const MAX_ARCHIVE_BYTES: number
+const provider: SandboxProvider
 ```
 
-#### `MAX_CAPTURED_OUTPUT_BYTES`
+#### `DEFAULT_TEMPLATE_PREFIX`
 
-Cap on captured stdout/stderr per detached command, in bytes. The exec
-response carries output inline as JSON, so an unbounded `cat` of a build log
-would try to materialize the whole thing in one response body.
+Default key prefix for every object this bond writes.
 
 ```typescript
-const MAX_CAPTURED_OUTPUT_BYTES: number
+const DEFAULT_TEMPLATE_PREFIX: 'molecule-sandbox-templates'
+```
+
+#### `DEFAULT_TEMPLATE_REGION`
+
+Region sent when none is configured. Tigris (and most S3-compatible stores)
+accept `auto`; the AWS SDK requires _some_ region to build a signature, so this
+is not optional even against a store that ignores it.
+
+```typescript
+const DEFAULT_TEMPLATE_REGION: 'auto'
 ```
 
 #### `MAX_PRESIGN_EXPIRY_SECONDS`
@@ -2022,23 +2055,67 @@ refuses — so it is clamped here.
 const MAX_PRESIGN_EXPIRY_SECONDS: number
 ```
 
-#### `PRIVATE_ROUTES_METADATA_SUFFIX`
+#### `MAX_ARCHIVE_BYTES`
 
-Machine-metadata key suffix (after the configured prefix) recording the
-private addresses allocated for a project, so `destroy()` can release exactly
-the ones it created. See consequence 2 in the module description: a listing on
-the target app cannot tell you which network an address serves.
+Single-`PUT` ceiling: "With a single `PUT` operation, you can upload a single
+object up to 5 GB in size"
+(https://docs.aws.amazon.com/AmazonS3/latest/userguide/upload-objects.html).
+The sandbox uploads with one presigned PUT, so an archive above this cannot be
+stored and the capture refuses before spending the bandwidth.
 
 ```typescript
-const PRIVATE_ROUTES_METADATA_SUFFIX: 'privateRoutes'
+const MAX_ARCHIVE_BYTES: number
 ```
 
-#### `provider`
+#### `DEFAULT_TRANSFER_TIMEOUT_MS`
 
-The provider implementation.
+Default wall-clock budget for a capture or restore transfer, in ms.
 
 ```typescript
-const provider: SandboxProvider
+const DEFAULT_TRANSFER_TIMEOUT_MS: 900000
+```
+
+#### `DEFAULT_PRESIGN_EXPIRY_SECONDS`
+
+Default lifetime of a presigned capture/restore URL, in seconds.
+
+```typescript
+const DEFAULT_PRESIGN_EXPIRY_SECONDS: 3600
+```
+
+#### `LEASE_GRACE_MS`
+
+Extra time a restore lease counts as live beyond the transfer budget, covering
+the Machine boot and the API round trips that bracket the transfer itself.
+A lease older than `transferTimeoutMs + this` cannot belong to a live restore,
+because the restore's own exec is bounded by that budget.
+
+```typescript
+const LEASE_GRACE_MS: 120000
+```
+
+#### `EXIT_ARCHIVE_TOO_LARGE`
+
+Exit status the capture script uses when the archive is over the size ceiling.
+
+```typescript
+const EXIT_ARCHIVE_TOO_LARGE: 90
+```
+
+#### `EXIT_SETUID_SURVIVED`
+
+Exit status the restore script uses when a setuid/setgid file survived the sweep.
+
+```typescript
+const EXIT_SETUID_SURVIVED: 91
+```
+
+#### `EXIT_TAR_FAILED`
+
+Exit status the capture script uses when `tar` failed outright (as opposed to warning).
+
+```typescript
+const EXIT_TAR_FAILED: 92
 ```
 
 #### `TAR_CHANGED_MARKER`
@@ -2374,12 +2451,26 @@ Fly documents the Machines API at "1 request, per second, per action … with a
 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