@molecule/api-code-sandbox-docker 1.0.1 → 1.1.0

package/dist/egress.js

@@ -0,0 +1,424 @@
+/**
+ * Observe whether a Docker host actually denies sandbox egress.
+ *
+ * TWO LEGS, AND BOTH ARE REQUIRED. This is the part that is easy to get wrong and
+ * was in fact got wrong: an earlier version of this check implemented only leg 1
+ * and therefore reported `filtered` on a host where sandboxes could still reach
+ * SSH, Redis, the monitoring stack, the MinIO admin console and the API itself.
+ *
+ * - **Leg 1 — DOCKER-USER (outbound to the internet).** A container on the sandbox
+ *   network tries to open raw TCP to literal public IPs. Traffic leaving the
+ *   bridge for the outside world traverses the `DOCKER-USER` chain.
+ * - **Leg 2 — INPUT (host-bound).** Packets a sandbox sends to the HOST GATEWAY
+ *   are delivered locally and **never traverse `DOCKER-USER`** — they hit the
+ *   `INPUT` chain instead. The two diverge in practice: a `ufw reload` rebuilds
+ *   INPUT while leaving DOCKER-USER intact, so leg 1 alone still passes while
+ *   every host-bound service is exposed.
+ *
+ * Leg 2's difficulty is that a firewall REJECT and "nothing is listening" are the
+ * same `ECONNREFUSED` to a client, so dialling an arbitrary closed port proves
+ * nothing. It therefore opens a REAL listener in the host network namespace on an
+ * ephemeral, deliberately non-allowlisted port and has a sandbox-network peer dial
+ * it. Both ends are ours, so the answer is unambiguous.
+ *
+ * Every failure mode collapses to `inconclusive` — never `filtered`. "I could not
+ * look" must never be reported as "I looked and it is safe"; that conflation is
+ * the original failure this whole mechanism exists to prevent.
+ *
+ * @module
+ */
+import net from 'net';
+/** Exit codes the probe programs use to report what they observed. */
+const EXIT_BLOCKED = 0;
+const EXIT_OPEN = 9;
+const EXIT_LISTENER_ACCEPTED = 10;
+const EXIT_LISTENER_IDLE = 11;
+const LISTENER_READY_MARKER = 'MOL_LISTENER_READY';
+const PROBE_NAME_PREFIX = 'mol-egress-probe-';
+/** Ephemeral range the host-port leg binds in. */
+const HOST_PROBE_PORT_MIN = 41_000;
+const HOST_PROBE_PORT_MAX = 45_000;
+const REMEDIATION = 'Apply the host default-deny for the sandbox subnet (scripts/provision-egress-firewall.sh), then re-check.';
+/**
+ * Parse an integer env var, tolerating garbage.
+ *
+ * `Math.max(min, parseInt(x))` returns NaN when x is malformed — NaN loses every
+ * comparison, so a typo silently produced a NaN timeout rather than the default.
+ *
+ * @param raw - Raw env value.
+ * @param fallback - Value to use when absent or unparseable.
+ * @param min - Lower clamp.
+ * @param max - Upper clamp.
+ * @returns A usable integer.
+ */
+function intEnv(raw, fallback, min, max) {
+    const parsed = Number.parseInt(raw ?? '', 10);
+    const value = Number.isFinite(parsed) ? parsed : fallback;
+    return Math.min(max, Math.max(min, value));
+}
+/**
+ * Literal `ip:port` destinations for leg 1.
+ *
+ * TWO by default, not one: a blocked verdict is inferred from failure, so a single
+ * unreachable target is indistinguishable from a working firewall. Requiring every
+ * target to fail makes that coincidence need two independent outages.
+ *
+ * Hostnames are REJECTED rather than resolved — a hostname would make DNS the
+ * thing under test, and a blocked resolver would read as `filtered` on a wide-open
+ * host.
+ *
+ * @returns Validated targets.
+ */
+function probeTargets() {
+    const raw = process.env.SANDBOX_EGRESS_PROBE_TARGETS ?? '1.1.1.1:443,8.8.8.8:443';
+    const targets = [];
+    for (const entry of raw.split(',')) {
+        const match = /^\s*(\d{1,3}(?:\.\d{1,3}){3}):(\d{1,5})\s*$/.exec(entry);
+        if (!match)
+            continue;
+        const port = Number(match[2]);
+        if (net.isIPv4(match[1]) && port > 0 && port < 65_536)
+            targets.push({ host: match[1], port });
+    }
+    return targets;
+}
+/**
+ * Host-gateway ports the firewall intentionally allows, mirroring
+ * `provision-egress-firewall.sh`. Read from the same env vars that script reads,
+ * so an operator who moves a port does not silently turn leg 2 into a false pass.
+ *
+ * @returns Ports a sandbox is expected to reach on the host gateway.
+ */
+function allowedHostPorts() {
+    const raw = process.env.SANDBOX_ALLOWED_HOST_PORTS ??
+        [
+            process.env.SANDBOX_EGRESS_PROXY_PORT ?? '3129',
+            process.env.SANDBOX_DB_PORT ?? '5432',
+            process.env.MINIO_PORT ?? '9000',
+        ].join(',');
+    const ports = new Set();
+    for (const entry of raw.split(',')) {
+        const port = Number(entry.trim());
+        if (Number.isInteger(port) && port > 0 && port < 65_536)
+            ports.add(port);
+    }
+    return ports;
+}
+/**
+ * The client program: raw `net.connect` to each target.
+ *
+ * Raw sockets, never `fetch` — proxy env is blanked AND a raw connect ignores it
+ * regardless, so this exercises the DIRECT path the proxy does not cover and only
+ * the firewall stops.
+ *
+ * @param targets - Destinations to attempt.
+ * @param timeoutMs - Per-connection timeout.
+ * @returns Program source.
+ */
+export function buildProbeScript(targets, timeoutMs) {
+    return (`const net=require('net');const ts=${JSON.stringify(targets)};let open=0,left=ts.length;` +
+        `const done=()=>{if(--left===0)process.exit(open>0?${EXIT_OPEN}:${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())}`);
+}
+/**
+ * The host-netns listener program for leg 2.
+ *
+ * @param port - Port to bind.
+ * @param timeoutMs - How long to wait for a connection.
+ * @returns Program source.
+ */
+export function buildListenerScript(port, timeoutMs) {
+    return [
+        "const net=require('net');",
+        'let settled=false;',
+        'const exit=(c)=>{if(settled)return;settled=true;process.exit(c);};',
+        `const s=net.createServer((c)=>{c.destroy();exit(${EXIT_LISTENER_ACCEPTED});});`,
+        "s.on('error',()=>exit(40));",
+        `s.listen(${port},'0.0.0.0',()=>{console.log('${LISTENER_READY_MARKER}');});`,
+        `setTimeout(()=>exit(${EXIT_LISTENER_IDLE}),${timeoutMs});`,
+    ].join('');
+}
+/** Sleep, for the readiness poll. */
+const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/**
+ * Create and start a hardened throwaway probe container.
+ *
+ * The name is PRE-CHOSEN, not read back from the create response: a create that
+ * times out client-side may still have landed daemon-side, and without a known
+ * name that container is unreachable and leaks.
+ *
+ * @param ctx - Probe context.
+ * @param name - Pre-chosen container name.
+ * @param script - Program to run.
+ * @param hostConfig - Extra HostConfig (network mode).
+ * @returns The container id, or a failure reason.
+ */
+async function startProbeContainer(ctx, name, script, hostConfig) {
+    try {
+        const created = (await ctx.request(`/containers/create?name=${name}`, 'POST', {
+            Image: ctx.baseImage,
+            Cmd: ['node', '-e', script],
+            // Blank the proxy env the sandbox image bakes in, plus NODE_OPTIONS —
+            // its --max-old-space-size fights the tiny memory cap below.
+            Env: [
+                'HTTP_PROXY=',
+                'HTTPS_PROXY=',
+                'http_proxy=',
+                'https_proxy=',
+                'NO_PROXY=',
+                'no_proxy=',
+                'NODE_USE_ENV_PROXY=',
+                'NODE_OPTIONS=',
+            ],
+            Labels: { [`${ctx.labelPrefix}.egress-probe`]: 'true' },
+            // Raw (non-multiplexed) logs, so the readiness marker reads back without
+            // decoding Docker's stream framing.
+            Tty: true,
+            HostConfig: {
+                // AutoRemove OFF deliberately: it races /wait, and the exit code matters
+                // more than the convenience. Callers remove unconditionally.
+                AutoRemove: false,
+                RestartPolicy: { Name: '' },
+                Memory: 128 * 1024 * 1024,
+                MemorySwap: 128 * 1024 * 1024,
+                NanoCPUs: 250_000_000,
+                PidsLimit: 32,
+                CapDrop: ['ALL'],
+                SecurityOpt: ['no-new-privileges'],
+                ReadonlyRootfs: true,
+                Tmpfs: { '/tmp': 'rw,noexec,nosuid,size=8m' },
+                ...hostConfig,
+            },
+        }));
+        await ctx.request(`/containers/${created.Id}/start`, 'POST');
+        return { id: created.Id };
+    }
+    catch (error) {
+        return { failure: error instanceof Error ? error.message : String(error) };
+    }
+}
+/** Remove a probe container by id or pre-chosen name; never throws. */
+async function removeProbeContainer(ctx, ref) {
+    await ctx.request(`/containers/${ref}?force=true`, 'DELETE').catch((error) => {
+        ctx.warn?.('Failed to remove egress probe container', { ref, error });
+    });
+}
+/** Wait for a container to exit and return its status code. */
+async function waitForExit(ctx, id, timeoutMs) {
+    try {
+        const waited = (await ctx.request(`/containers/${id}/wait`, 'POST', undefined, timeoutMs));
+        return typeof waited?.StatusCode === 'number' ? waited.StatusCode : null;
+    }
+    catch (_error) {
+        return null;
+    }
+}
+/**
+ * Resolve the host-gateway IP, preferring the daemon's own answer and falling
+ * back to the `bridge` network's gateway — `docker info` omits `HostGatewayIP`
+ * on some daemon versions.
+ *
+ * @param ctx - Probe context.
+ * @returns The gateway IP, or null when undiscoverable.
+ */
+async function resolveHostGatewayIp(ctx) {
+    try {
+        const info = (await ctx.request('/info'));
+        if (info?.HostGatewayIP && net.isIP(info.HostGatewayIP))
+            return info.HostGatewayIP;
+    }
+    catch (_error) {
+        // Fall through to the bridge lookup.
+    }
+    try {
+        const bridge = (await ctx.request('/networks/bridge'));
+        for (const entry of bridge?.IPAM?.Config ?? []) {
+            if (entry.Gateway && net.isIP(entry.Gateway))
+                return entry.Gateway;
+        }
+    }
+    catch (_error) {
+        // Reported as inconclusive by the caller.
+    }
+    return null;
+}
+/**
+ * Leg 2 — prove the INPUT chain denies sandbox→host traffic.
+ *
+ * @param ctx - Probe context.
+ * @param timeoutMs - Per-connection timeout.
+ * @returns What was observed on the locally-delivered path.
+ */
+async function probeHostPort(ctx, timeoutMs) {
+    const gateway = await resolveHostGatewayIp(ctx);
+    if (!gateway) {
+        return {
+            result: 'inconclusive',
+            detail: 'could not determine the host-gateway IP, so the INPUT-chain deny (host-bound ports: ' +
+                `SSH, Redis, monitoring, the MinIO console, this API) could not be verified. ${REMEDIATION}`,
+        };
+    }
+    const allowed = allowedHostPorts();
+    let port = 0;
+    for (let attempt = 0; attempt < 8 && port === 0; attempt++) {
+        const candidate = HOST_PROBE_PORT_MIN + Math.floor(Math.random() * (HOST_PROBE_PORT_MAX - HOST_PROBE_PORT_MIN));
+        if (!allowed.has(candidate))
+            port = candidate;
+    }
+    if (port === 0) {
+        return {
+            result: 'inconclusive',
+            detail: 'every candidate port collided with SANDBOX_ALLOWED_HOST_PORTS',
+        };
+    }
+    const listenerName = `${PROBE_NAME_PREFIX}l-${Math.random().toString(36).slice(2, 12)}`;
+    const clientName = `${PROBE_NAME_PREFIX}c-${Math.random().toString(36).slice(2, 12)}`;
+    try {
+        // The listener must live in the HOST network namespace — the only way to bind
+        // a port a sandbox reaches via the gateway, container or not.
+        const listener = await startProbeContainer(ctx, listenerName, buildListenerScript(port, timeoutMs + 5_000), { NetworkMode: 'host' });
+        if ('failure' in listener) {
+            return {
+                result: 'inconclusive',
+                detail: `host listener could not start: ${listener.failure} (INPUT-chain deny unverified)`,
+            };
+        }
+        // Wait for the bind. Without this a fast client races the listener and
+        // reports a false `blocked`.
+        const readyBudget = intEnv(process.env.SANDBOX_EGRESS_LISTENER_READY_MS, 5_000, 100, 30_000);
+        let ready = false;
+        for (let waited = 0; waited < readyBudget && !ready; waited += 100) {
+            const logs = await ctx
+                .request(`/containers/${listener.id}/logs?stdout=1&stderr=1`)
+                .catch(() => '');
+            if (String(logs).includes(LISTENER_READY_MARKER)) {
+                ready = true;
+                break;
+            }
+            await delay(100);
+        }
+        if (!ready) {
+            return {
+                result: 'inconclusive',
+                detail: `listener on ${gateway}:${port} never reported ready (INPUT-chain deny unverified)`,
+            };
+        }
+        const client = await startProbeContainer(ctx, clientName, buildProbeScript([{ host: gateway, port }], timeoutMs), { NetworkMode: ctx.network });
+        if ('failure' in client) {
+            return {
+                result: 'inconclusive',
+                detail: `host-port client could not start: ${client.failure} (INPUT-chain deny unverified)`,
+            };
+        }
+        const code = await waitForExit(ctx, client.id, timeoutMs + 10_000);
+        if (code === EXIT_OPEN) {
+            return {
+                result: 'reachable',
+                detail: `a container on "${ctx.network}" opened TCP to the host at ${gateway}:${port}, which is ` +
+                    'NOT an allowed host port. The INPUT-chain deny is not in effect, so sandboxes can ' +
+                    `reach host-bound services (SSH, Redis, monitoring, the MinIO console, this API). ${REMEDIATION}`,
+            };
+        }
+        if (code === EXIT_BLOCKED) {
+            return { result: 'blocked', detail: `host ${gateway}:${port} refused (INPUT deny verified)` };
+        }
+        return {
+            result: 'inconclusive',
+            detail: `host-port probe exited ${String(code)} (INPUT-chain deny unverified)`,
+        };
+    }
+    catch (error) {
+        return {
+            result: 'inconclusive',
+            detail: error instanceof Error ? error.message : String(error),
+        };
+    }
+    finally {
+        await removeProbeContainer(ctx, listenerName);
+        await removeProbeContainer(ctx, clientName);
+    }
+}
+/**
+ * Run BOTH legs and combine them into one verdict.
+ *
+ * A `filtered` verdict requires both legs to be denied. Either leg observing a
+ * successful connection is conclusive `open`; anything that could not be observed
+ * is `inconclusive`.
+ *
+ * @param ctx - Probe context.
+ * @returns The combined verdict.
+ */
+export async function verifyDockerEgress(ctx) {
+    const targets = probeTargets();
+    if (targets.length === 0) {
+        return {
+            state: 'inconclusive',
+            detail: 'No valid literal ip:port probe targets configured.',
+            remediation: 'Set SANDBOX_EGRESS_PROBE_TARGETS to comma-separated ip:port values.',
+        };
+    }
+    const timeoutMs = intEnv(process.env.SANDBOX_EGRESS_PROBE_TIMEOUT_MS, 3_000, 500, 15_000);
+    // ── Leg 1: DOCKER-USER / outbound ──────────────────────────────────────────
+    const outboundName = `${PROBE_NAME_PREFIX}o-${Math.random().toString(36).slice(2, 12)}`;
+    let outbound;
+    try {
+        const started = await startProbeContainer(ctx, outboundName, buildProbeScript(targets, timeoutMs), { NetworkMode: ctx.network });
+        if ('failure' in started) {
+            outbound = {
+                result: 'inconclusive',
+                detail: `outbound probe could not run: ${started.failure}`,
+            };
+        }
+        else {
+            const code = await waitForExit(ctx, started.id, timeoutMs * targets.length + 10_000);
+            outbound =
+                code === EXIT_OPEN
+                    ? {
+                        result: 'reachable',
+                        detail: `a container on "${ctx.network}" reached ${targets
+                            .map((t) => `${t.host}:${t.port}`)
+                            .join(' or ')} directly — outbound egress is NOT filtered. ${REMEDIATION}`,
+                    }
+                    : code === EXIT_BLOCKED
+                        ? {
+                            result: 'blocked',
+                            detail: `raw connects from "${ctx.network}" to ${targets.length} public target(s) were refused or timed out`,
+                        }
+                        : {
+                            result: 'inconclusive',
+                            detail: `outbound probe exited ${String(code)} — it did not complete its attempts`,
+                        };
+        }
+    }
+    finally {
+        await removeProbeContainer(ctx, outboundName);
+    }
+    if (outbound.result === 'reachable') {
+        return { state: 'open', detail: outbound.detail, remediation: REMEDIATION };
+    }
+    // ── Leg 2: INPUT / host-bound ──────────────────────────────────────────────
+    const hostBound = await probeHostPort(ctx, timeoutMs);
+    if (hostBound.result === 'reachable') {
+        return { state: 'open', detail: hostBound.detail, remediation: REMEDIATION };
+    }
+    // A pass needs BOTH legs denied. One inconclusive leg makes the whole verdict
+    // inconclusive — half a proof is not a proof.
+    if (outbound.result === 'inconclusive' || hostBound.result === 'inconclusive') {
+        const parts = [outbound, hostBound]
+            .filter((leg) => leg.result === 'inconclusive')
+            .map((leg) => leg.detail);
+        return {
+            state: 'inconclusive',
+            detail: `egress could not be fully verified: ${parts.join('; ')}`,
+            remediation: `Ensure the Docker daemon is reachable and the base image ("${ctx.baseImage}") is present. ${REMEDIATION}`,
+        };
+    }
+    return {
+        state: 'filtered',
+        detail: `both legs denied — ${outbound.detail}; ${hostBound.detail}`,
+    };
+}

