@molecule/api-code-sandbox-flyio 1.0.1

package/dist/egress.js

@@ -0,0 +1,283 @@
+/**
+ * Fly network policies — the only egress restriction Fly.io exposes — and the
+ * pure logic behind the observation that proves one is actually in force.
+ *
+ * **What Fly actually offers.** 6PN custom private networks isolate apps from
+ * EACH OTHER ("Apps on separate 6PNs can never communicate unless explicitly
+ * configured to do so",
+ * https://fly.io/docs/networking/custom-private-networks/); they say nothing
+ * about reaching the public internet, which is a different question and the one
+ * `verifyEgress()` answers. The mechanism Fly documents for that is **network
+ * policies** (https://fly.io/docs/machines/guides-examples/network-policies/,
+ * announced at https://community.fly.io/t/new-feature-network-policies/19173):
+ * an app-scoped object with a `selector` and `allow` rules, where "Once you
+ * create a rule for a given direction, the default for that direction becomes
+ * drop."
+ *
+ * Three properties of that mechanism drive everything below, and every one of
+ * them is a limitation you cannot design around:
+ *
+ * 1. **Rules match protocol + port ONLY.** There is no host, IP or CIDR
+ *    matching, and (as of the announcement) no port ranges. A network policy
+ *    therefore CANNOT express a host allowlist. `allow tcp/443` permits a
+ *    sandbox to reach every host on the internet that listens on 443.
+ * 2. **They do not apply to Fly Proxy traffic** — stated in the docs and, in
+ *    the announcement, in capitals. Inbound preview traffic through the proxy
+ *    is unaffected by an ingress rule.
+ * 3. **They take effect at Machine boot.** Fly's own troubleshooting note:
+ *    "After creating or updating a policy, restart or redeploy the Machines for
+ *    changes to take effect." A policy applied to an app with an already-running
+ *    Machine does not retroactively cover it.
+ *
+ * The endpoints are documented in the guide and the announcement but are NOT in
+ * Fly's OpenAPI specification (https://docs.machines.dev/openapi.json — 68
+ * paths, none of them `network_policies`), so the request shape below is taken
+ * from those two documents verbatim and the LIST response shape, which neither
+ * document specifies, is parsed defensively by {@link extractPolicyId}.
+ *
+ * VERIFIED AGAINST A REAL FLY ORG, 2026-08-05 — the endpoints DO exist despite
+ * their absence from the spec:
+ *
+ *   GET  /apps/{app}/network_policies   -> 200 []
+ *   GET  /apps/{app}/network_policies/  -> 404 (trailing slash is NOT accepted)
+ *   POST /apps/{app}/network_policies   -> 400 {"error":"name is required"}
+ *
+ * The POST error is the useful one: it proves the route is real and validating,
+ * and that `name` is mandatory — which is why {@link DEFAULT_EGRESS_POLICY_NAME}
+ * is always sent.
+ *
+ * @module
+ */
+import { shellQuote } from './utilities.js';
+/** Default name of the egress policy this provider owns on each sandbox app. */
+export const DEFAULT_EGRESS_POLICY_NAME = 'molecule-sandbox-egress';
+/**
+ * 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.
+ */
+export const EGRESS_PROBE_EXIT_REACHED = 9;
+/** Probe exit status meaning every raw connection attempt was refused or timed out. */
+export const EGRESS_PROBE_EXIT_BLOCKED = 0;
+/**
+ * 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.
+ */
+export const DEFAULT_EGRESS_PROBE_TARGETS = '1.1.1.1:443,[2606:4700:4700::1111]:443';
+/** Matches a bare IPv4 literal. */
+const IPV4 = /^\d{1,3}(\.\d{1,3}){3}$/;
+/** Matches a bracketed IPv6 literal, e.g. `[2606:4700:4700::1111]`. */
+const IPV6_BRACKETED = /^\[[0-9a-fA-F:]+\]$/;
+/**
+ * Renders a target the way it is written in configuration, so an operator can
+ * paste it straight back.
+ * @param target - The parsed target.
+ * @returns `host:port`, with IPv6 hosts bracketed.
+ */
+export function formatEgressProbeTarget(target) {
+    const host = target.host.includes(':') ? `[${target.host}]` : target.host;
+    return `${host}:${target.port}`;
+}
+/**
+ * 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.
+ * @param 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".
+ */
+export function parseEgressProbeTargets(raw) {
+    const entries = Array.isArray(raw) ? raw : (raw ?? '').split(',');
+    const targets = [];
+    for (const entry of entries) {
+        const trimmed = entry.trim();
+        const index = trimmed.lastIndexOf(':');
+        if (index <= 0)
+            continue;
+        const host = trimmed.slice(0, index);
+        const port = Number(trimmed.slice(index + 1));
+        if (!Number.isInteger(port) || port < 1 || port > 65535)
+            continue;
+        if (IPV4.test(host))
+            targets.push({ host, port });
+        else if (IPV6_BRACKETED.test(host))
+            targets.push({ host: host.slice(1, -1), port });
+    }
+    return targets;
+}
+/**
+ * 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.
+ * @param raw - Comma-separated `protocol:port` pairs, e.g. `tcp:3128,udp:53`.
+ *   A bare port is treated as TCP.
+ * @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".
+ * @throws {Error} When an entry is present but unparseable — silently dropping a
+ *   port from a security control would produce a policy the operator never wrote.
+ */
+export function parseEgressAllowedPorts(raw) {
+    const entries = (raw ?? '')
+        .split(',')
+        .map((entry) => entry.trim())
+        .filter(Boolean);
+    if (entries.length === 0)
+        return undefined;
+    const ports = [];
+    for (const entry of entries) {
+        const [left, right] = entry.includes(':') ? entry.split(':', 2) : ['tcp', entry];
+        const protocol = left.toLowerCase();
+        const port = Number(right);
+        if ((protocol !== 'tcp' && protocol !== 'udp') ||
+            !Number.isInteger(port) ||
+            port < 1 ||
+            port > 65535) {
+            throw new Error(`Invalid Fly egress port "${entry}" — expected "tcp:443", "udp:53" or a bare port number.`);
+        }
+        ports.push({ protocol, port });
+    }
+    return ports;
+}
+/**
+ * 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.
+ * @param targets - Literal targets to attempt.
+ * @param timeoutMs - Per-connection timeout.
+ * @returns A `sh`-safe command string.
+ */
+export function buildEgressProbeCommand(targets, timeoutMs) {
+    const script = `const net=require('net');const ts=${JSON.stringify(targets)};` +
+        `if(!ts.length)process.exit(1);` +
+        `let open=0,left=ts.length;` +
+        `const done=()=>{if(--left===0)process.exit(open>0?${EGRESS_PROBE_EXIT_REACHED}:${EGRESS_PROBE_EXIT_BLOCKED})};` +
+        `for(const t of ts){const s=net.connect({host:t.host,port:t.port});` +
+        `s.setTimeout(${timeoutMs});` +
+        `s.on('connect',()=>{open++;s.destroy();done()});` +
+        `s.on('timeout',()=>{s.destroy();done()});` +
+        `s.on('error',()=>done())}`;
+    return `node -e ${shellQuote(script)}`;
+}
+/**
+ * Describes the policy this provider applied, for the verdict message.
+ * @param policyPorts - Allowed ports, or `undefined` when no policy is applied.
+ * @returns A phrase naming the mechanism that was (or was not) in place.
+ */
+function describePolicy(policyPorts) {
+    if (!policyPorts)
+        return 'no Fly network policy applied by this provider';
+    const ports = policyPorts.map((port) => `${port.protocol}/${port.port}`).join(', ');
+    return `a Fly network policy allowing egress on ${ports}`;
+}
+/**
+ * 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:
+ *
+ * | 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`.
+ * @param exitCode - The probe process's exit status.
+ * @param context - App, targets and the policy this provider applied.
+ * @returns The verdict.
+ */
+export function verdictForProbeExit(exitCode, context) {
+    const targets = context.targets.map(formatEgressProbeTarget).join(', ');
+    const policy = describePolicy(context.policyPorts);
+    if (exitCode === EGRESS_PROBE_EXIT_REACHED) {
+        return {
+            state: 'open',
+            detail: `A Machine in Fly app "${context.app}" (${policy}) opened a raw TCP connection to ` +
+                `${targets} — sandbox egress is NOT filtered.`,
+            remediation: context.policyPorts
+                ? 'The policy that is in force still permits the probe’s ports. A Fly network policy ' +
+                    'matches protocol and port ONLY — it has no host or CIDR matching — so it cannot be a ' +
+                    'host allowlist. Allow only the port of an egress proxy you control and route sandbox ' +
+                    'traffic through it. See https://fly.io/docs/machines/guides-examples/network-policies/.'
+                : 'Set config.egressAllowedPorts (or FLY_SANDBOX_EGRESS_ALLOWED_PORTS, e.g. ' +
+                    '"tcp:3128,udp:53") so this provider applies a Fly network policy to every sandbox app. ' +
+                    'Fly drops everything else in that direction once one egress rule exists. See ' +
+                    'https://fly.io/docs/machines/guides-examples/network-policies/.',
+        };
+    }
+    if (exitCode === EGRESS_PROBE_EXIT_BLOCKED) {
+        return {
+            state: 'filtered',
+            detail: `Raw TCP connects to ${targets} from a Machine in Fly app "${context.app}" ` +
+                `(${policy}) were refused or timed out.`,
+        };
+    }
+    return {
+        state: 'inconclusive',
+        detail: `The egress probe in Fly app "${context.app}" exited ${exitCode}, which is neither ` +
+            `${EGRESS_PROBE_EXIT_BLOCKED} (every attempt blocked) nor ${EGRESS_PROBE_EXIT_REACHED} ` +
+            '(a target was reached) — it did not complete its connection attempts, so nothing was ' +
+            'observed about egress.',
+        remediation: 'Check that the probe image can run `node -e` (override it with config.egressProbeImage), ' +
+            'and that the Fly API token may create Machines in the probe app.',
+    };
+}
+/**
+ * Narrows an unknown value to a plain object.
+ * @param value - The value to test.
+ * @returns `true` when it is a non-null, non-array object.
+ */
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * Finds an existing policy's id in a LIST response, so the next write updates it
+ * instead of stacking duplicates.
+ *
+ * Neither the guide nor the announcement specifies what
+ * `GET /v1/apps/{app}/network_policies/` returns, and the endpoint is absent
+ * from Fly's OpenAPI specification — so this accepts a bare array or an object
+ * wrapping one under any of the plausible keys, and returns `undefined` for
+ * anything it does not recognize. `undefined` is safe: the caller then POSTs
+ * without an `id`, which still applies the policy.
+ * @param response - The raw parsed LIST response.
+ * @param name - The policy name to match.
+ * @returns The matching policy's id, or `undefined`.
+ */
+export function extractPolicyId(response, name) {
+    const list = Array.isArray(response)
+        ? response
+        : isRecord(response)
+            ? [response.policies, response.network_policies, response.data].find(Array.isArray)
+            : undefined;
+    if (!Array.isArray(list))
+        return undefined;
+    for (const entry of list) {
+        if (isRecord(entry) && entry.name === name && typeof entry.id === 'string' && entry.id) {
+            return entry.id;
+        }
+    }
+    return undefined;
+}

