@sema-agent/server 1.185.0

package/dist/plugins/remote-env-k8s.js

@@ -0,0 +1,1206 @@
+import path from "node:path";
+import { readFileSync } from "node:fs";
+import https from "node:https";
+import http from "node:http";
+import { StringDecoder } from "node:string_decoder";
+import WebSocket from "ws";
+import { shellQuote, kindFromMode } from "./remote-shell.js";
+import { presignS3Url } from "./s3-presign.js";
+import { FileError, ExecutionError, RemoteExecutionError, withRetry, RollingTailBuffer, markTruncated, } from "@sema-agent/core";
+import { randomUUID } from "node:crypto";
+import { BackgroundShellManager, seedMemStream, feedMemStream, drainMemStream } from "./background-shell-support.js";
+const PROVIDER = "k8s";
+const K8S_BG_DIR_ROOT = "/tmp/.sema-bg";
+const K8S_BG_MAX_CONCURRENT = Math.max(1, Math.floor(Number(process.env.K8S_BG_MAX_CONCURRENT ?? "")) || 8);
+const K8S_BG_DEFAULT_TIMEOUT_SEC = Math.max(1, Math.floor(Number(process.env.K8S_BG_DEFAULT_TIMEOUT_SEC ?? "")) || 300);
+const K8S_BG_MAX_TIMEOUT_SEC = Math.max(K8S_BG_DEFAULT_TIMEOUT_SEC, Math.floor(Number(process.env.K8S_BG_MAX_TIMEOUT_SEC ?? "")) || 1800);
+const K8S_BG_READ_CAP = Math.max(64 * 1024, Math.floor(Number(process.env.K8S_BG_READ_CAP ?? "")) || 1024 * 1024);
+const K8S_BG_FILE_CAP = Math.max(K8S_BG_READ_CAP, Math.floor(Number(process.env.K8S_BG_FILE_CAP ?? "")) || 64 * 1024 * 1024);
+const K8S_BG_MEM_CAP = Math.max(64 * 1024, Math.floor(Number(process.env.K8S_BG_MEM_CAP ?? "")) || 8 * 1024 * 1024);
+export function buildBgRunnerScript(dir) {
+    const q = (name) => shellQuote(`${dir}/${name}`);
+    return [
+        `echo $$ > ${q("pgid.tmp")} 2>/dev/null && mv ${q("pgid.tmp")} ${q("pgid")} 2>/dev/null`,
+        `sh ${q("cmd.sh")} > ${q("out")} 2> ${q("err")} < /dev/null`,
+        `__RC=$?`,
+        `echo $__RC > ${q("exit.tmp")} 2>/dev/null && mv ${q("exit.tmp")} ${q("exit")} 2>/dev/null`,
+    ].join("\n");
+}
+export function buildBgLauncherScript(dir, cmdShB64, runnerShB64) {
+    const d = shellQuote(dir);
+    const q = (name) => shellQuote(`${dir}/${name}`);
+    return [
+        `mkdir -p ${d} && chmod 700 ${d}`,
+        `printf %s '${cmdShB64}' | base64 -d > ${q("cmd.sh")}`,
+        `printf %s '${runnerShB64}' | base64 -d > ${q("runner.sh")}`,
+        `setsid sh ${q("runner.sh")} >/dev/null 2>&1 &`,
+        `__i=0; while [ ! -s ${q("pgid")} ] && [ $__i -lt 40 ]; do __i=$((__i+1)); sleep 0.05; done`,
+        `if [ -s ${q("pgid")} ]; then echo SEMABG_LAUNCHED; else echo SEMABG_NOPGID; fi`,
+    ].join("\n");
+}
+export function buildBgPollScript(dir, stdoutCursor, stderrCursor, readCap) {
+    const d = shellQuote(dir);
+    const slice = (file, cursor) => [
+        `__N=$((__T - ${cursor}))`,
+        `if [ "$__N" -gt 0 ]; then`,
+        `  if [ "$__N" -le ${readCap} ]; then tail -c +$(( ${cursor} + 1 )) ${d}/${file} 2>/dev/null | head -c "$__N" | base64;`,
+        `  else tail -c +$(( __T - ${readCap} + 1 )) ${d}/${file} 2>/dev/null | head -c ${readCap} | base64; fi`,
+        `fi`,
+    ].join("\n");
+    return [
+        `if [ ! -d ${d} ]; then echo SEMABG_GONE; exit 0; fi`,
+        `__OT=$(wc -c < ${d}/out 2>/dev/null); __OT=$(( \${__OT:-0} + 0 ))`,
+        `__ET=$(wc -c < ${d}/err 2>/dev/null); __ET=$(( \${__ET:-0} + 0 ))`,
+        `__EX=$( [ -f ${d}/exit ] && cat ${d}/exit 2>/dev/null || echo - )`,
+        `__PG=$(cat ${d}/pgid 2>/dev/null); __PG=\${__PG:--}`,
+        `if [ "$__PG" = "-" ]; then __AL=1; elif kill -0 -"$__PG" 2>/dev/null; then __AL=1; else __AL=0; fi`,
+        `echo "SEMABG_META o=$__OT e=$__ET x=$__EX a=$__AL"`,
+        `echo SEMABG_O`,
+        `__T=$__OT`,
+        slice("out", stdoutCursor),
+        `echo SEMABG_E`,
+        `__T=$__ET`,
+        slice("err", stderrCursor),
+        `echo SEMABG_X`,
+    ].join("\n");
+}
+export function buildBgKillScript(dir) {
+    const d = shellQuote(dir);
+    return [
+        `__i=0; while [ ! -s ${d}/pgid ] && [ $__i -lt 40 ]; do __i=$((__i+1)); sleep 0.05; done`,
+        `__PG=$(cat ${d}/pgid 2>/dev/null); __PG=\${__PG:--}`,
+        `if [ "$__PG" != "-" ]; then kill -TERM -"$__PG" 2>/dev/null || kill -TERM "$__PG" 2>/dev/null; sleep 1; kill -KILL -"$__PG" 2>/dev/null || kill -KILL "$__PG" 2>/dev/null; fi`,
+        `echo SEMABG_KILLED`,
+    ].join("\n");
+}
+export function buildBgDisposeScript(dir) {
+    const d = shellQuote(dir);
+    return [
+        `__PG=$(cat ${d}/pgid 2>/dev/null); __PG=\${__PG:--}`,
+        `if [ "$__PG" != "-" ]; then kill -KILL -"$__PG" 2>/dev/null || kill -KILL "$__PG" 2>/dev/null; fi`,
+        `rm -rf ${d} 2>/dev/null`,
+        `echo SEMABG_DISPOSED`,
+    ].join("\n");
+}
+export function buildDetachCapableExec(dir, command) {
+    const d = shellQuote(dir);
+    const q = (name) => shellQuote(`${dir}/${name}`);
+    const cmdB64 = Buffer.from(command, "utf8").toString("base64");
+    const writePgid = (val) => `printf %s ${val} > ${q("pgid.tmp")} 2>/dev/null && mv ${q("pgid.tmp")} ${q("pgid")} 2>/dev/null`;
+    return [
+        `__cmd=$(printf %s '${cmdB64}' | base64 -d)`,
+        `mkdir -p ${d} 2>/dev/null`,
+        `trap 'rm -rf ${d} 2>/dev/null' EXIT`,
+        `if command -v setsid >/dev/null 2>&1; then`,
+        `  setsid sh -c "$__cmd" &`,
+        `  __pg=$!`,
+        `  ${writePgid('"$__pg"')}`,
+        `  wait "$__pg"; __rc=$?`,
+        `else`,
+        `  ${writePgid('"$$"')}`,
+        `  sh -c "$__cmd"; __rc=$?`,
+        `fi`,
+        `exit $__rc`,
+    ].join("\n");
+}
+export function parseBgPollOutput(raw) {
+    if (raw.includes("SEMABG_GONE")) {
+        return { gone: true, outTotal: 0, errTotal: 0, alive: false, stdout: "", stdoutBytes: 0, stderr: "", stderrBytes: 0 };
+    }
+    const lines = raw.split("\n");
+    const metaIdx = lines.findIndex((l) => l.startsWith("SEMABG_META "));
+    if (metaIdx < 0)
+        return undefined;
+    const oIdx = lines.indexOf("SEMABG_O", metaIdx + 1);
+    const eIdx = oIdx >= 0 ? lines.indexOf("SEMABG_E", oIdx + 1) : -1;
+    const xIdx = eIdx >= 0 ? lines.indexOf("SEMABG_X", eIdx + 1) : -1;
+    if (oIdx < 0 || eIdx < 0 || xIdx < 0)
+        return undefined;
+    const m = /o=(\d+) e=(\d+) x=(\S+) a=([01])/.exec(lines[metaIdx].slice("SEMABG_META ".length));
+    if (!m)
+        return undefined;
+    const outTotal = parseInt(m[1], 10);
+    const errTotal = parseInt(m[2], 10);
+    const exTok = m[3];
+    const alive = m[4] === "1";
+    const exitParsed = exTok === "-" ? NaN : parseInt(exTok, 10);
+    const exitCode = Number.isFinite(exitParsed) ? exitParsed : undefined;
+    const decode = (from, to) => {
+        const b64 = lines.slice(from, to).join("").replace(/\s+/g, "");
+        const buf = Buffer.from(b64, "base64");
+        return { text: buf.toString("utf8"), bytes: buf.length };
+    };
+    const o = decode(oIdx + 1, eIdx);
+    const e = decode(eIdx + 1, xIdx);
+    return {
+        gone: false,
+        outTotal,
+        errTotal,
+        ...(exitCode !== undefined ? { exitCode } : {}),
+        alive,
+        stdout: o.text,
+        stdoutBytes: o.bytes,
+        stderr: e.text,
+        stderrBytes: e.bytes,
+    };
+}
+const ok = (value) => ({ ok: true, value });
+const unsupported = (op) => ({
+    ok: false,
+    error: new RemoteExecutionError("unsupported", `${op} is not supported on a Kata pod sandbox (no managed memory snapshot — capabilities.suspendable=false; durable suspend degrades to checkpoint + cold rebuild)`),
+});
+const SA_DIR = "/var/run/secrets/kubernetes.io/serviceaccount";
+const EXEC_SUBPROTOCOLS = ["v5.channel.k8s.io", "v4.channel.k8s.io"];
+const WRITE_CHUNK_BYTES = 64 * 1024;
+export function applyPodSpecPatch(pod, patch) {
+    assertHardeningOnly(patch.podSecurityContext, "podSecurityContext");
+    assertHardeningOnly(patch.containerSecurityContext, "containerSecurityContext");
+    if (patch.labels) {
+        const identity = {};
+        for (const k of ["app", "managed-by"]) {
+            const v = pod.metadata.labels?.[k];
+            if (v !== undefined)
+                identity[k] = v;
+        }
+        pod.metadata.labels = { ...pod.metadata.labels, ...patch.labels, ...identity };
+    }
+    const spec = pod.spec;
+    assertVolumesPodLocal(patch.volumes, "volumes");
+    if (patch.volumes?.length)
+        spec.volumes = [...(spec.volumes ?? []), ...patch.volumes];
+    if (patch.podSecurityContext)
+        spec.securityContext = { ...(spec.securityContext ?? {}), ...patch.podSecurityContext };
+    const container = spec.containers?.[0];
+    if (container) {
+        if (patch.volumeMounts?.length)
+            container.volumeMounts = [...(container.volumeMounts ?? []), ...patch.volumeMounts];
+        if (patch.containerSecurityContext)
+            container.securityContext = { ...(container.securityContext ?? {}), ...patch.containerSecurityContext };
+    }
+}
+function assertHardeningOnly(sc, where) {
+    if (!sc)
+        return;
+    const bad = (msg) => {
+        throw new Error(`podSpecPatch.${where} rejected — it may only HARDEN, never weaken isolation: ${msg}`);
+    };
+    if (sc.privileged === true)
+        bad("privileged:true");
+    if (sc.allowPrivilegeEscalation === true)
+        bad("allowPrivilegeEscalation:true");
+    if (sc.readOnlyRootFilesystem === false)
+        bad("readOnlyRootFilesystem:false");
+    if (sc.runAsNonRoot === false)
+        bad("runAsNonRoot:false");
+    if (sc.runAsUser === 0)
+        bad("runAsUser:0 (root)");
+    const caps = sc.capabilities;
+    if (caps && Array.isArray(caps.add) && caps.add.length > 0)
+        bad(`capabilities.add ${JSON.stringify(caps.add)} (a hardening patch may only .drop)`);
+    if (sc.procMount === "Unmasked")
+        bad('procMount:"Unmasked" (re-exposes masked /proc)');
+    const seccomp = sc.seccompProfile;
+    if (seccomp && seccomp.type === "Unconfined")
+        bad('seccompProfile.type:"Unconfined" (disables syscall filtering)');
+}
+function assertVolumesPodLocal(volumes, where) {
+    if (!volumes?.length)
+        return;
+    const POD_LOCAL = new Set(["emptyDir", "configMap", "secret", "projected", "downwardAPI", "ephemeral"]);
+    for (const v of volumes) {
+        const vol = v;
+        const sources = Object.keys(vol).filter((k) => k !== "name");
+        for (const src of sources) {
+            if (!POD_LOCAL.has(src)) {
+                throw new Error(`podSpecPatch.${where} rejected — volume source ${JSON.stringify(src)} is not pod-local (host-backed sources like hostPath/csi/flexVolume cross the Kata VM boundary into the node FS). Allowed: ${[...POD_LOCAL].join("/")}`);
+            }
+        }
+    }
+}
+export function execSocketTlsOptions(ca, insecureTls) {
+    const caList = ca ? [ca] : undefined;
+    return { ca: caList, rejectUnauthorized: !insecureTls, tls: { ca: caList, rejectUnauthorized: !insecureTls } };
+}
+export function errorMessageOf(e) {
+    if (e instanceof Error)
+        return e.message;
+    const m = e?.message;
+    return typeof m === "string" && m ? m : String(e);
+}
+export function exitCodeFromStatus(statusJson) {
+    try {
+        const s = JSON.parse(statusJson);
+        if (s.status === "Success")
+            return { exitCode: 0 };
+        const cause = s.details?.causes?.find((c) => c.reason === "ExitCode");
+        if (cause?.message?.trim()) {
+            const code = Number(cause.message);
+            if (Number.isFinite(code))
+                return { exitCode: code };
+        }
+        return { error: s.message || s.reason || "exec failed without an exit code" };
+    }
+    catch {
+        return { error: `unparseable exec status: ${statusJson.slice(0, 200)}` };
+    }
+}
+export class RemoteK8sExecutionEnv {
+    capabilities;
+    cwd;
+    podName;
+    podIP;
+    destroyed = false;
+    handleSnapshotId;
+    inFlightExecs = 0;
+    connectPromise;
+    cfg;
+    deps;
+    constructor(config, deps) {
+        this.cfg = {
+            apiUrl: config.apiUrl,
+            token: config.token,
+            caCert: config.caCert,
+            insecureTls: config.insecureTls ?? false,
+            namespace: config.namespace ?? "sandboxes",
+            image: config.image,
+            runtimeClass: config.runtimeClass ?? "kata-qemu",
+            mountPath: config.mountPath ?? "/workspace",
+            timeoutMs: config.timeoutMs ?? 30 * 60_000,
+            readyTimeoutMs: config.readyTimeoutMs ?? 120_000,
+            rpcTimeoutMs: config.rpcTimeoutMs ?? 30_000,
+            livenessMs: config.livenessMs ?? 120_000,
+            dataTimeoutMs: config.dataTimeoutMs ?? 5 * 60_000,
+            cpu: config.cpu ?? "1",
+            memory: config.memory ?? "2Gi",
+            retry: { maxAttempts: config.retry?.maxAttempts ?? 3, backoffMs: config.retry?.backoffMs ?? 1000 },
+            ...(config.s3Snapshot ? { s3Snapshot: config.s3Snapshot } : {}),
+            ...(config.sessionId ? { sessionId: config.sessionId } : {}),
+            ...(config.podSpecPatch ? { podSpecPatch: config.podSpecPatch } : {}),
+            ...(config.podEnv ? { podEnv: config.podEnv } : {}),
+        };
+        this.cwd = this.cfg.mountPath;
+        this.deps = deps ?? {};
+        this.capabilities = { isolation: true, suspendable: !!this.cfg.s3Snapshot };
+        const bgMax = Math.max(1, Math.min(K8S_BG_MAX_TIMEOUT_SEC, Math.floor(this.cfg.timeoutMs / 1000)));
+        this.backgroundCapabilities = {
+            supported: true,
+            maxConcurrent: K8S_BG_MAX_CONCURRENT,
+            defaultBgTimeoutSec: Math.min(K8S_BG_DEFAULT_TIMEOUT_SEC, bgMax),
+            maxBgTimeoutSec: bgMax,
+            supportsDetach: true,
+        };
+    }
+    resolve(p) {
+        return path.posix.isAbsolute(p) ? path.posix.normalize(p) : path.posix.normalize(path.posix.join(this.cwd, p));
+    }
+    workspaceHandle() {
+        return { sandboxId: this.podName ?? "(unconnected)", provider: PROVIDER, mountPath: this.cwd, ...(this.handleSnapshotId ? { snapshotId: this.handleSnapshotId } : {}) };
+    }
+    creds() {
+        const apiUrl = this.cfg.apiUrl ??
+            (process.env.KUBERNETES_SERVICE_HOST ? `https://${process.env.KUBERNETES_SERVICE_HOST}:${process.env.KUBERNETES_SERVICE_PORT ?? "443"}` : undefined);
+        if (!apiUrl)
+            throw new RemoteExecutionError("connect_failed", "no k8s API: set K8S_API_URL or run in-cluster");
+        let token = this.cfg.token;
+        let ca = this.cfg.caCert;
+        if (!token) {
+            try {
+                token = readFileSync(`${SA_DIR}/token`, "utf8").trim();
+            }
+            catch {
+                throw new RemoteExecutionError("auth_failed", "no k8s token: set K8S_TOKEN or run in-cluster with a service account");
+            }
+        }
+        if (!ca && !this.cfg.insecureTls) {
+            try {
+                ca = readFileSync(`${SA_DIR}/ca.crt`, "utf8");
+            }
+            catch {
+                throw new RemoteExecutionError("auth_failed", "no k8s CA: set K8S_CA_CERT_B64, K8S_INSECURE_TLS=true (lab), or run in-cluster");
+            }
+        }
+        return { apiUrl: apiUrl.replace(/\/+$/, ""), token, ca };
+    }
+    async request(method, apiPath, body, opts) {
+        if (this.deps.request)
+            return this.deps.request(method, apiPath, body, opts);
+        const { apiUrl, token, ca } = this.creds();
+        const url = new URL(apiUrl + apiPath);
+        const isHttps = url.protocol === "https:";
+        const payload = body === undefined ? undefined : JSON.stringify(body);
+        return new Promise((resolvePromise, rejectPromise) => {
+            const req = (isHttps ? https : http).request({
+                method,
+                hostname: url.hostname,
+                port: url.port || (isHttps ? 443 : 80),
+                path: url.pathname + url.search,
+                headers: {
+                    authorization: `Bearer ${token}`,
+                    accept: "application/json",
+                    ...(payload ? { "content-type": "application/json", "content-length": Buffer.byteLength(payload) } : {}),
+                },
+                ...(isHttps ? { ca: ca ? [ca] : undefined, rejectUnauthorized: !this.cfg.insecureTls } : {}),
+                timeout: opts?.timeoutMs ?? this.cfg.rpcTimeoutMs,
+                signal: opts?.signal,
+            }, (res) => {
+                const bufs = [];
+                res.on("data", (d) => bufs.push(d));
+                res.on("end", () => {
+                    const text = Buffer.concat(bufs).toString("utf8");
+                    let json = undefined;
+                    try {
+                        json = text ? JSON.parse(text) : undefined;
+                    }
+                    catch {
+                        json = { raw: text.slice(0, 500) };
+                    }
+                    resolvePromise({ status: res.statusCode ?? 0, json });
+                });
+            });
+            req.on("timeout", () => {
+                req.destroy(new Error(`k8s API ${method} ${apiPath} timed out`));
+            });
+            req.on("error", (e) => rejectPromise(e));
+            if (payload)
+                req.write(payload);
+            req.end();
+        });
+    }
+    openExec(url, headers) {
+        if (this.deps.openExec)
+            return this.deps.openExec(url, headers);
+        const { ca } = this.creds();
+        return new WebSocket(url, EXEC_SUBPROTOCOLS, {
+            headers,
+            ...(url.startsWith("wss:") ? execSocketTlsOptions(ca, this.cfg.insecureTls) : {}),
+        });
+    }
+    async connect(config) {
+        const policy = {
+            retryableCodes: ["connect_failed", "timeout", "transport_lost"],
+            maxAttempts: this.cfg.retry.maxAttempts,
+            backoffMs: (failed) => this.cfg.retry.backoffMs * failed,
+        };
+        const once = this.deps.connectOnce ?? ((s) => this.connectOnce(s));
+        return withRetry(() => once(config?.abortSignal), policy, { signal: config?.abortSignal });
+    }
+    async ensureConnected() {
+        if (this.podName)
+            return ok(undefined);
+        if (this.destroyed)
+            return { ok: false, error: new ExecutionError("shell_unavailable", "k8s sandbox destroyed") };
+        this.connectPromise ??= this.connect();
+        const r = await this.connectPromise;
+        if (!r.ok) {
+            this.connectPromise = undefined;
+            return { ok: false, error: new ExecutionError("shell_unavailable", `k8s sandbox connect failed: ${r.error.message}`, r.error) };
+        }
+        return ok(undefined);
+    }
+    async connectOnce(signal) {
+        if (signal?.aborted)
+            return { ok: false, error: new RemoteExecutionError("aborted", "connect aborted") };
+        if (this.destroyed)
+            return { ok: false, error: new RemoteExecutionError("connect_failed", "env already destroyed") };
+        const ns = this.cfg.namespace;
+        const pod = {
+            apiVersion: "v1",
+            kind: "Pod",
+            metadata: {
+                generateName: "sbx-",
+                labels: { app: "sema-sandbox", "managed-by": "sema-server" },
+            },
+            spec: {
+                ...(this.cfg.runtimeClass ? { runtimeClassName: this.cfg.runtimeClass } : {}),
+                restartPolicy: "Never",
+                automountServiceAccountToken: false,
+                activeDeadlineSeconds: Math.ceil(this.cfg.timeoutMs / 1000),
+                terminationGracePeriodSeconds: 1,
+                containers: [
+                    {
+                        name: "sandbox",
+                        image: this.cfg.image,
+                        command: this.cfg.podEnv?.SEMA_PKG_SOURCE
+                            ? ["sh", "-c", "[ -f /opt/sema/pkg-source.sh ] && sh /opt/sema/pkg-source.sh || true; sleep infinity"]
+                            : ["sh", "-c", "sleep infinity"],
+                        ...(this.cfg.podEnv && Object.keys(this.cfg.podEnv).length > 0
+                            ? { env: Object.entries(this.cfg.podEnv).map(([name, value]) => ({ name, value: String(value) })) }
+                            : {}),
+                        resources: { limits: { cpu: this.cfg.cpu, memory: this.cfg.memory } },
+                    },
+                ],
+            },
+        };
+        if (this.cfg.podSpecPatch)
+            applyPodSpecPatch(pod, this.cfg.podSpecPatch);
+        let created;
+        try {
+            created = await this.request("POST", `/api/v1/namespaces/${ns}/pods`, pod, { signal });
+        }
+        catch (e) {
+            return { ok: false, error: new RemoteExecutionError("connect_failed", `pod create RPC failed: ${e instanceof Error ? e.message : String(e)}`, e instanceof Error ? e : undefined) };
+        }
+        if (created.status === 401 || created.status === 403) {
+            return { ok: false, error: new RemoteExecutionError("auth_failed", `pod create denied (${created.status}): ${JSON.stringify(created.json).slice(0, 200)}`) };
+        }
+        if (created.status >= 300) {
+            return { ok: false, error: new RemoteExecutionError("connect_failed", `pod create failed (${created.status}): ${JSON.stringify(created.json).slice(0, 300)}`) };
+        }
+        const name = created.json?.metadata?.name;
+        if (!name)
+            return { ok: false, error: new RemoteExecutionError("connect_failed", "pod create returned no name") };
+        const deadline = Date.now() + this.cfg.readyTimeoutMs;
+        let podIP;
+        for (;;) {
+            if (signal?.aborted) {
+                await this.deletePod(name).catch(() => { });
+                return { ok: false, error: new RemoteExecutionError("aborted", "connect aborted") };
+            }
+            let got;
+            try {
+                got = await this.request("GET", `/api/v1/namespaces/${ns}/pods/${name}`, undefined, { signal });
+            }
+            catch (e) {
+                await this.deletePod(name).catch(() => { });
+                return { ok: false, error: new RemoteExecutionError("connect_failed", `pod status RPC failed: ${e instanceof Error ? e.message : String(e)}`, e instanceof Error ? e : undefined) };
+            }
+            const status = got.json?.status;
+            const phase = status?.phase;
+            if (phase === "Running") {
+                podIP = status?.podIP;
+                break;
+            }
+            if (phase === "Failed" || phase === "Succeeded") {
+                await this.deletePod(name).catch(() => { });
+                return { ok: false, error: new RemoteExecutionError("connect_failed", `pod entered ${phase} before Running (${status?.reason ?? "?"})`) };
+            }
+            const waiting = status?.containerStatuses?.[0]?.state?.waiting;
+            if (waiting?.reason === "ImagePullBackOff" || waiting?.reason === "ErrImagePull") {
+                await this.deletePod(name).catch(() => { });
+                return { ok: false, error: new RemoteExecutionError("connect_failed", `image pull failed for ${this.cfg.image}: ${waiting.message ?? waiting.reason}`) };
+            }
+            if (Date.now() > deadline) {
+                await this.deletePod(name).catch(() => { });
+                return { ok: false, error: new RemoteExecutionError("timeout", `pod not Running within ${this.cfg.readyTimeoutMs}ms (phase=${phase ?? "?"})`) };
+            }
+            await new Promise((r) => setTimeout(r, 1000));
+        }
+        if (this.destroyed) {
+            await this.deletePod(name).catch(() => { });
+            return { ok: false, error: new RemoteExecutionError("connect_failed", "env destroyed during connect") };
+        }
+        this.podName = name;
+        this.podIP = podIP;
+        const mk = await this.runExec(`mkdir -p ${shellQuote(this.cfg.mountPath)}`);
+        if (!mk.ok || mk.value.exitCode !== 0) {
+            await this.deletePod(name).catch(() => { });
+            this.podName = undefined;
+            this.podIP = undefined;
+            return { ok: false, error: new RemoteExecutionError("connect_failed", `workspace mkdir failed: ${mk.ok ? mk.value.stderr : mk.error.message}`) };
+        }
+        return ok(this.workspaceHandle());
+    }
+    presignSnapshot(method, snapshotId) {
+        const s3 = this.cfg.s3Snapshot;
+        const prefix = s3.keyPrefix ?? "kata";
+        const session = this.cfg.sessionId ?? "_";
+        const safe = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+        for (const [label, seg] of [["sessionId", session], ["snapshotId", snapshotId], ["keyPrefix", prefix]]) {
+            if (!safe.test(seg))
+                return { ok: false, error: new RemoteExecutionError("connect_failed", `unsafe snapshot key segment (${label}): refusing to build a traversing object key`) };
+        }
+        return {
+            ok: true,
+            value: presignS3Url({
+                endpoint: s3.endpoint,
+                bucket: s3.bucket,
+                key: `${prefix}/${session}/${snapshotId}.tar.gz`,
+                method,
+                accessKey: s3.accessKey,
+                secretKey: s3.secretKey,
+                ...(s3.region ? { region: s3.region } : {}),
+                expiresSec: Math.min(s3.presignTtlSec ?? 600, 3600),
+            }),
+        };
+    }
+    redactUrl(text, url) {
+        return text.split(url).join("<presigned-url>").replace(/X-Amz-Signature=[0-9a-f]+/gi, "X-Amz-Signature=<redacted>");
+    }
+    async suspendVM(_options) {
+        if (!this.cfg.s3Snapshot)
+            return unsupported("suspendVM");
+        if (this.inFlightExecs > 0)
+            return { ok: false, error: new RemoteExecutionError("command_in_flight", "cannot suspend while a command is in flight (would snapshot a torn workspace)") };
+        const snapshotId = `kata-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
+        if (!this.podName)
+            return ok(snapshotId);
+        const presigned = this.presignSnapshot("PUT", snapshotId);
+        if (!presigned.ok)
+            return presigned;
+        const url = presigned.value;
+        const tmp = "/tmp/ws-snap.tgz";
+        const cmd = `tar czf ${tmp} -C ${shellQuote(this.cfg.mountPath)} . && curl -fsS -X PUT -T ${tmp} ${shellQuote(url)}; ` +
+            `rc=$?; rm -f ${tmp}; exit $rc`;
+        const r = await this.runExec(cmd, { timeoutMs: this.cfg.dataTimeoutMs, livenessMs: 0 });
+        if (!r.ok)
+            return { ok: false, error: new RemoteExecutionError("connect_failed", `workspace snapshot upload failed: ${this.redactUrl(r.error.message, url)}`, r.error) };
+        if (r.value.exitCode !== 0)
+            return { ok: false, error: new RemoteExecutionError("connect_failed", `workspace snapshot upload exited ${r.value.exitCode}: ${this.redactUrl(r.value.stderr, url).slice(0, 300)}`) };
+        const name = this.podName;
+        this.podName = undefined;
+        this.podIP = undefined;
+        await this.deletePod(name).catch(() => { });
+        return ok(snapshotId);
+    }
+    async resumeVM(snapshotId, options) {
+        if (!this.cfg.s3Snapshot)
+            return unsupported("resumeVM");
+        const presigned = this.presignSnapshot("GET", snapshotId);
+        if (!presigned.ok)
+            return presigned;
+        const c = await this.connect({ abortSignal: options?.abortSignal });
+        if (!c.ok)
+            return c;
+        const url = presigned.value;
+        const cmd = `code=$(curl -s -o /tmp/ws.tgz -w '%{http_code}' ${shellQuote(url)}); ` +
+            `if [ "$code" = "404" ]; then echo EMPTY_SNAPSHOT; exit 0; fi; ` +
+            `if [ "$code" != "200" ]; then echo "snapshot GET HTTP $code" >&2; exit 22; fi; ` +
+            `tar xzf /tmp/ws.tgz -C ${shellQuote(this.cfg.mountPath)} && rm -f /tmp/ws.tgz`;
+        const r = await this.runExec(cmd, { timeoutMs: this.cfg.dataTimeoutMs, livenessMs: 0 });
+        if (!r.ok)
+            return { ok: false, error: new RemoteExecutionError("connect_failed", `workspace snapshot restore failed: ${this.redactUrl(r.error.message, url)}`, r.error) };
+        if (r.value.exitCode !== 0)
+            return { ok: false, error: new RemoteExecutionError("connect_failed", `workspace snapshot restore exited ${r.value.exitCode}: ${this.redactUrl(r.value.stderr, url).slice(0, 300)}`) };
+        this.handleSnapshotId = snapshotId;
+        return ok(this.workspaceHandle());
+    }
+    async postResumeInit() {
+        if (!this.cfg.s3Snapshot)
+            return unsupported("postResumeInit");
+        return ok(undefined);
+    }
+    async reconnect(_sessionToken) {
+        if (this.podName) {
+            const alive = await this.request("GET", `/api/v1/namespaces/${this.cfg.namespace}/pods/${this.podName}`).catch(() => undefined);
+            const phase = alive?.json?.status?.phase;
+            if (alive?.status === 200 && phase === "Running")
+                return ok(this.workspaceHandle());
+            this.podName = undefined;
+            this.podIP = undefined;
+        }
+        return this.connect();
+    }
+    async deletePod(name) {
+        await this.request("DELETE", `/api/v1/namespaces/${this.cfg.namespace}/pods/${name}?gracePeriodSeconds=0`, undefined, { timeoutMs: this.cfg.rpcTimeoutMs });
+    }
+    async destroy() {
+        await this.disposeBackgroundShells().catch(() => { });
+        this.destroyed = true;
+        const name = this.podName;
+        this.podName = undefined;
+        this.podIP = undefined;
+        if (name)
+            await this.deletePod(name).catch(() => { });
+    }
+    async cleanup() {
+        return this.destroy();
+    }
+    execUrl(command) {
+        const { apiUrl, token } = this.creds();
+        const base = apiUrl.replace(/^http/, "ws");
+        const q = new URLSearchParams();
+        q.append("container", "sandbox");
+        q.append("stdout", "true");
+        q.append("stderr", "true");
+        for (const part of ["sh", "-c", command])
+            q.append("command", part);
+        return { url: `${base}/api/v1/namespaces/${this.cfg.namespace}/pods/${this.podName}/exec?${q.toString()}`, headers: { authorization: `Bearer ${token}` } };
+    }
+    runExec(command, opts) {
+        let sock;
+        let headers;
+        let url;
+        try {
+            ({ url, headers } = this.execUrl(command));
+            sock = this.openExec(url, headers);
+        }
+        catch (e) {
+            return Promise.resolve({ ok: false, error: new ExecutionError("shell_unavailable", e instanceof Error ? e.message : String(e), e instanceof Error ? e : undefined) });
+        }
+        return new Promise((resolvePromise) => {
+            const boundOutput = !!opts?.boundOutput;
+            const outBufs = [];
+            const outTail = boundOutput ? new RollingTailBuffer() : undefined;
+            const errBuf = new RollingTailBuffer();
+            const outDecoder = opts?.onStdout ? new StringDecoder("utf8") : undefined;
+            const errDecoder = opts?.onStderr ? new StringDecoder("utf8") : undefined;
+            let statusFrame;
+            let settled = false;
+            let lastProgress = Date.now();
+            let spliceSink;
+            let sinkClosed = false;
+            let removeDetachListener;
+            const detachTee = opts?.detach?.tee;
+            const finish = (r) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(wallTimer);
+                clearTimeout(livenessTimer);
+                opts?.signal?.removeEventListener("abort", onAbort);
+                removeDetachListener?.();
+                try {
+                    (sock.terminate ?? sock.close).call(sock);
+                }
+                catch {
+                }
+                resolvePromise(r);
+            };
+            const wallMs = opts?.timeoutMs;
+            const wallTimer = wallMs ? setTimeout(() => finish({ ok: false, error: new ExecutionError("timeout", `command exceeded ${wallMs}ms`) }), wallMs) : undefined;
+            let livenessTimer;
+            const livenessMs = opts?.livenessMs ?? this.cfg.livenessMs;
+            const armLiveness = () => {
+                if (livenessMs <= 0)
+                    return;
+                clearTimeout(livenessTimer);
+                const idle = Date.now() - lastProgress;
+                if (idle >= livenessMs) {
+                    finish({ ok: false, error: new ExecutionError("timeout", `no output for ${idle}ms (exec liveness) — suspected hang`) });
+                    return;
+                }
+                livenessTimer = setTimeout(armLiveness, livenessMs - idle);
+            };
+            armLiveness();
+            const onAbort = () => finish({ ok: false, error: new ExecutionError("aborted", "command aborted") });
+            if (opts?.signal) {
+                if (opts.signal.aborted)
+                    return onAbort();
+                opts.signal.addEventListener("abort", onAbort, { once: true });
+            }
+            sock.on("message", (...args) => {
+                const data = args[0];
+                const buf = Buffer.isBuffer(data) ? data : Buffer.from(data);
+                if (buf.length === 0)
+                    return;
+                lastProgress = Date.now();
+                const channel = buf[0];
+                const payload = buf.subarray(1);
+                if (spliceSink) {
+                    if (channel === 1 || channel === 2)
+                        spliceSink.data(channel, payload);
+                    else if (channel === 3)
+                        statusFrame = payload.toString("utf8");
+                    return;
+                }
+                if (channel === 1) {
+                    if (boundOutput)
+                        outTail.push(payload);
+                    else
+                        outBufs.push(payload);
+                    if (detachTee)
+                        feedMemStream(detachTee.out, payload, K8S_BG_MEM_CAP);
+                    if (outDecoder)
+                        opts.onStdout(outDecoder.write(payload));
+                }
+                else if (channel === 2) {
+                    errBuf.push(payload);
+                    if (detachTee)
+                        feedMemStream(detachTee.err, payload, K8S_BG_MEM_CAP);
+                    if (errDecoder)
+                        opts.onStderr(errDecoder.write(payload));
+                }
+                else if (channel === 3) {
+                    statusFrame = payload.toString("utf8");
+                }
+            });
+            sock.on("error", (...args) => {
+                const e = args[0];
+                if (spliceSink) {
+                    if (!sinkClosed) {
+                        sinkClosed = true;
+                        spliceSink.closed({ failed: true });
+                    }
+                    return;
+                }
+                finish({ ok: false, error: new ExecutionError("transport_lost", `exec socket error: ${errorMessageOf(e)}`, e instanceof Error ? e : undefined) });
+            });
+            sock.on("close", () => {
+                if (spliceSink) {
+                    if (sinkClosed)
+                        return;
+                    sinkClosed = true;
+                    if (statusFrame === undefined)
+                        return spliceSink.closed({ failed: true });
+                    const parsed = exitCodeFromStatus(statusFrame);
+                    return spliceSink.closed("error" in parsed ? { failed: true } : { failed: false, exitCode: parsed.exitCode });
+                }
+                if (statusFrame === undefined) {
+                    finish({ ok: false, error: new ExecutionError("transport_lost", "exec socket closed without status — k8s transport lost mid-command") });
+                    return;
+                }
+                const parsed = exitCodeFromStatus(statusFrame);
+                if ("error" in parsed) {
+                    finish({ ok: false, error: new ExecutionError("spawn_error", parsed.error) });
+                    return;
+                }
+                const err = errBuf.result();
+                const stderr = markTruncated(err.text, err.droppedBytes);
+                if (boundOutput) {
+                    const out = outTail.result();
+                    finish(ok({ stdout: markTruncated(out.text, out.droppedBytes), stderr, exitCode: parsed.exitCode }));
+                }
+                else {
+                    finish(ok({ stdout: Buffer.concat(outBufs).toString("utf8"), stderr, exitCode: parsed.exitCode }));
+                }
+            });
+            const detach = opts?.detach;
+            if (detach) {
+                const onDetach = () => {
+                    if (settled || spliceSink)
+                        return;
+                    const out = outTail ? outTail.result() : { text: "", droppedBytes: 0 };
+                    const err = errBuf.result();
+                    const shellId = detach.adopt({ sock, reroute: (sink) => { spliceSink = sink; } });
+                    if (shellId === undefined) {
+                        spliceSink = undefined;
+                        return;
+                    }
+                    settled = true;
+                    clearTimeout(wallTimer);
+                    clearTimeout(livenessTimer);
+                    opts?.signal?.removeEventListener("abort", onAbort);
+                    removeDetachListener?.();
+                    resolvePromise(ok({ stdout: markTruncated(out.text, out.droppedBytes), stderr: markTruncated(err.text, err.droppedBytes), exitCode: 0, detached: { shellId } }));
+                };
+                if (detach.signal.aborted)
+                    onDetach();
+                else {
+                    detach.signal.addEventListener("abort", onDetach, { once: true });
+                    removeDetachListener = () => detach.signal.removeEventListener("abort", onDetach);
+                }
+            }
+        });
+    }
+    async exec(command, options) {
+        const c = await this.ensureConnected();
+        if (!c.ok)
+            return c;
+        const detachSignal = options?.detachSignal;
+        this.inFlightExecs++;
+        try {
+            const composed = this.withCwdEnv(command, options?.cwd, options?.env);
+            if (!detachSignal) {
+                return await this.runExec(composed, {
+                    signal: options?.abortSignal,
+                    timeoutMs: options?.timeout != null ? options.timeout * 1000 : undefined,
+                    boundOutput: true,
+                    onStdout: options?.onStdout,
+                    onStderr: options?.onStderr,
+                });
+            }
+            const adoptId = randomUUID();
+            const dir = `${K8S_BG_DIR_ROOT}/exec-${adoptId}`;
+            const tee = { out: seedMemStream(""), err: seedMemStream("") };
+            return await this.runExec(buildDetachCapableExec(dir, composed), {
+                signal: options?.abortSignal,
+                timeoutMs: options?.timeout != null ? options.timeout * 1000 : undefined,
+                boundOutput: true,
+                onStdout: options?.onStdout,
+                onStderr: options?.onStderr,
+                detach: {
+                    signal: detachSignal,
+                    tee,
+                    adopt: (io) => {
+                        const adopted = this.bgManager.adoptSync((ctx) => {
+                            const mem = { out: tee.out, err: tee.err };
+                            io.reroute({
+                                data: (channel, payload) => feedMemStream(channel === 1 ? mem.out : mem.err, payload, K8S_BG_MEM_CAP),
+                                closed: (terminal) => ctx.onTerminal(terminal.failed, terminal.exitCode),
+                            });
+                            return { jobId: adoptId, dir, stdoutCursor: 0, stderrCursor: 0, adopt: { mem, sock: io.sock } };
+                        });
+                        return adopted?.shellId;
+                    },
+                },
+            });
+        }
+        finally {
+            this.inFlightExecs--;
+        }
+    }
+    async getHost(port) {
+        const c = await this.ensureConnected();
+        if (!c.ok || !this.podIP)
+            return undefined;
+        return `${this.podIP}:${port}`;
+    }
+    async startBackground(command) {
+        const wrapped = command.replace(/[\\"$`]/g, (c) => "\\" + c);
+        const r = await this.exec(`(nohup sh -c "${wrapped}" >>/tmp/lsp-bridge.log 2>&1 &) ; echo started`, { timeout: 30 });
+        if (!r.ok)
+            throw new RemoteExecutionError("connect_failed", `startBackground failed: ${r.error.message}`, r.error);
+        if (r.value.exitCode !== 0)
+            throw new RemoteExecutionError("connect_failed", `startBackground exited ${r.value.exitCode}: ${r.value.stderr.slice(0, 200)}`);
+    }
+    async *execStream(command, options) {
+        const c = await this.ensureConnected();
+        if (!c.ok)
+            throw new RemoteExecutionError("connect_failed", c.error.message, c.error);
+        this.inFlightExecs++;
+        const queue = [];
+        let finished = false;
+        let failure;
+        let exitCode = 0;
+        let wake;
+        const signalReady = () => {
+            const w = wake;
+            wake = undefined;
+            w?.();
+        };
+        let lastChunk = Date.now();
+        const idleMs = options?.readTimeoutMs ?? this.cfg.livenessMs;
+        const cap = options?.maxOutputBytes;
+        let bytes = 0;
+        const ac = new AbortController();
+        const signal = options?.signal ? AbortSignal.any([options.signal, ac.signal]) : ac.signal;
+        const done = this.runExec(this.withCwdEnv(command, options?.cwd, options?.env), {
+            signal,
+            boundOutput: true,
+            onStdout: (d) => {
+                lastChunk = Date.now();
+                queue.push({ type: "stdout", data: d });
+                signalReady();
+            },
+            onStderr: (d) => {
+                lastChunk = Date.now();
+                queue.push({ type: "stderr", data: d });
+                signalReady();
+            },
+        }).then((r) => {
+            if (r.ok)
+                exitCode = r.value.exitCode;
+            else {
+                const code = r.error.code === "aborted"
+                    ? "aborted"
+                    : r.error.code === "transport_lost"
+                        ? "transport_lost"
+                        : r.error.code === "timeout"
+                            ? "timeout"
+                            : r.error.code === "spawn_error" || r.error.code === "shell_unavailable"
+                                ? "unknown"
+                                : "connect_failed";
+                failure = new RemoteExecutionError(code, r.error.message, r.error);
+            }
+            finished = true;
+            signalReady();
+        });
+        try {
+            for (;;) {
+                while (queue.length) {
+                    const chunk = queue.shift();
+                    yield chunk;
+                    if (cap != null && chunk.type !== "exit") {
+                        bytes += Buffer.byteLength(chunk.data, "utf8");
+                        if (bytes > cap)
+                            throw new RemoteExecutionError("unknown", `execStream output exceeded maxOutputBytes=${cap}`);
+                    }
+                }
+                if (failure)
+                    throw failure;
+                if (finished)
+                    break;
+                const waitMs = Math.max(1, idleMs - (Date.now() - lastChunk));
+                await new Promise((r) => {
+                    wake = r;
+                    setTimeout(r, Math.min(waitMs, 30_000));
+                });
+                if (!finished && Date.now() - lastChunk >= idleMs) {
+                    throw new RemoteExecutionError("timeout", `execStream idle > ${idleMs}ms (suspected hang)`);
+                }
+            }
+            while (queue.length)
+                yield queue.shift();
+            yield { type: "exit", exitCode };
+        }
+        finally {
+            ac.abort();
+            await done.catch(() => { });
+            this.inFlightExecs--;
+        }
+    }
+    backgroundCapabilities;
+    _bgManager;
+    get bgManager() {
+        return (this._bgManager ??= new BackgroundShellManager(this.makeBgDriver(), this.backgroundCapabilities));
+    }
+    makeBgDriver() {
+        const self = this;
+        const bgExec = (script, boundOutput) => self.runExec(script, { timeoutMs: self.cfg.rpcTimeoutMs, livenessMs: self.cfg.livenessMs, boundOutput });
+        return {
+            async launch(command, options, ctx) {
+                const conn = await self.ensureConnected();
+                if (!conn.ok)
+                    throw new Error(`pod connect failed: ${conn.error.message}`);
+                const jobId = randomUUID();
+                const dir = `${K8S_BG_DIR_ROOT}/${jobId}`;
+                const inner = self.withCwdEnv(command, options?.cwd, options?.env);
+                const cmdB64 = Buffer.from(inner, "utf8").toString("base64");
+                const runnerB64 = Buffer.from(buildBgRunnerScript(dir), "utf8").toString("base64");
+                const r = await bgExec(buildBgLauncherScript(dir, cmdB64, runnerB64), true);
+                if (!r.ok)
+                    throw new Error(`background launch failed: ${r.error.message}`);
+                if (r.value.exitCode !== 0 || !r.value.stdout.includes("SEMABG_LAUNCHED")) {
+                    throw new Error(`background launch exited ${r.value.exitCode}: ${r.value.stderr.slice(0, 200)}`);
+                }
+                void ctx;
+                return { jobId, dir, stdoutCursor: 0, stderrCursor: 0 };
+            },
+            async read(state) {
+                if (state.adopt) {
+                    const o = drainMemStream(state.adopt.mem.out);
+                    const e = drainMemStream(state.adopt.mem.err);
+                    return {
+                        stdout: o.text,
+                        stderr: e.text,
+                        bytesFromStart: state.adopt.mem.out.totalBytes + state.adopt.mem.err.totalBytes,
+                        bytesDroppedBeforeCursor: o.dropped + e.dropped,
+                    };
+                }
+                const r = await bgExec(buildBgPollScript(state.dir, state.stdoutCursor, state.stderrCursor, K8S_BG_READ_CAP), false);
+                if (!r.ok)
+                    throw new Error(`background poll failed: ${r.error.message}`);
+                const p = parseBgPollOutput(r.value.stdout);
+                if (!p)
+                    throw new Error("background poll: unparseable response");
+                if (p.gone) {
+                    return { stdout: "", stderr: "", bytesFromStart: state.stdoutCursor + state.stderrCursor, bytesDroppedBeforeCursor: 0, terminal: { failed: true } };
+                }
+                const droppedO = Math.max(0, p.outTotal - state.stdoutCursor - p.stdoutBytes);
+                const droppedE = Math.max(0, p.errTotal - state.stderrCursor - p.stderrBytes);
+                state.stdoutCursor = p.outTotal;
+                state.stderrCursor = p.errTotal;
+                let terminal = p.exitCode !== undefined ? { failed: false, exitCode: p.exitCode } : !p.alive ? { failed: true } : undefined;
+                if (!terminal && (p.outTotal > K8S_BG_FILE_CAP || p.errTotal > K8S_BG_FILE_CAP)) {
+                    void bgExec(buildBgKillScript(state.dir), true).catch(() => { });
+                    terminal = { failed: true };
+                }
+                return {
+                    stdout: p.stdout,
+                    stderr: p.stderr,
+                    bytesFromStart: p.outTotal + p.errTotal,
+                    bytesDroppedBeforeCursor: droppedO + droppedE,
+                    ...(terminal ? { terminal } : {}),
+                };
+            },
+            async kill(state) {
+                await bgExec(buildBgKillScript(state.dir), true).catch(() => { });
+            },
+            async disposeOne(state) {
+                const closeAdopted = () => {
+                    if (!state.adopt)
+                        return;
+                    try {
+                        (state.adopt.sock.terminate ?? state.adopt.sock.close).call(state.adopt.sock);
+                    }
+                    catch { }
+                };
+                if (self.destroyed) {
+                    closeAdopted();
+                    return;
+                }
+                await bgExec(buildBgDisposeScript(state.dir), true).catch(() => { });
+                closeAdopted();
+            },
+        };
+    }
+    spawnBackground(command, options) {
+        return this.bgManager.spawn(command, options);
+    }
+    pollBackground(shellId) {
+        return this.bgManager.poll(shellId);
+    }
+    killBackground(shellId) {
+        return this.bgManager.kill(shellId);
+    }
+    disposeBackgroundShells(opts) {
+        return this._bgManager ? this._bgManager.dispose(opts) : Promise.resolve();
+    }
+    async absolutePath(p) {
+        return ok(this.resolve(p));
+    }
+    async joinPath(parts) {
+        return ok(path.posix.join(...parts));
+    }
+    async readBinaryFile(p, abortSignal) {
+        const abs = this.resolve(p);
+        const r = await this.execData(`base64 < ${shellQuote(abs)}`, abortSignal);
+        if (!r.ok)
+            return { ok: false, error: new FileError("unknown", r.error.message, abs, r.error) };
+        if (r.value.exitCode !== 0)
+            return { ok: false, error: this.fileErrorFrom(r.value.stderr, abs, "not_found") };
+        return ok(new Uint8Array(Buffer.from(r.value.stdout.replace(/\s+/g, ""), "base64")));
+    }
+    async readTextFile(p, abortSignal) {
+        const r = await this.readBinaryFile(p, abortSignal);
+        return r.ok ? ok(Buffer.from(r.value).toString("utf8")) : r;
+    }
+    async readTextLines(p, options) {
+        const r = await this.readTextFile(p, options?.abortSignal);
+        if (!r.ok)
+            return r;
+        let lines = r.value.split(/\r?\n/);
+        if (lines.length > 0 && lines[lines.length - 1] === "")
+            lines.pop();
+        if (options?.maxLines != null)
+            lines = lines.slice(0, options.maxLines);
+        return ok(lines);
+    }
+    async writeFile(p, content, abortSignal) {
+        const abs = this.resolve(p);
+        const dir = path.posix.dirname(abs);
+        if (dir && dir !== "." && dir !== "/") {
+            const mk = await this.exec(`mkdir -p ${shellQuote(dir)}`, { abortSignal });
+            if (!mk.ok)
+                return { ok: false, error: new FileError("unknown", mk.error.message, dir, mk.error) };
+            if (mk.value.exitCode !== 0)
+                return { ok: false, error: this.fileErrorFrom(mk.value.stderr, dir) };
+        }
+        return this.writeChunked(abs, content, true, abortSignal);
+    }
+    async appendFile(p, content, abortSignal) {
+        return this.writeChunked(this.resolve(p), content, false, abortSignal);
+    }
+    async writeChunked(abs, content, truncateFirst, abortSignal) {
+        const bytes = typeof content === "string" ? Buffer.from(content, "utf8") : Buffer.from(content);
+        for (let off = 0, first = true; off < bytes.length || first; off += WRITE_CHUNK_BYTES, first = false) {
+            const b64 = bytes.subarray(off, off + WRITE_CHUNK_BYTES).toString("base64");
+            const redirect = first && truncateFirst ? ">" : ">>";
+            const r = await this.execData(`printf '%s' ${shellQuote(b64)} | base64 -d ${redirect} ${shellQuote(abs)}`, abortSignal);
+            if (!r.ok)
+                return { ok: false, error: new FileError("unknown", r.error.message, abs, r.error) };
+            if (r.value.exitCode !== 0)
+                return { ok: false, error: this.fileErrorFrom(r.value.stderr, abs) };
+        }
+        return ok(undefined);
+    }
+    async fileInfo(p, abortSignal) {
+        const abs = this.resolve(p);
+        const r = await this.exec(`stat -c '%s %Y %f' ${shellQuote(abs)}`, { abortSignal });
+        if (!r.ok)
+            return { ok: false, error: new FileError("unknown", r.error.message, abs, r.error) };
+        if (r.value.exitCode !== 0)
+            return { ok: false, error: this.fileErrorFrom(r.value.stderr, abs, "not_found") };
+        const [sizeS, mtimeS, modeHex] = r.value.stdout.trim().split(/\s+/);
+        return ok({ name: path.posix.basename(abs), path: abs, kind: kindFromMode(parseInt(modeHex ?? "0", 16)), size: Number(sizeS) || 0, mtimeMs: (Number(mtimeS) || 0) * 1000 });
+    }
+    async listDir(p, abortSignal) {
+        const abs = this.resolve(p);
+        const r = await this.exec(`ls -1A ${shellQuote(abs)}`, { abortSignal });
+        if (!r.ok)
+            return { ok: false, error: new FileError("unknown", r.error.message, abs, r.error) };
+        if (r.value.exitCode !== 0)
+            return { ok: false, error: this.fileErrorFrom(r.value.stderr, abs) };
+        const names = r.value.stdout.split(/\r?\n/).map((s) => s.trim()).filter(Boolean);
+        const out = [];
+        for (const name of names) {
+            const info = await this.fileInfo(path.posix.join(abs, name), abortSignal);
+            out.push(info.ok ? info.value : { name, path: path.posix.join(abs, name), kind: "file", size: 0, mtimeMs: 0 });
+        }
+        return ok(out);
+    }
+    async canonicalPath(p, abortSignal) {
+        const abs = this.resolve(p);
+        const r = await this.exec(`realpath ${shellQuote(abs)}`, { abortSignal });
+        if (!r.ok)
+            return { ok: false, error: new FileError("unknown", r.error.message, abs, r.error) };
+        if (r.value.exitCode !== 0)
+            return { ok: false, error: this.fileErrorFrom(r.value.stderr, abs, "not_found") };
+        return ok(r.value.stdout.trim());
+    }
+    async exists(p, abortSignal) {
+        const abs = this.resolve(p);
+        const r = await this.exec(`[ -e ${shellQuote(abs)} ] && printf yes || printf no`, { abortSignal });
+        if (!r.ok)
+            return { ok: false, error: new FileError("unknown", r.error.message, abs, r.error) };
+        const out = r.value.stdout.trim();
+        if (out === "yes")
+            return ok(true);
+        if (out === "no")
+            return ok(false);
+        return { ok: false, error: this.fileErrorFrom(r.value.stderr, abs) };
+    }
+    async createDir(p, options) {
+        const abs = this.resolve(p);
+        const r = await this.exec(`mkdir ${options?.recursive === false ? "" : "-p "}${shellQuote(abs)}`, { abortSignal: options?.abortSignal });
+        if (!r.ok)
+            return { ok: false, error: new FileError("unknown", r.error.message, abs, r.error) };
+        if (r.value.exitCode !== 0)
+            return { ok: false, error: this.fileErrorFrom(r.value.stderr, abs) };
+        return ok(undefined);
+    }
+    async remove(p, options) {
+        const abs = this.resolve(p);
+        const flags = `${options?.recursive ? "r" : ""}${options?.force ? "f" : ""}`;
+        const r = await this.exec(`rm ${flags ? `-${flags}` : ""} ${shellQuote(abs)}`, { abortSignal: options?.abortSignal });
+        if (!r.ok)
+            return { ok: false, error: new FileError("unknown", r.error.message, abs, r.error) };
+        if (r.value.exitCode !== 0) {
+            if (options?.force && /no such file/i.test(r.value.stderr))
+                return ok(undefined);
+            return { ok: false, error: this.fileErrorFrom(r.value.stderr, abs) };
+        }
+        return ok(undefined);
+    }
+    async createTempDir(prefix = "tmp-", abortSignal) {
+        const r = await this.exec(`mktemp -d -p ${shellQuote(this.cwd)} ${shellQuote(`${prefix}XXXXXX`)}`, { abortSignal });
+        return this.tempResult(r, "mktemp -d");
+    }
+    async createTempFile(options) {
+        const tmpl = `${options?.prefix ?? ""}XXXXXX${options?.suffix ?? ""}`;
+        const r = await this.exec(`mktemp -p ${shellQuote(this.cwd)} ${shellQuote(tmpl)}`, { abortSignal: options?.abortSignal });
+        return this.tempResult(r, "mktemp");
+    }
+    async execData(command, abortSignal) {
+        const c = await this.ensureConnected();
+        if (!c.ok)
+            return c;
+        return this.runExec(command, { signal: abortSignal, timeoutMs: this.cfg.dataTimeoutMs });
+    }
+    withCwdEnv(command, cwd, env) {
+        const parts = [];
+        const dir = cwd ?? this.cwd;
+        if (dir)
+            parts.push(`cd ${shellQuote(this.resolve(dir))} &&`);
+        if (env)
+            for (const [k, v] of Object.entries(env))
+                parts.push(`export ${k}=${shellQuote(v)};`);
+        parts.push(command);
+        return parts.join(" ");
+    }
+    fileErrorFrom(stderr, p, fallback = "unknown") {
+        const msg = stderr.trim();
+        if (/no such file/i.test(msg))
+            return new FileError("not_found", msg, p);
+        if (/permission denied/i.test(msg))
+            return new FileError("permission_denied", msg, p);
+        if (/is a directory/i.test(msg))
+            return new FileError("is_directory", msg, p);
+        if (/not a directory/i.test(msg))
+            return new FileError("not_directory", msg, p);
+        if (/input\/output error|too many levels|file name too long|no space left/i.test(msg))
+            return new FileError("unknown", msg, p);
+        return new FileError(fallback, msg || "command failed", p);
+    }
+    tempResult(r, label) {
+        if (!r.ok)
+            return { ok: false, error: new FileError("unknown", r.error.message, undefined, r.error) };
+        if (r.value.exitCode !== 0)
+            return { ok: false, error: new FileError("unknown", r.value.stderr.trim() || `${label} failed`) };
+        return ok(r.value.stdout.trim());
+    }
+}
+export function k8sExecutionEnvFactory(config) {
+    return (ctx) => new RemoteK8sExecutionEnv({ ...config, sessionId: ctx.sessionId });
+}
+//# sourceMappingURL=remote-env-k8s.js.map