package/dist/hibernate.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Suspend and resume a Docker sandbox, and report which mechanism actually ran.
+ *
+ * Docker has two, and they are not interchangeable. A CRIU **checkpoint** freezes
+ * the whole process tree to disk and restores it; a **stop** does not, and a
+ * sandbox that comes back from one is running with nothing in it. Which one is
+ * available is a property of the HOST — CRIU needs the daemon's experimental
+ * flag and the `criu` package — so the same code path produces different
+ * fidelity on different machines, and the caller cannot know which it got.
+ *
+ * That is why both functions return a {@link HibernationOutcome} instead of
+ * `void`. molecule.dev's sandboxes run their dev servers as detached exec
+ * processes; after a stop-style wake the container is "running", the preview
+ * answers nothing, and `status` says everything is fine. The relaunch that fixes
+ * it is only expressible if the resume reports what it did.
+ *
+ * ## The parameter that is a query parameter
+ *
+ * Restoring from a checkpoint is `POST /containers/{id}/start?checkpoint=<name>`.
+ * The checkpoint name is a QUERY parameter. Passing it in a JSON body — which is
+ * an easy and silent mistake, since the daemon accepts the request and starts the
+ * container — performs an ordinary cold start while looking exactly like a
+ * successful restore.
+ *
+ * @module
+ */
+import type { HibernationOutcome } from '@molecule/api-code-sandbox';
+import type { DockerRequest } from './request.js';
+/** What the hibernation capability needs from the provider. */
+export interface HibernateContext {
+    request: DockerRequest;
+    /**
+     * Whether this host is believed to support CRIU checkpoints. Owned by the
+     * provider and flipped to `false` the first time the daemon says otherwise, so
+     * a host without CRIU pays one failed request per process rather than one per
+     * hibernation. Mutable state on purpose: the alternative is module-level state
+     * that tests cannot reset and two providers cannot hold separately.
+     */
+    checkpoints: {
+        supported: boolean;
+    };
+    warn?: (message: string, meta?: Record<string, unknown>) => void;
+    info?: (message: string, meta?: Record<string, unknown>) => void;
+}
+/**
+ * The checkpoint name for a container. Derived, not passed in: it is an
+ * implementation detail of this bond's own suspend/resume pair, and a caller that
+ * supplied it could only get it wrong.
+ *
+ * @param containerId - The container id.
+ * @returns A stable checkpoint name.
+ */
+export declare function checkpointName(containerId: string): string;
+/**
+ * Suspend a sandbox, preferring a checkpoint and falling back to a stop.
+ *
+ * Never fails just because the high-fidelity path is unavailable: a sandbox that
+ * cannot be checkpointed must still be suspendable. The outcome reports which
+ * one ran.
+ *
+ * @param ctx - Hibernation context.
+ * @param containerId - The sandbox to suspend.
+ * @returns What the suspend actually did.
+ */
+export declare function hibernateContainer(ctx: HibernateContext, containerId: string): Promise<HibernationOutcome>;
+/**
+ * Resume a suspended sandbox, preferring a checkpoint restore.
+ *
+ * A missing checkpoint is the ROUTINE case — it is what a stop-suspended sandbox
+ * looks like — so it falls through quietly. Any other restore failure is logged,
+ * because it means every wake on this host is silently taking the slow, empty
+ * path.
+ *
+ * @param ctx - Hibernation context.
+ * @param containerId - The sandbox to resume.
+ * @returns What the resume actually did.
+ */
+export declare function resumeContainer(ctx: HibernateContext, containerId: string): Promise<HibernationOutcome>;
+//# sourceMappingURL=hibernate.d.ts.map