package/dist/exec.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Command execution on a Fly Machine, including the detach-and-poll path that
+ * works around Fly's 60-second exec ceiling.
+ *
+ * **The constraint.** `POST /v1/apps/{app}/machines/{id}/exec` is a
+ * request/response call whose `timeout` field is capped by Fly at 60 seconds —
+ * a longer value is rejected outright with
+ * `{"error":"timeout must not exceed 60 seconds"}`
+ * (https://community.fly.io/t/extending-timeout-of-execute-command-machines-api-endpoint/26074).
+ * A sandbox routinely runs commands far past that (`npm install`, a production
+ * build), so a provider that only ever calls exec directly would fail every one
+ * of them. That is not an acceptable gap — it is the common case.
+ *
+ * **The mapping.** Commands whose budget fits inside the ceiling run directly.
+ * Anything longer is written to a script file inside the Machine, launched
+ * detached with its stdout/stderr redirected to files and its exit status
+ * written to a third file, and then POLLED with short direct execs until the
+ * status file appears. The caller sees one `ExecResult` either way; the only
+ * observable difference is that output arrives at the end rather than streaming
+ * (which the core `exec` contract does not offer anyway).
+ *
+ * @module
+ */
+import type { ExecOptions, ExecResult } from '@molecule/api-code-sandbox';
+import type { FlyExecResponse } from './types.js';
+/**
+ * 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.
+ */
+export declare const FLY_EXEC_MAX_TIMEOUT_SECONDS = 60;
+/**
+ * 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.
+ */
+export declare const DIRECT_EXEC_BUDGET_SECONDS = 55;
+/**
+ * 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.
+ */
+export declare const MAX_CAPTURED_OUTPUT_BYTES: number;
+/**
+ * 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".
+ */
+export declare const INDETERMINATE_EXIT_CODE = -1;
+/** Runs one exec call against a Machine. Injected so this module stays transport-free. */
+export type RawExec = (command: string[], timeoutSeconds: number) => Promise<FlyExecResponse>;
+/**
+ * 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`.
+ * @param response - The raw Fly exec response.
+ * @returns The normalized result.
+ */
+export declare function toExecResult(response: FlyExecResponse): ExecResult;
+/**
+ * Builds the shell script body for a command: change directory, export the
+ * requested environment, then run the command.
+ * @param command - The shell command to run.
+ * @param opts - Optional cwd and environment.
+ * @param defaultCwd - Directory used when `opts.cwd` is unset.
+ * @returns The script source, newline separated.
+ */
+export declare function buildScript(command: string, opts: ExecOptions | undefined, defaultCwd: string): string;
+/**
+ * Executes a command on a Machine, choosing the direct or detached strategy
+ * based on the caller's time budget.
+ *
+ * @param rawExec - Transport callback issuing one Fly exec call.
+ * @param command - The shell command to run.
+ * @param opts - Core exec options (cwd, env, timeout in ms).
+ * @param defaultCwd - Working directory used when `opts.cwd` is unset.
+ * @returns The command's stdout, stderr and exit code.
+ * @throws {Error} When the command is too large to launch (see
+ *   {@link MAX_SCRIPT_BASE64_BYTES}), or when the transport itself fails.
+ */
+export declare function execCommand(rawExec: RawExec, command: string, opts: ExecOptions | undefined, defaultCwd: string): Promise<ExecResult>;
+//# sourceMappingURL=exec.d.ts.map

package/dist/exec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"exec.d.ts","sourceRoot":"","sources":["../src/exec.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAA;AAGzE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAKjD;;;;GAIG;AACH,eAAO,MAAM,4BAA4B,KAAK,CAAA;AAE9C;;;;GAIG;AACH,eAAO,MAAM,0BAA0B,KAAK,CAAA;AAW5C;;;;GAIG;AACH,eAAO,MAAM,yBAAyB,QAAkB,CAAA;AAWxD;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,KAAK,CAAA;AAEzC,0FAA0F;AAC1F,MAAM,MAAM,OAAO,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,cAAc,EAAE,MAAM,KAAK,OAAO,CAAC,eAAe,CAAC,CAAA;AAE7F;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,eAAe,GAAG,UAAU,CAYlE;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CACzB,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,WAAW,GAAG,SAAS,EAC7B,UAAU,EAAE,MAAM,GACjB,MAAM,CAGR;AAaD;;;;;;;;;;;GAWG;AACH,wBAAsB,WAAW,CAC/B,OAAO,EAAE,OAAO,EAChB,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,WAAW,GAAG,SAAS,EAC7B,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,UAAU,CAAC,CAUrB"}

package/dist/exec.js

@@ -0,0 +1,215 @@
+/**
+ * Command execution on a Fly Machine, including the detach-and-poll path that
+ * works around Fly's 60-second exec ceiling.
+ *
+ * **The constraint.** `POST /v1/apps/{app}/machines/{id}/exec` is a
+ * request/response call whose `timeout` field is capped by Fly at 60 seconds —
+ * a longer value is rejected outright with
+ * `{"error":"timeout must not exceed 60 seconds"}`
+ * (https://community.fly.io/t/extending-timeout-of-execute-command-machines-api-endpoint/26074).
+ * A sandbox routinely runs commands far past that (`npm install`, a production
+ * build), so a provider that only ever calls exec directly would fail every one
+ * of them. That is not an acceptable gap — it is the common case.
+ *
+ * **The mapping.** Commands whose budget fits inside the ceiling run directly.
+ * Anything longer is written to a script file inside the Machine, launched
+ * detached with its stdout/stderr redirected to files and its exit status
+ * written to a third file, and then POLLED with short direct execs until the
+ * status file appears. The caller sees one `ExecResult` either way; the only
+ * observable difference is that output arrives at the end rather than streaming
+ * (which the core `exec` contract does not offer anyway).
+ *
+ * @module
+ */
+import { getLogger } from '@molecule/api-bond';
+import { t } from '@molecule/api-i18n';
+import { renderEnvExports, shellQuote } from './utilities.js';
+const logger = getLogger();
+/**
+ * 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.
+ */
+export const FLY_EXEC_MAX_TIMEOUT_SECONDS = 60;
+/**
+ * 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.
+ */
+export const DIRECT_EXEC_BUDGET_SECONDS = 55;
+/** Timeout applied to the short bookkeeping execs (launch, poll, collect), in seconds. */
+const CONTROL_EXEC_TIMEOUT_SECONDS = 30;
+/** Interval between status-file polls for a detached command, in ms. */
+const POLL_INTERVAL_MS = 2000;
+/** Default wall-clock budget for a command with no `opts.timeout`, in ms. */
+const DEFAULT_TIMEOUT_MS = 600_000;
+/**
+ * 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.
+ */
+export const MAX_CAPTURED_OUTPUT_BYTES = 5 * 1024 * 1024;
+/**
+ * Cap on the base64-encoded launcher script. `sh -c` receives it as a single
+ * argument, which Linux limits to MAX_ARG_STRLEN (128 KB).
+ */
+const MAX_SCRIPT_BASE64_BYTES = 60_000;
+/** Directory inside the Machine holding detached-command bookkeeping files. */
+const WORK_DIR = '/tmp/.mol-exec';
+/**
+ * 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".
+ */
+export const INDETERMINATE_EXIT_CODE = -1;
+/**
+ * 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`.
+ * @param response - The raw Fly exec response.
+ * @returns The normalized result.
+ */
+export function toExecResult(response) {
+    const exitCode = typeof response.exit_code === 'number'
+        ? response.exit_code
+        : typeof response.exit_signal === 'number' && response.exit_signal > 0
+            ? 128 + response.exit_signal
+            : INDETERMINATE_EXIT_CODE;
+    return {
+        stdout: response.stdout ?? '',
+        stderr: response.stderr ?? '',
+        exitCode,
+    };
+}
+/**
+ * Builds the shell script body for a command: change directory, export the
+ * requested environment, then run the command.
+ * @param command - The shell command to run.
+ * @param opts - Optional cwd and environment.
+ * @param defaultCwd - Directory used when `opts.cwd` is unset.
+ * @returns The script source, newline separated.
+ */
+export function buildScript(command, opts, defaultCwd) {
+    const cwd = opts?.cwd ?? defaultCwd;
+    return [`cd ${shellQuote(cwd)} || exit 127`, ...renderEnvExports(opts?.env), command].join('\n');
+}
+/**
+ * Generates an id for one detached run's bookkeeping files. Hex only, so it is
+ * always safe to interpolate into a shell command unquoted.
+ * @returns A 16-character hex id.
+ */
+function newRunId() {
+    let id = '';
+    while (id.length < 16)
+        id += Math.floor(Math.random() * 0xffffffff).toString(16);
+    return id.slice(0, 16);
+}
+/**
+ * Executes a command on a Machine, choosing the direct or detached strategy
+ * based on the caller's time budget.
+ *
+ * @param rawExec - Transport callback issuing one Fly exec call.
+ * @param command - The shell command to run.
+ * @param opts - Core exec options (cwd, env, timeout in ms).
+ * @param defaultCwd - Working directory used when `opts.cwd` is unset.
+ * @returns The command's stdout, stderr and exit code.
+ * @throws {Error} When the command is too large to launch (see
+ *   {@link MAX_SCRIPT_BASE64_BYTES}), or when the transport itself fails.
+ */
+export async function execCommand(rawExec, command, opts, defaultCwd) {
+    const budgetMs = opts?.timeout ?? DEFAULT_TIMEOUT_MS;
+    const script = buildScript(command, opts, defaultCwd);
+    if (budgetMs <= DIRECT_EXEC_BUDGET_SECONDS * 1000) {
+        const seconds = Math.max(1, Math.min(Math.ceil(budgetMs / 1000), FLY_EXEC_MAX_TIMEOUT_SECONDS));
+        return toExecResult(await rawExec(['sh', '-c', script], seconds));
+    }
+    return await execDetached(rawExec, script, budgetMs);
+}
+/**
+ * Runs a script detached inside the Machine and polls for its completion.
+ *
+ * The script is delivered base64-encoded so that no amount of quoting in the
+ * caller's command can break out of the launcher; the launcher itself only ever
+ * interpolates a hex run id.
+ * @param rawExec - Transport callback issuing one Fly exec call.
+ * @param script - The script body to run.
+ * @param budgetMs - Wall-clock budget before the result is reported indeterminate.
+ * @returns The command's captured output and exit code.
+ * @throws {Error} When the encoded script exceeds the single-argument limit, or
+ *   when the launcher itself fails to start.
+ */
+async function execDetached(rawExec, script, budgetMs) {
+    const runId = newRunId();
+    const base64 = Buffer.from(script, 'utf8').toString('base64');
+    if (base64.length > MAX_SCRIPT_BASE64_BYTES) {
+        throw new Error(t('codeSandbox.flyio.error.commandTooLarge', { limit: String(MAX_SCRIPT_BASE64_BYTES) }, {
+            defaultValue: `Command is too large to launch on a Fly Machine (encoded ${base64.length} bytes, limit ${MAX_SCRIPT_BASE64_BYTES}). ` +
+                'Write it to a file with writeFile() and exec that file instead.',
+        }));
+    }
+    const scriptPath = `${WORK_DIR}/${runId}.sh`;
+    const outPath = `${WORK_DIR}/${runId}.out`;
+    const errPath = `${WORK_DIR}/${runId}.err`;
+    const rcPath = `${WORK_DIR}/${runId}.rc`;
+    // The `&` must apply to the nohup line ALONE. In POSIX sh, `a && b &`
+    // backgrounds the whole AND-list, which would race the script write against
+    // the launch, so these are separate statements rather than one chain.
+    const launcher = [
+        `mkdir -p ${WORK_DIR} || exit 1`,
+        `printf %s ${shellQuote(base64)} | base64 -d > ${scriptPath} || exit 1`,
+        `nohup sh -c 'sh ${scriptPath} > ${outPath} 2> ${errPath}; printf %s "$?" > ${rcPath}' > /dev/null 2>&1 < /dev/null &`,
+        `printf %s ${runId}`,
+    ].join('\n');
+    const launch = toExecResult(await rawExec(['sh', '-c', launcher], CONTROL_EXEC_TIMEOUT_SECONDS));
+    if (launch.exitCode !== 0) {
+        throw new Error(t('codeSandbox.flyio.error.launchFailed', { error: launch.stderr || launch.stdout }, {
+            defaultValue: `Failed to launch detached command on Fly Machine: ${launch.stderr || launch.stdout}`,
+        }));
+    }
+    const deadline = Date.now() + budgetMs;
+    let rc = null;
+    while (Date.now() < deadline) {
+        await new Promise((resolve) => setTimeout(resolve, POLL_INTERVAL_MS));
+        const poll = toExecResult(await rawExec(['sh', '-c', `cat ${rcPath} 2>/dev/null`], Math.max(1, Math.min(CONTROL_EXEC_TIMEOUT_SECONDS, FLY_EXEC_MAX_TIMEOUT_SECONDS))));
+        const value = poll.stdout.trim();
+        if (value) {
+            rc = value;
+            break;
+        }
+    }
+    const collect = toExecResult(await rawExec([
+        'sh',
+        '-c',
+        `head -c ${MAX_CAPTURED_OUTPUT_BYTES} ${outPath} 2>/dev/null; printf '\\n__MOL_STDERR__\\n'; head -c ${MAX_CAPTURED_OUTPUT_BYTES} ${errPath} 2>/dev/null`,
+    ], CONTROL_EXEC_TIMEOUT_SECONDS));
+    const separator = collect.stdout.indexOf('\n__MOL_STDERR__\n');
+    const stdout = separator === -1 ? collect.stdout : collect.stdout.slice(0, separator);
+    const stderr = separator === -1 ? '' : collect.stdout.slice(separator + '\n__MOL_STDERR__\n'.length);
+    if (rc === null) {
+        // Still running at the deadline. The bookkeeping files are deliberately NOT
+        // removed — the process owns them and will keep writing.
+        logger.warn('Fly detached command exceeded its budget and is still running', {
+            runId,
+            budgetMs,
+        });
+        return { stdout, stderr, exitCode: INDETERMINATE_EXIT_CODE };
+    }
+    try {
+        await rawExec(['sh', '-c', `rm -f ${WORK_DIR}/${runId}.*`], CONTROL_EXEC_TIMEOUT_SECONDS);
+    }
+    catch (error) {
+        // Best-effort cleanup of four files under /tmp. The command itself already
+        // completed and its result is in hand; failing the call over leftover
+        // scratch files would turn a success into an error.
+        logger.debug('Failed to clean up Fly detached command scratch files', { runId, error });
+    }
+    const parsed = Number.parseInt(rc, 10);
+    return {
+        stdout,
+        stderr,
+        exitCode: Number.isFinite(parsed) ? parsed : INDETERMINATE_EXIT_CODE,
+    };
+}