@spunto/build 0.16.0 → 0.17.0

package/src/sandbox-agent/agent.mjs

@@ -0,0 +1,1174 @@
+// Spunto sandbox agent (RFC 0035) — runs *inside* a sandbox, whatever runs the sandbox.
+//
+// One file, no dependencies, Node >= 22 (global WebSocket). It dials the platform, says hello with
+// the sandbox's own token, and then serves what the platform asks: run a command, open a terminal,
+// report its health. The provider that booted the box never sees any of it — which is the point:
+// a Docker host, a Kubernetes pod and a boat.dev VM all get the same data plane for free.
+//
+// Env: SPUNTO_API_URL, SPUNTO_SANDBOX_TOKEN (required), SPUNTO_WORKSPACE (default /workspace),
+// SPUNTO_AGENT_CONNECT_URL (default $SPUNTO_API_URL/api/sandbox-agent/connect, ws: or wss:).
+//
+// Shipped in @spunto/build (`./sandbox-agent`), served as is by whichever control plane runs the
+// box (RFC 0047); the wire is written down in `./agent-protocol`.
+
+import { spawn, execFileSync } from "node:child_process"
+import { mkdirSync, existsSync, readdirSync, readFileSync, readlinkSync, writeFileSync, openSync, statSync, statfsSync } from "node:fs"
+import { writeFile } from "node:fs/promises"
+import { dirname, join } from "node:path"
+import { fileURLToPath } from "node:url"
+import os from "node:os"
+import net from "node:net"
+
+const VERSION = "0.10.0"
+const API = (process.env.SPUNTO_API_URL ?? "").replace(/\/$/, "")
+// `let`: a fork (RFC 0039 § 4.10) hands this process the identity of the copy it now runs in.
+let TOKEN = process.env.SPUNTO_SANDBOX_TOKEN ?? ""
+const CONNECT_URL = process.env.SPUNTO_AGENT_CONNECT_URL || `${API.replace(/^http/, "ws")}/api/sandbox-agent/connect`
+const WORKSPACE = process.env.SPUNTO_WORKSPACE || "/workspace"
+const MAX_OUTPUT = 1024 * 1024 // per stream, per exec
+
+if (!API || !TOKEN) {
+  console.error("[sandbox-agent] SPUNTO_API_URL and SPUNTO_SANDBOX_TOKEN are required")
+  process.exit(2)
+}
+if (typeof WebSocket === "undefined") {
+  console.error(`[sandbox-agent] Node ${process.versions.node} has no global WebSocket — need Node >= 22`)
+  process.exit(2)
+}
+
+try {
+  mkdirSync(WORKSPACE, { recursive: true })
+} catch {}
+const CWD = existsSync(WORKSPACE) ? WORKSPACE : os.homedir()
+
+// Child processes must not inherit the agent's credential: a command run in the sandbox is the
+// user's code, and the token would let it impersonate the agent.
+const baseEnv = { ...process.env }
+delete baseEnv.SPUNTO_SANDBOX_TOKEN
+delete baseEnv.SPUNTO_AGENT_PIDFILE
+delete baseEnv.SPUNTO_AGENT_CONNECT_URL
+// Plus the project's environment (secrets…) once a project plan arrived — see `applyProject`.
+let childEnv = { ...baseEnv }
+
+const has = (bin) => {
+  try {
+    execFileSync("sh", ["-c", `command -v ${bin}`], { stdio: "ignore" })
+    return true
+  } catch {
+    return false
+  }
+}
+const SHELL = has("bash") ? "bash" : "sh"
+const HAS_SCRIPT = has("script")
+// python3 alone is not enough: a "minimal" python (pulled in by some feature, seen for real on
+// base:ubuntu + node) has no `pty` module. Ask for the modules the PTY helper actually imports.
+// SPUNTO_SANDBOX_PTY=script forces the fallback (the agent's own tests, which run both).
+const HAS_PYTHON = (() => {
+  if (process.env.SPUNTO_SANDBOX_PTY === "script") return false
+  try {
+    execFileSync("python3", ["-c", "import pty, termios, fcntl, select, struct"], { stdio: "ignore" })
+    return true
+  } catch {
+    return false
+  }
+})()
+const HAS_RUNUSER = has("runuser")
+
+// ── project (RFC 0035: a sandbox of a project gets what a worker of it gets) ──────
+const DIR = join(dirname(fileURLToPath(import.meta.url)), "project")
+// The worker script's home (overridable for the agent's own tests only).
+const HOME_DIR = process.env.SPUNTO_SANDBOX_HOME || "/home/vscode"
+const MP_STATUS = join(HOME_DIR, ".mp-status.json")
+const SETUP_DONE = join(HOME_DIR, ".mp-setup-done")
+let project = null // { plan, runner, exitCode, startedHere }
+let runAs = null // user terminals and commands run as, once the project recipe created it
+
+function userExists(name) {
+  try {
+    execFileSync("id", ["-u", name], { stdio: "ignore" })
+    return true
+  } catch {
+    return false
+  }
+}
+
+/** [cmd, args] running `argv` as `runAs` when there is one (root otherwise). */
+function asUser(argv) {
+  if (!runAs || process.getuid?.() !== 0 || !userExists(runAs)) return argv
+  if (HAS_RUNUSER) return ["runuser", ["-u", runAs, "--", argv[0], ...argv[1]]]
+  return ["su", [runAs, "-s", "/bin/sh", "-c", [argv[0], ...argv[1]].map((a) => `'${a.replace(/'/g, `'\\''`)}'`).join(" ")]]
+}
+
+/** What the feature recipe exported (see runner.sh), NUL-separated `K=V` — re-read on every spawn. */
+function featureEnv() {
+  try {
+    const out = {}
+    for (const kv of readFileSync(join(DIR, "env.list"), "utf8").split("\0")) {
+      const i = kv.indexOf("=")
+      if (i > 0) out[kv.slice(0, i)] = kv.slice(i + 1)
+    }
+    return out
+  } catch {
+    return {}
+  }
+}
+
+function userEnv(extra = {}) {
+  const env = { ...childEnv, ...featureEnv(), ...extra }
+  if (runAs && userExists(runAs)) {
+    env.HOME = `/home/${runAs}`
+    env.USER = runAs
+    env.LOGNAME = runAs
+  }
+  return env
+}
+
+// The runner (agent/runner.sh) comes with the plan: the same script a provider's build runs.
+
+function runnerPid() {
+  try {
+    const pid = Number(readFileSync(join(DIR, "runner.pid"), "utf8"))
+    // runner.sh execs worker.sh: either way the command line names a script of this directory.
+    if (pid && readFileSync(`/proc/${pid}/cmdline`, "utf8").includes(DIR)) return pid
+  } catch {}
+  return null
+}
+
+/** This boot of the box: the same after a resume (its RAM loaded), a new one after any boot. */
+function bootId() {
+  try {
+    return readFileSync("/proc/sys/kernel/random/boot_id", "utf8").trim()
+  } catch {
+    return null
+  }
+}
+
+/** The runner's last start: under which boot, and how it ended (`exitCode`, null while it runs or unknown). */
+const STARTED = () => join(DIR, "started.json")
+function lastStart() {
+  try {
+    return JSON.parse(readFileSync(STARTED(), "utf8"))
+  } catch {
+    return null
+  }
+}
+
+function tail(file, bytes = 4000) {
+  try {
+    const size = statSync(file).size
+    const buf = readFileSync(file)
+    return buf.subarray(Math.max(0, size - bytes)).toString("utf8")
+  } catch {
+    return ""
+  }
+}
+
+/**
+ * The worker script said `ready` for *this* start of the runner — postStart included. The marker of
+ * the one-time setup is on the box's disk since its first boot (or its build): on its own, it
+ * called the box running at every start while postStart was still going. `.mp-status.json` is on
+ * that disk too, so a `ready` older than the runner's start is the previous boot's.
+ */
+function startDone(worker) {
+  if (worker?.phase !== "ready") return false
+  try {
+    return statSync(MP_STATUS).mtimeMs >= statSync(STARTED()).mtimeMs
+  } catch {
+    return true // a runner started by an agent that kept no started.json: its word is all there is
+  }
+}
+
+function projectState() {
+  if (!project) return null
+  const { plan } = project
+  const baked = existsSync(join(DIR, `.baked-${plan.bakeKey}`))
+  const alive = runnerPid() != null
+  let worker = null
+  try {
+    worker = JSON.parse(readFileSync(MP_STATUS, "utf8"))
+  } catch {}
+  const phase = !alive && project.exitCode != null && project.exitCode !== 0
+    ? "failed"
+    : plan.bakeOnly
+      ? baked && !alive ? "baked" : alive ? "baking" : "pending"
+    : !baked
+      ? alive ? "baking" : "pending"
+      : existsSync(SETUP_DONE)
+        ? alive ? (startDone(worker) ? "running" : "setting-up") : "exited"
+        : alive ? "setting-up" : "exited"
+  return {
+    phase,
+    version: plan.version,
+    bakeKey: plan.bakeKey,
+    exitCode: project.exitCode,
+    worker,
+    logTail: tail(join(DIR, "project.log")),
+    at: new Date().toISOString(),
+  }
+}
+
+function reportProject() {
+  const state = projectState()
+  if (state) send({ type: "project_state", state })
+}
+
+// The member's git credential (RFC 0025), from a file this agent keeps current rather than from
+// the env of the process asking. The setup's helper reads $SPUNTO_WORKER_TOKEN, frozen in every
+// shell, code-server and session started since: in a fork or a member's model (RFC 0039 § 4.10),
+// that is the source's token. A system helper comes before the user's: it answers with the token
+// of the box it runs in, and says nothing when it has none (the setup's helper is asked next).
+const GIT_HELPER = "/opt/spunto-sandbox/git-credential"
+const GIT_HELPER_SOURCE = `#!/bin/sh
+# Spunto sandbox: the member's git credential, with the token the agent keeps in ~/.spunto/git-token.
+[ "$1" = get ] || exit 0
+T=$(cat "$HOME/.spunto/git-token" 2>/dev/null); A=$(cat "$HOME/.spunto/api-url" 2>/dev/null)
+[ -n "$T" ] && [ -n "$A" ] || exit 0
+REPO=
+while IFS= read -r line; do case "$line" in path=*) REPO="\${line#path=}" ;; "") break ;; esac; done
+REPO="\${REPO%.git}"
+R=$(curl -fsS -m 20 -X POST "$A/api/workers/git-credential" -H "Authorization: Bearer $T" -H "Content-Type: application/json" -d "{\\"repo\\":\\"$REPO\\"}" 2>/dev/null) || exit 0
+P=$(printf %s "$R" | sed -n 's/.*"password":"\\([^"]*\\)".*/\\1/p')
+[ -n "$P" ] || exit 0
+echo "username=$(printf %s "$R" | sed -n 's/.*"username":"\\([^"]*\\)".*/\\1/p')"
+echo "password=$P"
+`
+function refreshGitIdentity(plan) {
+  const token = plan.env?.SPUNTO_WORKER_TOKEN
+  if (!token || !runAs || process.getuid?.() !== 0 || !userExists(runAs)) return
+  try {
+    const dir = `/home/${runAs}/.spunto`
+    mkdirSync(dir, { recursive: true, mode: 0o700 })
+    writeFileSync(`${dir}/git-token`, `${token}\n`, { mode: 0o600 })
+    writeFileSync(`${dir}/api-url`, `${plan.env.SPUNTO_API_URL ?? API}\n`, { mode: 0o600 })
+    execFileSync("chown", [`${runAs}:`, dir, `${dir}/git-token`, `${dir}/api-url`], { stdio: "ignore" })
+    mkdirSync("/opt/spunto-sandbox", { recursive: true })
+    writeFileSync(GIT_HELPER, GIT_HELPER_SOURCE, { mode: 0o755 })
+    if (!has("git")) return
+    const helpers = (() => {
+      try {
+        return execFileSync("git", ["config", "--system", "--get-all", "credential.helper"], { encoding: "utf8" })
+      } catch {
+        return ""
+      }
+    })()
+    if (!helpers.split("\n").includes(GIT_HELPER)) execFileSync("git", ["config", "--system", "--add", "credential.helper", GIT_HELPER], { stdio: "ignore" })
+  } catch (err) {
+    console.warn(`[sandbox-agent] git identity not written: ${err.message}`)
+  }
+}
+
+/**
+ * The image's own ENV (the plan's `imageEnv`), for a box whose provider booted the image's files
+ * without it (a microVM): its PATH in front of ours — `claude` in spunto-worker-base is in
+ * /usr/local/share/npm-global/bin, which only the image's ENV says —, anything else only if unset.
+ */
+function underImageEnv(env, image) {
+  if (!image || typeof image !== "object") return {}
+  const out = {}
+  for (const [k, v] of Object.entries(image)) {
+    if (typeof v !== "string") continue
+    if (k === "PATH") {
+      const seen = new Set()
+      out.PATH = [...v.split(":"), ...(env.PATH ?? "").split(":")].filter((p) => p && !seen.has(p) && seen.add(p)).join(":")
+    } else if (env[k] == null) out[k] = v
+  }
+  return out
+}
+
+function applyProject(plan) {
+  mkdirSync(DIR, { recursive: true, mode: 0o700 })
+  writeFileSync(join(DIR, "bake.sh"), plan.bake, { mode: 0o700 })
+  writeFileSync(join(DIR, "worker.sh"), plan.worker, { mode: 0o700 })
+  writeFileSync(join(DIR, "runner.sh"), plan.runner, { mode: 0o700 })
+  childEnv = { ...baseEnv, ...underImageEnv(baseEnv, plan.imageEnv), ...plan.env }
+  runAs = plan.user || null
+  refreshGitIdentity(plan)
+  project = { plan, exitCode: project?.exitCode ?? null }
+
+  if (runnerPid()) {
+    // Already running (this agent restarted, or merely reconnected): leave the user's processes
+    // alone. A new project version is applied at the next start of the box.
+    reportProject()
+    return
+  }
+  // Not running, but already started in this very boot: its runner ended (postStart done, nothing
+  // left in the background) and the box was resumed with its RAM, or the agent merely reconnected.
+  // postStart runs once per boot — never at a resume (RFC 0039 § 20). Only a runner that is known to
+  // have failed is started again, as before.
+  const boot = bootId()
+  const last = lastStart()
+  if (boot && last?.boot === boot && !(last.exitCode != null && last.exitCode !== 0)) {
+    project.exitCode = last.exitCode ?? null
+    reportProject()
+    return
+  }
+  const log = openSync(join(DIR, "project.log"), "a")
+  // Before the spawn: the worker script's `ready` of this start must be newer than it (startDone).
+  writeFileSync(STARTED(), JSON.stringify({ boot, version: plan.version, exitCode: null, at: new Date().toISOString() }))
+  // Detached, in its own session: it outlives an agent restart, like a container's CMD would.
+  const child = spawn("bash", [join(DIR, "runner.sh"), DIR, plan.bakeKey, plan.bakeOnly ? "bake-only" : "full"], {
+    cwd: "/",
+    env: { ...childEnv, HOME: "/root" },
+    detached: true,
+    stdio: ["ignore", log, log],
+  })
+  writeFileSync(join(DIR, "runner.pid"), String(child.pid))
+  project.exitCode = null
+  child.on("exit", (code) => {
+    project.exitCode = code ?? 1
+    try {
+      writeFileSync(STARTED(), JSON.stringify({ ...lastStart(), exitCode: project.exitCode, endedAt: new Date().toISOString() }))
+    } catch {}
+    reportProject()
+  })
+  child.unref()
+  console.log(`[sandbox-agent] project ${plan.projectId} v${plan.version}: runner ${child.pid}`)
+  reportProject()
+}
+
+// A change of phase goes out at once — the platform waits on `running` to call the box ready, and
+// riding the heartbeat cost ~14 s on every create and every start (measured on boat). Otherwise,
+// every 5 s while something is happening, else the heartbeat cadence.
+let reportedPhase = null
+let reportedAt = 0
+setInterval(() => {
+  const st = projectState()
+  if (!st) return
+  const busy = ["baking", "setting-up", "pending"].includes(st.phase)
+  if (st.phase !== reportedPhase || (busy && Date.now() - reportedAt >= 5_000)) {
+    reportedPhase = st.phase
+    reportedAt = Date.now()
+    send({ type: "project_state", state: st })
+  }
+}, 1_000).unref()
+
+let ws = null
+let backoff = 1000
+const terminals = new Map() // termId → child
+const execs = new Map() // execId → child
+
+function send(msg) {
+  if (ws && ws.readyState === WebSocket.OPEN) ws.send(JSON.stringify(msg))
+}
+
+function info() {
+  return {
+    agentVersion: VERSION,
+    hostname: os.hostname(),
+    platform: `${os.type()} ${os.release()}`,
+    arch: os.arch(),
+    node: process.versions.node,
+    cpus: boxResources().cpus,
+    memTotal: boxResources().memTotal,
+    shell: SHELL,
+    pty: HAS_PYTHON ? "python3" : HAS_SCRIPT ? "script" : "none",
+    workspace: CWD,
+  }
+}
+
+/**
+ * The box's own resources, not the host's: in a container `os.totalmem()` and the load average
+ * are the machine's (a 2 GB sandbox showed 22 GB used). cgroup v2 says what this box has and
+ * uses; a VM (boat, GCE) has no limit there and falls back to `os`, which is then right.
+ */
+const CG = "/sys/fs/cgroup"
+let lastCpu = null // { usec, at }
+function readNum(file) {
+  try {
+    const v = readFileSync(file, "utf8").trim()
+    return v === "max" ? null : Number(v.split(/\s+/)[0])
+  } catch {
+    return undefined
+  }
+}
+function boxResources() {
+  const memCurrent = readNum(`${CG}/memory.current`)
+  const memMax = readNum(`${CG}/memory.max`)
+  let cpuPercent = null
+  let cpus = os.cpus().length
+  try {
+    const [quota, period] = readFileSync(`${CG}/cpu.max`, "utf8").trim().split(/\s+/)
+    if (quota !== "max") cpus = Number(quota) / Number(period)
+  } catch {}
+  try {
+    const usec = Number(/usage_usec (\d+)/.exec(readFileSync(`${CG}/cpu.stat`, "utf8"))?.[1])
+    const at = Date.now()
+    if (lastCpu && at > lastCpu.at) cpuPercent = Math.min(100, ((usec - lastCpu.usec) / 1000 / (at - lastCpu.at) / cpus) * 100)
+    lastCpu = { usec, at }
+  } catch {}
+  const inCgroup = typeof memCurrent === "number"
+  const memTotal = inCgroup && memMax ? memMax : os.totalmem()
+  const memUsed = inCgroup ? memCurrent : os.totalmem() - os.freemem()
+  return { memTotal, memFree: Math.max(0, memTotal - memUsed), cpuPercent: cpuPercent == null ? null : Math.round(cpuPercent), cpus: Math.round(cpus * 10) / 10 }
+}
+
+/**
+ * How full the system disk and /workspace are — `statfs`, no walk: cheap enough for every call. What
+ * a full `/` looked like before this (RFC 0039 § 4.12): a terminal saying a dtach socket did not
+ * exist, its `mkdir` failing with "No space left on device" out of sight.
+ */
+function diskUsage() {
+  const out = []
+  for (const path of ["/", WORKSPACE]) {
+    try {
+      const st = statfsSync(path)
+      const sizeMb = Math.round((st.blocks * st.bsize) / 1024 ** 2)
+      // `bavail`, not `bfree`: what a user can still write (root's reserve excluded).
+      const freeMb = Math.round((st.bavail * st.bsize) / 1024 ** 2)
+      if (sizeMb > 0 && !out.some((d) => d.sizeMb === sizeMb && d.freeMb === freeMb)) out.push({ path, sizeMb, freeMb })
+    } catch {}
+  }
+  return out
+}
+
+function heartbeat() {
+  send({ type: "heartbeat" })
+  reportProject()
+}
+
+/**
+ * Gives the host back the page cache nobody reads any more (RFC 0039 § 15). In a microVM the
+ * guest's cache is RAM the VMM holds: the guest counts it as available and never drops it without
+ * pressure of its own, while the host sees it in the box's memory, its slice fills up, and the
+ * kernel kills a box (one showed 3 GB used inside, 8 GB outside). The balloon's free page reporting
+ * returns what the guest *frees*: so every minute, the cold half of the cache (`Inactive(file)`,
+ * pages read once and not since) is reclaimed through the root cgroup — the hot files stay cached,
+ * unlike `drop_caches`. Only with a balloon (Firecracker); a container has no business doing it.
+ *
+ * Freed is not enough: the balloon only reports free blocks of 2 MB and more, and a cache dropped
+ * page by page leaves holes between the pages still in use. Measured on Canada (2026-10-16): 550 MB
+ * of cache reclaimed in the guest, 40 MB back on the host; then a compaction, 377 MB (2.3 s of the
+ * kernel's CPU). So when the free memory in blocks under 2 MB (`/proc/buddyinfo`, orders 0 to 8)
+ * passes 256 MB, the guest is compacted, every 10 minutes at most.
+ */
+const RECLAIM_MIN_BYTES = 256 * 1024 ** 2
+const COMPACT_EVERY_MS = 10 * 60_000
+let compactedAt = 0
+const hasBalloon = (() => {
+  try {
+    return readdirSync("/sys/bus/virtio/devices").some((d) => readFileSync(`/sys/bus/virtio/devices/${d}/device`, "utf8").trim() === "0x0005")
+  } catch {
+    return false
+  }
+})()
+let reclaiming = false
+async function reclaimColdCache() {
+  if (reclaiming) return
+  let bytes = 0
+  try {
+    bytes = Number(/^Inactive\(file\):\s+(\d+) kB$/m.exec(readFileSync("/proc/meminfo", "utf8"))?.[1]) * 1024
+  } catch {}
+  reclaiming = true
+  // On the thread pool: reclaiming a few GB takes the kernel a second or so. EAGAIN when it could
+  // not reach the whole amount (pages in use meanwhile): what it did reclaim is gone all the same.
+  if (bytes >= RECLAIM_MIN_BYTES) await writeFile(`${CG}/memory.reclaim`, String(bytes)).catch(() => {})
+  if (Date.now() - compactedAt >= COMPACT_EVERY_MS && fragmentedFreeBytes() >= RECLAIM_MIN_BYTES) {
+    compactedAt = Date.now()
+    await writeFile("/proc/sys/vm/compact_memory", "1").catch(() => {})
+  }
+  reclaiming = false
+}
+
+/** Free memory in blocks too small for the balloon to report (under 2 MB: orders 0 to 8 of 4 KB pages). */
+function fragmentedFreeBytes() {
+  let pages = 0
+  try {
+    for (const line of readFileSync("/proc/buddyinfo", "utf8").split("\n")) {
+      const counts = line.split(/\s+/).slice(4).map(Number)
+      for (let order = 0; order < 9 && order < counts.length; order++) pages += counts[order] * 2 ** order
+    }
+  } catch {}
+  return pages * 4096
+}
+
+// ── exec ──────────────────────────────────────────────────────────────────────
+function runExec(msg) {
+  const started = Date.now()
+  const [cmd, args] = asUser([SHELL, ["-lc", msg.command]])
+  const child = spawn(cmd, args, {
+    cwd: msg.cwd || CWD,
+    env: userEnv(msg.env ?? {}),
+    stdio: ["ignore", "pipe", "pipe"],
+  })
+  execs.set(msg.id, child)
+  const out = { stdout: [], stderr: [], size: { stdout: 0, stderr: 0 }, truncated: false }
+  const collect = (stream) => (chunk) => {
+    if (out.size[stream] >= MAX_OUTPUT) {
+      out.truncated = true
+      return
+    }
+    const room = MAX_OUTPUT - out.size[stream]
+    const piece = chunk.length > room ? chunk.subarray(0, room) : chunk
+    if (piece.length < chunk.length) out.truncated = true
+    out[stream].push(piece)
+    out.size[stream] += piece.length
+  }
+  child.stdout.on("data", collect("stdout"))
+  child.stderr.on("data", collect("stderr"))
+  let timedOut = false
+  const timer = setTimeout(() => {
+    timedOut = true
+    child.kill("SIGKILL")
+  }, Math.min(Math.max(Number(msg.timeoutMs) || 60_000, 1000), 30 * 60_000))
+  const finish = (exitCode, error) => {
+    clearTimeout(timer)
+    execs.delete(msg.id)
+    send({
+      type: "exec_result",
+      id: msg.id,
+      exitCode,
+      timedOut,
+      error,
+      stdout: Buffer.concat(out.stdout).toString("utf8"),
+      stderr: Buffer.concat(out.stderr).toString("utf8"),
+      truncated: out.truncated,
+      durationMs: Date.now() - started,
+    })
+  }
+  child.on("error", (err) => finish(null, err.message))
+  child.on("close", (code, signal) => finish(code ?? (signal ? 128 : null)))
+}
+
+// ── terminals ─────────────────────────────────────────────────────────────────
+// A real PTY without native modules: python3's `pty` when present (it also handles resizes, via a
+// tiny control protocol on fd 3), else util-linux `script`, else a plain interactive shell.
+const PY_PTY = `
+import os, pty, sys, select, struct, fcntl, termios, signal
+cols, rows = int(sys.argv[1]), int(sys.argv[2])
+# The control pipe is ours alone: a program started in the pty must not hold it open for life.
+os.set_inheritable(3, False)
+pid, fd = pty.fork()
+if pid == 0:
+    os.execvp(sys.argv[3], sys.argv[3:])
+def setsize(c, r):
+    fcntl.ioctl(fd, termios.TIOCSWINSZ, struct.pack("HHHH", r, c, 0, 0))
+setsize(cols, rows)
+ctl = os.fdopen(3, "rb", 0)
+buf = b""
+# Input is written to the pty without blocking, from a queue: a blocking write of a paste bigger
+# than the pty's input queue stopped this loop reading the program's output, and the program,
+# echoing the paste, blocked writing it — both stuck for good. Past 1 MB queued, stdin waits.
+os.set_blocking(fd, False)
+pending = b""
+while True:
+    try:
+        r, w, _ = select.select([fd, ctl] + ([0] if len(pending) < 1048576 else []), [fd] if pending else [], [])
+    except InterruptedError:
+        continue
+    if fd in w:
+        try:
+            pending = pending[os.write(fd, pending[:65536]):]
+        except BlockingIOError:
+            pass
+        except OSError:
+            break
+    if fd in r:
+        try:
+            data = os.read(fd, 65536)
+        except BlockingIOError:
+            data = None
+        except OSError:
+            break
+        if data == b"":
+            break
+        if data:
+            os.write(1, data)
+    if 0 in r:
+        data = os.read(0, 65536)
+        if not data:
+            break
+        pending += data
+    if ctl in r:
+        data = ctl.read(64)
+        if not data:
+            continue
+        buf += data
+        while b"\\n" in buf:
+            line, buf = buf.split(b"\\n", 1)
+            try:
+                c, r2 = map(int, line.split())
+                setsize(c, r2)
+                os.kill(pid, signal.SIGWINCH)
+            except Exception:
+                pass
+try:
+    _, status = os.waitpid(pid, 0)
+    sys.exit(os.waitstatus_to_exitcode(status))
+except Exception:
+    sys.exit(0)
+`
+
+/** `script` fallback: find the pty its shell got, set the size on it, and tell the shell. */
+function resizeScriptPty(scriptPid, cols, rows) {
+  try {
+    const child = readdirSync("/proc").find((d) => {
+      if (!/^\d+$/.test(d)) return false
+      try {
+        return readFileSync(`/proc/${d}/stat`, "utf8").split(") ")[1]?.split(" ")[1] === String(scriptPid)
+      } catch {
+        return false
+      }
+    })
+    if (!child) return
+    const pty = readlinkSync(`/proc/${child}/fd/0`)
+    if (!pty.startsWith("/dev/pts/")) return
+    execFileSync("stty", ["-F", pty, "cols", String(cols), "rows", String(rows)], { stdio: "ignore" })
+    process.kill(-Number(child), "SIGWINCH")
+  } catch {}
+}
+
+// What a terminal's environment says about the terminal: xterm.js, 256 colours and 24-bit ones.
+const TERM_ENV = { TERM: "xterm-256color", COLORTERM: "truecolor" }
+
+/**
+ * The program a session runs, as positional parameters (`"$@"`): the login shell under script(1),
+ * as in a worker's terminal (apps/agent terminal-dtach.ts). script records the session's output
+ * for the replay of a reattach, and it sits between dtach and the shell: straight over the shell,
+ * a paste bigger than the pty's input queue (~4 KB) deadlocked dtach's master, blocked writing the
+ * paste in, against the shell, blocked writing its echo out — the session was dead for good,
+ * Ctrl-C and reattach included (BAC-18). Without script: the shell, which works, minus both.
+ */
+const SESSION_PROGRAM = [
+  '_SH=$(getent passwd "$(id -un)" 2>/dev/null | cut -d: -f7); _SH=${_SH:-/bin/bash}',
+  // script runs `-c` through $SHELL, and what the session starts reads it too.
+  'export SHELL="$_SH"',
+  'LOG="$D/$MP_TERM_SESSION.log"',
+  'if command -v script >/dev/null 2>&1; then set -- script -q -a -f "$LOG" -c "$_SH -l"; else set -- "$_SH" -l; fi',
+].join("\n")
+
+/** Bytes of a session's recorded output replayed to a reattach, and the log's bounds (a worker's). */
+const REPLAY_BYTES = 262144
+const REPLAY_MIN_BYTES = 512 // a fresh "+" session has recorded its prompt: nothing worth a replay
+const MAX_LOG_BYTES = 4194304
+const TRIM_TO = 1048576
+
+/**
+ * What runs inside the PTY: a named dtach session when dtach is there (spunto-pack bakes it in),
+ * so closing the tab or losing the network detaches instead of killing the shell — the worker
+ * terminal's behaviour (apps/agent terminal-dtach.ts, same flags). Without dtach: a plain shell.
+ *   -A attach-or-create · -r winch repaint on attach · -E no detach key · -z Ctrl-Z to the program
+ */
+const TERM_SCRIPT = [
+  "D=/tmp/spunto-term",
+  'SOCK="$D/$MP_TERM_SESSION.sock"',
+  SESSION_PROGRAM,
+  // What goes wrong here is said, with the disk's state — then a plain shell rather than nothing:
+  // a full `/` showed only `dtach -a`'s "No such file or directory" (RFC 0039 § 4.12).
+  'fail() { printf "\\r\\n\\033[1;31mspunto: %s\\033[0m\\r\\n" "$1"; df -h / /tmp 2>/dev/null | sed "s/$/\\r/"; printf "\\033[2m(a plain shell, without a session that survives the tab)\\033[0m\\r\\n\\r\\n"; exec "$_SH" -l; }',
+  'err=$(mkdir -p "$D" 2>&1) || fail "cannot create $D: $err"',
+  // chmod is best effort, as before: a directory made by another user (root, an earlier session)
+  // cannot be chmodded but may well be writable — only a directory this user cannot write in fails.
+  'chmod 700 "$D" 2>/dev/null; [ -w "$D" ] || fail "$D is not writable by $(id -un)"',
+  'if ! command -v dtach >/dev/null 2>&1; then exec "$_SH" -l; fi',
+  // The session is created detached, like a "+" tab (createSession), then attached. Created by the
+  // attach itself (`-A`), it was the attach's child: the session kept this PTY's control pipe (fd 3)
+  // and its size variables for life, and the terminal that created it never reported its exit —
+  // the one thing "main", the tab every first visit opens, had that the others did not.
+  // A socket left by a dead session refuses connections: `-n` cannot bind it, so it goes first. If
+  // two attaches race to create it, the loser's `-n` fails and its `-a` joins the winner's.
+  // A session that is not live has nothing to replay: its log goes with it.
+  'LIVE=0',
+  'if [ -S "$SOCK" ] && dtach -p "$SOCK" </dev/null >/dev/null 2>&1; then LIVE=1; else rm -f "$SOCK"; : > "$LOG" 2>/dev/null; fi',
+  'if [ ! -S "$SOCK" ]; then err=$(dtach -n "$SOCK" -E -z "$@" </dev/null 2>&1 >/dev/null 3>&-) || [ -S "$SOCK" ] || fail "cannot start the session: ${err:-dtach -n failed}"; fi',
+  '[ -S "$SOCK" ] || fail "the session socket $SOCK is not there"',
+  // The replay: dtach remembers nothing of the screen, `-r winch` only gets the program to repaint
+  // itself — so the tail of the log comes first, after a reset (the tail can start mid-sequence, on
+  // the alternate screen, with the mouse grabbed) and without its first, likely truncated, line.
+  'if [ "$LIVE" = 1 ] && [ -f "$LOG" ]; then',
+  '  SZ=$(wc -c < "$LOG" 2>/dev/null || echo 0)',
+  `  if [ "$SZ" -gt ${MAX_LOG_BYTES} ] 2>/dev/null; then tail -c ${TRIM_TO} "$LOG" > "$LOG.trim" 2>/dev/null && cat "$LOG.trim" > "$LOG" 2>/dev/null; rm -f "$LOG.trim"; fi`,
+  `  if [ "$SZ" -gt ${REPLAY_MIN_BYTES} ] 2>/dev/null; then`,
+  "    printf '\\033[?1049l\\033[?1000l\\033[?1002l\\033[?1003l\\033[?1006l\\033c\\033[2m── replay ──\\033[0m\\r\\n'",
+  `    tail -c ${REPLAY_BYTES} "$LOG" 2>/dev/null | tail -n +2`,
+  "  fi",
+  "fi",
+  'exec dtach -a "$SOCK" -r winch -E -z',
+].join("\n")
+
+/**
+ * dtach clears the screen as a client attaches (a bare `ESC[H ESC[J`), which would wipe the replay
+ * printed just before. Dropped once, in the first seconds of the attach — a worker's terminal does
+ * the same (makeDtachAttachClearStripper); `clear` writes other bytes, so it is never touched.
+ */
+function attachClearStripper(windowMs = 5000) {
+  const CLEAR = Buffer.from("\x1b[H\x1b[J")
+  const deadline = Date.now() + windowMs
+  let done = false
+  return (buf) => {
+    if (done || Date.now() > deadline) {
+      done = true
+      return buf
+    }
+    const i = buf.indexOf(CLEAR)
+    if (i === -1) return buf
+    done = true
+    return Buffer.concat([buf.subarray(0, i), buf.subarray(i + CLEAR.length)])
+  }
+}
+
+// ── terminal sessions (the worker's tab strip) ────────────────────────────────
+// A session is a dtach socket in /tmp/spunto-term, nothing more — like the worker agent's.
+const TERM_DIR = "/tmp/spunto-term"
+const sessionName = (n) => String(n || "").replace(/[^A-Za-z0-9_-]/g, "").slice(0, 40)
+
+function holders(sock) {
+  try {
+    return execFileSync("ps", ["-eo", "args="], { encoding: "utf8" }).split("\n").filter((l) => l.includes(sock)).length
+  } catch {
+    return 0
+  }
+}
+
+function listSessions() {
+  let names = []
+  try {
+    names = readdirSync(TERM_DIR).filter((f) => f.endsWith(".sock"))
+  } catch {}
+  return names
+    .map((f) => {
+      const sock = join(TERM_DIR, f)
+      const n = holders(sock)
+      if (n === 0) return null // a leftover socket, nobody behind it
+      let createdAt = Date.now()
+      try {
+        createdAt = statSync(sock).ctimeMs
+      } catch {}
+      // The dtach master holds the socket; any more process is an attached client.
+      return { name: f.slice(0, -5), windows: 1, attached: n > 1, createdAt: Math.round(createdAt) }
+    })
+    .filter(Boolean)
+    .sort((a, b) => a.createdAt - b.createdAt)
+}
+
+function createSession(requested) {
+  const taken = new Set(listSessions().map((s) => s.name))
+  let name = sessionName(requested)
+  if (!name) {
+    let i = 2
+    while (taken.has(`shell-${i}`)) i++
+    name = taken.has("main") ? `shell-${i}` : "main"
+  }
+  // Started detached (-n): it exists before anyone attaches, like a new tmux window.
+  const script = [
+    `D=${TERM_DIR}`,
+    'mkdir -p "$D" || exit 4; chmod 700 "$D" 2>/dev/null; [ -w "$D" ] || exit 4',
+    SESSION_PROGRAM,
+    'command -v dtach >/dev/null 2>&1 || exit 3',
+    ': > "$LOG" 2>/dev/null',
+    'exec dtach -n "$D/$MP_TERM_SESSION.sock" -E -z "$@"',
+  ].join("\n")
+  const [cmd, args] = asUser(["sh", ["-c", script]])
+  try {
+    execFileSync(cmd, args, { cwd: CWD, env: userEnv({ ...TERM_ENV, MP_TERM_SESSION: name }), stdio: ["ignore", "ignore", "pipe"], timeout: 10_000 })
+  } catch (err) {
+    // Said in the agent's log with the disk's state: a full `/` is the usual cause.
+    const full = diskUsage().filter((d) => d.freeMb < 64)
+    console.error(`[sandbox-agent] session ${name} not created: ${String(err.stderr || err.message).trim()}${full.length ? ` — full: ${full.map((d) => d.path).join(", ")}` : ""}`)
+  }
+  return listSessions()
+}
+
+function killSession(requested) {
+  const sock = join(TERM_DIR, `${sessionName(requested)}.sock`)
+  try {
+    execFileSync("pkill", ["-f", sock], { stdio: "ignore" })
+  } catch {}
+  try {
+    execFileSync("rm", ["-f", sock, sock.replace(/\.sock$/, ".log")], { stdio: "ignore" })
+  } catch {}
+  return listSessions()
+}
+
+// ── logs: what a worker's "container logs" are — the project runner's output ─────
+function openLogs(msg) {
+  const file = join(DIR, "project.log")
+  const forward = (chunk) => send({ type: "term_data", termId: msg.termId, data: chunk.toString("base64") })
+  if (!existsSync(file)) {
+    forward(Buffer.from("[spunto] No project runs in this sandbox (bare image): nothing logs here yet.\r\n"))
+  }
+  // -F: follows the file across a restart of the runner (it is reopened, not truncated).
+  const child = spawn("tail", ["-n", "400", "-F", file], { stdio: ["ignore", "pipe", "pipe"] })
+  terminals.set(msg.termId, child)
+  child.stdout.on("data", (c) => forward(Buffer.from(c.toString("utf8").replace(/\r?\n/g, "\r\n"))))
+  child.on("close", (code) => {
+    terminals.delete(msg.termId)
+    send({ type: "term_exit", termId: msg.termId, code })
+  })
+}
+
+function openTerminal(msg) {
+  const cols = Math.max(Number(msg.cols) || 120, 20)
+  const rows = Math.max(Number(msg.rows) || 30, 5)
+  const session = String(msg.session || "main").replace(/[^A-Za-z0-9_-]/g, "").slice(0, 40) || "main"
+  // No COLUMNS/LINES: the pty has the size, and a shell that inherits them keeps them past a resize.
+  const env = userEnv({ ...TERM_ENV, MP_TERM_SESSION: session })
+  const [shCmd, shArgs] = asUser(["sh", ["-c", TERM_SCRIPT]])
+  let child
+  if (HAS_PYTHON) {
+    child = spawn("python3", ["-c", PY_PTY, String(cols), String(rows), shCmd, ...shArgs], {
+      cwd: CWD,
+      env,
+      stdio: ["pipe", "pipe", "pipe", "pipe"],
+    })
+  } else if (HAS_SCRIPT) {
+    // `script` has no size of its own: set it from inside, then resize through the pty (below).
+    const login = [shCmd, ...shArgs].map((a) => `'${a.replace(/'/g, `'\\''`)}'`).join(" ")
+    child = spawn("script", ["-qfc", `stty cols ${cols} rows ${rows} 2>/dev/null; exec ${login}`, "/dev/null"], {
+      cwd: CWD,
+      env,
+      stdio: ["pipe", "pipe", "pipe"],
+    })
+  } else {
+    child = spawn(SHELL, ["-i"], { cwd: CWD, env: { ...env, COLUMNS: String(cols), LINES: String(rows) }, stdio: ["pipe", "pipe", "pipe"] })
+  }
+  terminals.set(msg.termId, child)
+  const strip = attachClearStripper()
+  const forward = (chunk) => send({ type: "term_data", termId: msg.termId, data: strip(chunk).toString("base64") })
+  child.stdout.on("data", forward)
+  child.stderr.on("data", forward)
+  child.on("error", (err) => {
+    send({ type: "term_data", termId: msg.termId, data: Buffer.from(`\r\n[agent] ${err.message}\r\n`).toString("base64") })
+  })
+  child.on("close", (code) => {
+    terminals.delete(msg.termId)
+    send({ type: "term_exit", termId: msg.termId, code })
+  })
+}
+
+// ── ports: TCP tunnels to what listens inside the box ─────────────────────────────
+// The platform's proxy reaches `sbx-<id>-<port>.<domain>` through here: the API asks for a tunnel,
+// the agent connects to 127.0.0.1:<port> — it runs inside the box, so no container IP to resolve —
+// and bytes flow both ways as binary frames: [1][id length][id][payload].
+const tunnels = new Map()
+const FRAME_DATA = 1
+const HIGH_WATER = 8 * 1024 * 1024
+
+function tunnelFrame(tunnelId, chunk) {
+  const id = Buffer.from(tunnelId)
+  return Buffer.concat([Buffer.from([FRAME_DATA, id.length]), id, chunk])
+}
+
+function openTunnel(msg) {
+  const port = Number(msg.port)
+  if (!Number.isInteger(port) || port < 1 || port > 65535) return send({ type: "tunnel_close", tunnelId: msg.tunnelId, error: "bad port" })
+  const sock = net.connect({ host: "127.0.0.1", port })
+  tunnels.set(msg.tunnelId, sock)
+  sock.on("connect", () => send({ type: "tunnel_ready", tunnelId: msg.tunnelId }))
+  sock.on("data", (chunk) => {
+    if (!ws || ws.readyState !== WebSocket.OPEN) return sock.destroy()
+    ws.send(tunnelFrame(msg.tunnelId, chunk))
+    // Backpressure: a slow browser must not make the agent buffer a whole download.
+    if (ws.bufferedAmount > HIGH_WATER) {
+      sock.pause()
+      const wait = setInterval(() => {
+        if (!ws || ws.readyState !== WebSocket.OPEN || ws.bufferedAmount < HIGH_WATER / 4) {
+          clearInterval(wait)
+          sock.resume()
+        }
+      }, 20)
+    }
+  })
+  const close = (error) => {
+    if (!tunnels.has(msg.tunnelId)) return
+    tunnels.delete(msg.tunnelId)
+    send({ type: "tunnel_close", tunnelId: msg.tunnelId, ...(error ? { error } : {}) })
+  }
+  sock.on("error", (err) => close(err.code === "ECONNREFUSED" ? `nothing listens on port ${port}` : err.message))
+  sock.on("close", () => close())
+}
+
+function tunnelData(buf) {
+  if (buf[0] !== FRAME_DATA) return
+  const idLen = buf[1]
+  const tunnelId = buf.subarray(2, 2 + idLen).toString()
+  tunnels.get(tunnelId)?.write(buf.subarray(2 + idLen))
+}
+
+/** `node`, `python3`, `code-server`… — argv[0]'s basename; `comm` can be a thread name ("MainThread"). */
+function processName(pid) {
+  try {
+    const argv = readFileSync(`/proc/${pid}/cmdline`, "utf8").split("\0").filter(Boolean)
+    // `node /usr/lib/code-server/out/node/entry.js` says more as "code-server" than as "node".
+    const script = argv.slice(1).find((a) => !a.startsWith("-"))
+    if (script?.includes("code-server")) return "code-server"
+    if (argv[0]) return argv[0].split("/").pop()
+  } catch {}
+  try {
+    return readFileSync(`/proc/${pid}/comm`, "utf8").trim()
+  } catch {
+    return undefined
+  }
+}
+
+/** What listens on TCP inside the box, with the process when it can be told: /proc, no `ss` needed. */
+function listeningPorts() {
+  const byInode = new Map()
+  for (const file of ["/proc/net/tcp", "/proc/net/tcp6"]) {
+    let text = ""
+    try {
+      text = readFileSync(file, "utf8")
+    } catch {
+      continue
+    }
+    for (const line of text.split("\n").slice(1)) {
+      const f = line.trim().split(/\s+/)
+      if (f.length < 10 || f[3] !== "0A") continue // LISTEN
+      const port = parseInt(f[1].split(":")[1], 16)
+      byInode.set(f[9], port)
+    }
+  }
+  const procs = new Map()
+  for (const pid of readdirSync("/proc").filter((d) => /^\d+$/.test(d))) {
+    let fds = []
+    try {
+      fds = readdirSync(`/proc/${pid}/fd`)
+    } catch {
+      continue
+    }
+    for (const fd of fds) {
+      let target = ""
+      try {
+        target = readlinkSync(`/proc/${pid}/fd/${fd}`)
+      } catch {
+        continue
+      }
+      const m = /^socket:\[(\d+)\]$/.exec(target)
+      if (m && byInode.has(m[1]) && !procs.has(m[1])) {
+        procs.set(m[1], processName(pid))
+      }
+    }
+  }
+  const ports = new Map()
+  for (const [inode, port] of byInode) if (!ports.has(port)) ports.set(port, procs.get(inode))
+  return [...ports].sort((a, b) => a[0] - b[0]).map(([port, process]) => ({ port, ...(process ? { process } : {}) }))
+}
+
+// ── connection ────────────────────────────────────────────────────────────────
+function handle(msg) {
+  switch (msg.type) {
+    case "welcome":
+      backoff = 1000
+      resumed = false
+      console.log(`[sandbox-agent] connected as sandbox ${msg.sandboxId}`)
+      heartbeat()
+      return
+    case "ping":
+      send({ type: "pong", at: msg.at })
+      return
+    case "project":
+      return applyProject(msg)
+    case "exec":
+      return runExec(msg)
+    case "exec_cancel":
+      execs.get(msg.id)?.kill("SIGKILL")
+      return
+    case "term_open":
+      return msg.mode === "logs" ? openLogs(msg) : openTerminal(msg)
+    case "sessions": {
+      const sessions = msg.op === "create" ? createSession(msg.name) : msg.op === "kill" ? killSession(msg.name) : listSessions()
+      send({ type: "reply", id: msg.id, result: sessions })
+      return
+    }
+    case "term_input":
+      terminals.get(msg.termId)?.stdin.write(Buffer.from(msg.data, "base64"))
+      return
+    case "term_resize": {
+      const t = terminals.get(msg.termId)
+      const cols = Math.max(Number(msg.cols) || 0, 20)
+      const rows = Math.max(Number(msg.rows) || 0, 5)
+      if (t?.stdio[3]) t.stdio[3].write(`${cols} ${rows}\n`)
+      else if (t) resizeScriptPty(t.pid, cols, rows)
+      return
+    }
+    case "term_close":
+      terminals.get(msg.termId)?.kill("SIGHUP")
+      terminals.delete(msg.termId)
+      return
+    case "tunnel_open":
+      return openTunnel(msg)
+    case "tunnel_close":
+      tunnels.get(msg.tunnelId)?.destroy()
+      tunnels.delete(msg.tunnelId)
+      return
+    case "ports":
+      send({ type: "reply", id: msg.id, result: listeningPorts() })
+      return
+  }
+}
+
+function connect() {
+  const sock = (ws = new WebSocket(CONNECT_URL))
+  wsDialedAt = uptime()
+  ws.binaryType = "arraybuffer"
+  ws.addEventListener("open", () => send({ type: "hello", token: TOKEN, info: info() }))
+  ws.addEventListener("message", (ev) => {
+    // A socket given up on after a resume (see SIGUSR1) may still deliver late: not ours anymore.
+    if (ws !== sock) return
+    lastMessageAt = Date.now()
+    if (typeof ev.data !== "string") return tunnelData(Buffer.from(ev.data))
+    let msg
+    try {
+      msg = JSON.parse(ev.data)
+    } catch {
+      return
+    }
+    try {
+      handle(msg)
+    } catch (err) {
+      console.error("[sandbox-agent] handler failed:", err)
+    }
+  })
+  ws.addEventListener("close", (ev) => {
+    if (ws !== sock) return
+    dropSessions()
+    if (ev.code === 4401) console.error("[sandbox-agent] token refused")
+    // The sandbox is stopped (a sleep, on some providers, that has not frozen us yet): ask again
+    // every few seconds rather than backing off to 30 s — a start should find us in at once.
+    if (ev.code === 4409) return void (reconnect = setTimeout(connect, 3_000))
+    const wait = resumed ? 0 : Math.min(backoff, 30_000) * (0.5 + Math.random())
+    resumed = false
+    backoff = Math.min(backoff * 2, 30_000)
+    reconnect = setTimeout(connect, wait)
+  })
+  ws.addEventListener("error", () => {})
+}
+
+/** What lives on a connection ends with it: terminals detach (dtach keeps the shell), tunnels close. */
+function dropSessions() {
+  for (const child of terminals.values()) child.kill("SIGHUP")
+  terminals.clear()
+  for (const t of tunnels.values()) t.destroy()
+  tunnels.clear()
+}
+
+// The box was frozen and comes back (a RAM snapshot loaded, RFC 0039). Its provider says so with
+// SIGUSR1, to the pid it asked us to write (SPUNTO_AGENT_PIDFILE) — never `pkill -f`, which would
+// hit any process with "agent.mjs" on its command line. Then:
+// - socket open: it may be dead (the platform let it go) or alive (a short stop). A `probe`, which
+//   the platform acks, tells: nothing back within 1.5 s and the socket is given up for a new one.
+//   Waiting for TCP to notice took 6 s after an 8 s stop (no RST through the tunnel, the peer's
+//   retransmission instead). Only a socket that heard nothing since the signal is dropped: the
+//   first version dropped blindly, and cut a connection already re-made with the exec just sent on it;
+// - socket closed, a reconnect waiting out its backoff (up to ~45 s): dial now;
+// - socket connecting: nothing to do.
+// The "skip the backoff" only holds for a few seconds: a later, unrelated drop backs off as usual.
+let resumed = false
+let resumedTimer = null
+let reconnect = null
+let lastMessageAt = 0
+// When the current socket was dialed, on the box's own clock (/proc/uptime: it stops while the box is
+// frozen, like the provider's record of the resume).
+let wsDialedAt = 0
+function uptime() {
+  try {
+    return Number(readFileSync("/proc/uptime", "utf8").split(" ")[0])
+  } catch {
+    return 0
+  }
+}
+// SIGUSR2: frozen, and the platform let this connection go when it stopped the box (RFC 0039 § 4.4)
+// — a probe on it would only wait out its 1.5 s. A socket dialed before the resume (the provider
+// writes when, SPUNTO_AGENT_RESUMED_FILE) is dropped and a new one dialed now. One dialed since —
+// this agent already reconnected on its own — is the right one: probed, never cut.
+process.on("SIGUSR2", () => {
+  // A fork: this is now another sandbox, its token in the env file the provider rewrote. A new
+  // connection under it, at once; every process of the box stays (terminals, services, the setup).
+  const forked = newIdentity()
+  if (forked) {
+    console.log(`[sandbox-agent] forked: now sandbox ${forked.SPUNTO_SANDBOX_ID ?? "?"}, dialing under its identity`)
+    const before = process.env.SPUNTO_SANDBOX_ID ?? ""
+    TOKEN = forked.SPUNTO_SANDBOX_TOKEN
+    process.env.SPUNTO_SANDBOX_ID = forked.SPUNTO_SANDBOX_ID ?? before
+    // What the commands it starts from now on see: this sandbox's id, not the source's. (The
+    // processes already running keep the env they were started with.)
+    for (const env of [baseEnv, childEnv]) {
+      if (env.SPUNTO_SANDBOX_ID) env.SPUNTO_SANDBOX_ID = process.env.SPUNTO_SANDBOX_ID
+    }
+    const sock = ws
+    dropSessions()
+    clearTimeout(reconnect)
+    resumed = false
+    connect()
+    try {
+      sock?.close()
+    } catch {}
+    return
+  }
+  let resumedAt = NaN
+  try {
+    resumedAt = Number(readFileSync(process.env.SPUNTO_AGENT_RESUMED_FILE ?? "", "utf8").trim())
+  } catch {}
+  if (Number.isNaN(resumedAt) || (ws && ws.readyState !== WebSocket.CLOSED && wsDialedAt > resumedAt)) return onResume()
+  console.log("[sandbox-agent] resumed, the platform dropped the connection: dialing now")
+  const sock = ws
+  dropSessions()
+  clearTimeout(reconnect)
+  resumed = false
+  connect()
+  try {
+    sock?.close()
+  } catch {}
+})
+
+/** The env file's token when it is not ours any more (`K='v'` lines, as the provider writes them). */
+function newIdentity() {
+  const file = process.env.SPUNTO_AGENT_ENV_FILE
+  if (!file) return null
+  let text = ""
+  try {
+    text = readFileSync(file, "utf8")
+  } catch {
+    return null
+  }
+  const env = {}
+  for (const line of text.split("\n")) {
+    const m = /^([A-Za-z_][A-Za-z0-9_]*)='(.*)'$/.exec(line)
+    if (m) env[m[1]] = m[2].replace(/'\\''/g, "'")
+  }
+  return env.SPUNTO_SANDBOX_TOKEN && env.SPUNTO_SANDBOX_TOKEN !== TOKEN ? env : null
+}
+
+process.on("SIGUSR1", () => onResume())
+function onResume() {
+  console.log("[sandbox-agent] resumed: checking the connection")
+  resumed = true
+  clearTimeout(resumedTimer)
+  resumedTimer = setTimeout(() => (resumed = false), 5_000)
+  if (ws?.readyState === WebSocket.OPEN) {
+    const sock = ws
+    const at = Date.now()
+    send({ type: "probe", id: at })
+    heartbeat()
+    setTimeout(() => {
+      if (ws !== sock || lastMessageAt >= at) return
+      console.log("[sandbox-agent] no answer after the resume: reconnecting")
+      resumed = false
+      dropSessions()
+      connect()
+      try {
+        sock.close()
+      } catch {}
+    }, 1_500)
+    return
+  }
+  if (ws?.readyState === WebSocket.CONNECTING) return
+  // Dialing now is the shortcut: if this one fails too, the backoff applies.
+  resumed = false
+  clearTimeout(reconnect)
+  connect()
+}
+// After the handler: a SIGUSR1 before it is in place would start Node's inspector instead.
+if (process.env.SPUNTO_AGENT_PIDFILE) {
+  try {
+    writeFileSync(process.env.SPUNTO_AGENT_PIDFILE, `${process.pid}\n`)
+    // What this agent understands, for a provider choosing between them (an older agent: USR1 only).
+    if (process.env.SPUNTO_AGENT_SIGNALS_FILE) writeFileSync(process.env.SPUNTO_AGENT_SIGNALS_FILE, "USR1 USR2 REIDENTIFY\n")
+  } catch (err) {
+    console.error(`[sandbox-agent] cannot write ${process.env.SPUNTO_AGENT_PIDFILE}: ${err.message}`)
+  }
+}
+
+setInterval(heartbeat, 15_000).unref()
+if (hasBalloon && process.getuid?.() === 0 && process.env.SPUNTO_RECLAIM_CACHE !== "0") setInterval(reclaimColdCache, 60_000).unref()
+console.log(`[sandbox-agent] ${VERSION} → ${API} (shell ${SHELL}, cwd ${CWD})`)
+connect()