package/dist/hibernate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hibernate.d.ts","sourceRoot":"","sources":["../src/hibernate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAA;AAEpE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAA;AAEjD,+DAA+D;AAC/D,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,aAAa,CAAA;IACtB;;;;;;OAMG;IACH,WAAW,EAAE;QAAE,SAAS,EAAE,OAAO,CAAA;KAAE,CAAA;IACnC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAA;IAChE,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAA;CACjE;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAE1D;AAcD;;;;;;;;;;GAUG;AACH,wBAAsB,kBAAkB,CACtC,GAAG,EAAE,gBAAgB,EACrB,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,kBAAkB,CAAC,CAiC7B;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,eAAe,CACnC,GAAG,EAAE,gBAAgB,EACrB,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,kBAAkB,CAAC,CAgD7B"}

package/dist/hibernate.js

@@ -0,0 +1,142 @@
+/**
+ * Suspend and resume a Docker sandbox, and report which mechanism actually ran.
+ *
+ * Docker has two, and they are not interchangeable. A CRIU **checkpoint** freezes
+ * the whole process tree to disk and restores it; a **stop** does not, and a
+ * sandbox that comes back from one is running with nothing in it. Which one is
+ * available is a property of the HOST — CRIU needs the daemon's experimental
+ * flag and the `criu` package — so the same code path produces different
+ * fidelity on different machines, and the caller cannot know which it got.
+ *
+ * That is why both functions return a {@link HibernationOutcome} instead of
+ * `void`. molecule.dev's sandboxes run their dev servers as detached exec
+ * processes; after a stop-style wake the container is "running", the preview
+ * answers nothing, and `status` says everything is fine. The relaunch that fixes
+ * it is only expressible if the resume reports what it did.
+ *
+ * ## The parameter that is a query parameter
+ *
+ * Restoring from a checkpoint is `POST /containers/{id}/start?checkpoint=<name>`.
+ * The checkpoint name is a QUERY parameter. Passing it in a JSON body — which is
+ * an easy and silent mistake, since the daemon accepts the request and starts the
+ * container — performs an ordinary cold start while looking exactly like a
+ * successful restore.
+ *
+ * @module
+ */
+/**
+ * The checkpoint name for a container. Derived, not passed in: it is an
+ * implementation detail of this bond's own suspend/resume pair, and a caller that
+ * supplied it could only get it wrong.
+ *
+ * @param containerId - The container id.
+ * @returns A stable checkpoint name.
+ */
+export function checkpointName(containerId) {
+    return `mol-hibernate-${containerId.slice(0, 12)}`;
+}
+/**
+ * Whether an error means "this host has no CRIU", as opposed to "this checkpoint
+ * failed". The former is permanent for the process; the latter is not, and
+ * treating it as permanent would silently downgrade every later hibernation.
+ *
+ * @param message - The error message.
+ * @returns `true` when the host does not support checkpointing at all.
+ */
+function isCheckpointUnsupported(message) {
+    return /\b501\b|not implemented|not supported|checkpoint.*disabled|experimental/i.test(message);
+}
+/**
+ * Suspend a sandbox, preferring a checkpoint and falling back to a stop.
+ *
+ * Never fails just because the high-fidelity path is unavailable: a sandbox that
+ * cannot be checkpointed must still be suspendable. The outcome reports which
+ * one ran.
+ *
+ * @param ctx - Hibernation context.
+ * @param containerId - The sandbox to suspend.
+ * @returns What the suspend actually did.
+ */
+export async function hibernateContainer(ctx, containerId) {
+    let fallbackReason = 'this host does not support CRIU checkpoints';
+    if (ctx.checkpoints.supported) {
+        try {
+            await ctx.request(`/containers/${containerId}/checkpoints`, 'POST', {
+                CheckpointID: checkpointName(containerId),
+                Exit: true,
+            });
+            return { processesPreserved: true, mechanism: 'checkpoint' };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            if (isCheckpointUnsupported(message)) {
+                ctx.checkpoints.supported = false;
+                ctx.info?.('CRIU checkpoints are not available on this host — hibernating by stopping from now on', { containerId, error: message });
+            }
+            else {
+                // A real checkpoint failure, on a host that CAN checkpoint. Do not
+                // disable the mechanism for the whole process over one bad attempt, but
+                // do not hide it either: every wake after this one costs a full relaunch.
+                ctx.warn?.('Checkpoint failed — falling back to stopping the sandbox', {
+                    containerId,
+                    error: message,
+                });
+                fallbackReason = `checkpoint failed: ${message}`;
+            }
+        }
+    }
+    await ctx.request(`/containers/${containerId}/stop`, 'POST');
+    return { processesPreserved: false, mechanism: 'stop', detail: fallbackReason };
+}
+/**
+ * Resume a suspended sandbox, preferring a checkpoint restore.
+ *
+ * A missing checkpoint is the ROUTINE case — it is what a stop-suspended sandbox
+ * looks like — so it falls through quietly. Any other restore failure is logged,
+ * because it means every wake on this host is silently taking the slow, empty
+ * path.
+ *
+ * @param ctx - Hibernation context.
+ * @param containerId - The sandbox to resume.
+ * @returns What the resume actually did.
+ */
+export async function resumeContainer(ctx, containerId) {
+    const name = checkpointName(containerId);
+    if (ctx.checkpoints.supported) {
+        try {
+            // Query parameter, not a body field — see this module's header.
+            await ctx.request(`/containers/${containerId}/start?checkpoint=${encodeURIComponent(name)}`, 'POST', undefined, 120_000);
+            // The checkpoint has been consumed; leaving it behind would make the next
+            // resume restore a stale process tree.
+            await ctx
+                .request(`/containers/${containerId}/checkpoints/${name}`, 'DELETE')
+                .catch((error) => {
+                ctx.warn?.('Could not delete a consumed checkpoint — the next resume may restore stale state', {
+                    containerId,
+                    error,
+                });
+            });
+            return { processesPreserved: true, mechanism: 'restore' };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            if (isCheckpointUnsupported(message)) {
+                ctx.checkpoints.supported = false;
+            }
+            else if (!/no such (checkpoint|file)|does not exist|not found|\b404\b/i.test(message)) {
+                ctx.warn?.('Checkpoint restore failed — starting the sandbox cold instead', {
+                    containerId,
+                    error: message,
+                });
+            }
+        }
+    }
+    // 120 s: a first-ever start populates a fresh named volume from the image,
+    // which is a multi-gigabyte copy on this fleet's base image.
+    await ctx.request(`/containers/${containerId}/start`, 'POST', undefined, 120_000);
+    return {
+        processesPreserved: false,
+        mechanism: 'start',
+        detail: 'started from a stopped state — no process tree was restored, so anything launched inside the sandbox must be relaunched',
+    };
+}