@sema-agent/server 1.323.0 → 2.0.0

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

@@ -1,3 +1,35 @@
+/**
+ * `RemoteK8sExecutionEnv` — the Kubernetes pod-sandbox implementation of core's `RemoteExecutionEnv` seam
+ * (design/61). A PEER adapter to E2B/SSH/ADB (NOT chained). Use case: self-hosted sandboxes on our k3s with
+ * **Kata Containers** (`runtimeClassName: kata-qemu`) — a real VM boundary (guest kernel ≠ host, proven in the
+ * 2026-06-10 PoC) at ~2s startup, par with managed E2B.
+ *
+ * 🔴 Capabilities: `{ isolation: true, suspendable: false }` — Kata gives VM isolation, but
+ * there is NO managed memory snapshot (E2B-style pause/resume). `suspendVM`/`resumeVM`/`postResumeInit` →
+ * typed `"unsupported"` so durable suspend degrades honestly (checkpoint + cold rebuild, in-VM process state
+ * like a language server is lost). True memory snapshots = a separate CRIU/Kata-snapshot project, not implied.
+ *
+ * Transport: the k8s REST API + the exec WebSocket (channel-multiplexed: 1-byte channel prefix per frame —
+ * 1=stdout 2=stderr 3=status JSON) spoken directly over `ws` — deliberately NO `@kubernetes/client-node`
+ * dependency (its exec path is the only thing we'd use; our liveness/timeout discipline plugs straight into a
+ * raw socket, and the fault-injection seam stays trivial). Unlike `adb exec-out`, the status channel carries a
+ * REAL exit code.
+ *
+ * 🔴 Subprotocol = `v5.channel.k8s.io` first, `v4` fallback (night-drill 2026-06-11): the apiserver's **v4**
+ * WebSocket exec writer STALLS after the first ~6KB of a fast output burst (verified: the TCP socket stays
+ * healthy/flowing, the apiserver just stops sending; v5 streams the same 1MB+ burst to completion). v5 (k8s
+ * 1.29+) is what modern kubectl negotiates; the frame format is identical (it only adds a close-channel we
+ * ignore), so offering both lets a v5 apiserver fix the stall while a v4-only one still works for small output.
+ *
+ * Timeouts follow the E2B class-fix taxonomy: control-plane RPCs get a short wall-clock
+ * (`rpcTimeoutMs`); commands get a zero-progress LIVENESS bound (`livenessMs`) plus the caller's explicit
+ * wall-clock; pod readiness gets its own generous bound (image pull can be slow). ⚠️ killing the exec socket
+ * does NOT kill the remote process — acceptable here because the pod is DISPOSABLE (destroyed with the task;
+ * `activeDeadlineSeconds` is the leak guard), unlike the SSH real-machine posture.
+ *
+ * Auth: a bearer token + CA, either explicit (`K8S_API_URL`/`K8S_TOKEN`/`K8S_CA_CERT_B64`) or in-cluster
+ * (service-account files + `KUBERNETES_SERVICE_HOST`) — control-plane config, never agent-reachable.
+ */
 import path from "node:path";
 import { readFileSync } from "node:fs";
 import https from "node:https";
@@ -12,13 +44,25 @@ import { createPosixShellFs } from "./posix-shell-fs.js";
 import { randomUUID } from "node:crypto";
 import { BackgroundShellManager, seedMemStream, feedMemStream, drainMemStream } from "./background-shell-support.js";
 const PROVIDER = "k8s";
+/**
+ * design/103 background-shell (TOB, path ① — pod-side file buffer re-read by byte cursor). Bounds for kata/k8s.
+ * A background job cannot outlive its pod (`activeDeadlineSeconds`), so `maxBgTimeoutSec` is additionally clamped
+ * to the pod lifetime at construction. `maxConcurrent` mirrors the TOC default (8) — anti fork-bomb.
+ */
 const K8S_BG_DIR_ROOT = "/tmp/.sema-bg";
 const K8S_BG_MAX_CONCURRENT = numEnvOr("K8S_BG_MAX_CONCURRENT", 8, 1);
 const K8S_BG_DEFAULT_TIMEOUT_SEC = numEnvOr("K8S_BG_DEFAULT_TIMEOUT_SEC", 300, 1);
 const K8S_BG_MAX_TIMEOUT_SEC = numEnvOr("K8S_BG_MAX_TIMEOUT_SEC", 1800, K8S_BG_DEFAULT_TIMEOUT_SEC);
+/** Max bytes returned per stream per poll (bounds the control-plane transfer; the model only displays ~20K anyway). */
 const K8S_BG_READ_CAP = numEnvOr("K8S_BG_READ_CAP", 1024 * 1024, 64 * 1024);
+/** Per-stream pod-side file cap (FIFO+`head` — a runaway `yes` is SIGPIPE'd at this bound; the pod has no ephemeral-storage limit). */
 const K8S_BG_FILE_CAP = numEnvOr("K8S_BG_FILE_CAP", 64 * 1024 * 1024, K8S_BG_READ_CAP);
+/** Per-stream control-plane drain cap for an ADOPTED (mid-flight detach) shell — its output rides the still-open
+ *  exec WebSocket into worker memory, not pod files, so bound the un-polled queue (drop-oldest → `truncated`). */
 const K8S_BG_MEM_CAP = numEnvOr("K8S_BG_MEM_CAP", 8 * 1024 * 1024, 64 * 1024);
+// design/158 A13: the pure background-shell pod-side script generation/parsing group (buildBg*Script ×5 +
+// buildDetachCapableExec + parseBgPollOutput + ParsedBgPoll) moved VERBATIM to ./k8s-bg-scripts.js —
+// value-imported below (the class body still calls them) and re-exported so existing importers keep working.
 import { buildBgRunnerScript, buildBgLauncherScript, buildBgPollScript, buildBgKillScript, buildBgDisposeScript, buildDetachCapableExec, parseBgPollOutput, } from "./k8s-bg-scripts.js";
 export { buildBgRunnerScript, buildBgLauncherScript, buildBgPollScript, buildBgKillScript, buildBgDisposeScript, buildDetachCapableExec, parseBgPollOutput, } from "./k8s-bg-scripts.js";
 const ok = (value) => ({ ok: true, value });
@@ -27,12 +71,29 @@ const unsupported = (op) => ({
     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";
+/** Exec WebSocket subprotocols, preference order (see header — v4 burst-stall). */
 const EXEC_SUBPROTOCOLS = ["v5.channel.k8s.io", "v4.channel.k8s.io"];
+/**
+ * argv-embedded base64 write chunk (SOURCE bytes). 🔴 The bound is Linux `MAX_ARG_STRLEN` = 128KiB (131072),
+ * the limit on a SINGLE argv string — and the whole `printf '%s' '<base64>' | base64 -d >> '<path>'` command
+ * is passed as one `sh -c <cmd>` argument. base64 inflates 4/3, so a 96KiB source chunk made a 131072-byte
+ * base64 = exactly the limit ⇒ silent truncation (night-drill: writes >95KiB failed "command failed"). 64KiB
+ * source → 87KiB base64 + wrapper ≈ 87KiB command, a safe ~44KiB under the limit.
+ */
 const WRITE_CHUNK_BYTES = 64 * 1024;
+// design/158 A13: the pod-spec patch group (PodSpecPatch + applyPodSpecPatch + its hardening/volume guards)
+// moved VERBATIM to ./k8s-exec-protocol.js — value-imported below (the class body calls applyPodSpecPatch)
+// and re-exported so existing importers keep working.
 import { applyPodSpecPatch } from "./k8s-exec-protocol.js";
 export { applyPodSpecPatch } from "./k8s-exec-protocol.js";
+// design/158 A13: execSocketTlsOptions + exitCodeFromStatus moved VERBATIM to ./k8s-exec-protocol.js
+// (errorMessageOf, sandwiched between them in the original layout, stays HERE — it is a small ws-error
+// helper, not part of the pod-spec-patch/protocol group). Value-imported below (the class body calls both)
+// and re-exported so existing importers keep working.
 import { execSocketTlsOptions, exitCodeFromStatus } from "./k8s-exec-protocol.js";
 export { execSocketTlsOptions } from "./k8s-exec-protocol.js";
+/** `Error`-or-event → message. Bun's ws shim emits browser-style ErrorEvents (NOT instanceof Error) whose
+ *  String() is "[object ErrorEvent]" — that masked the real TLS failure for a whole drill. */
 export function errorMessageOf(e) {
     if (e instanceof Error)
         return e.message;
@@ -44,10 +105,15 @@ export class RemoteK8sExecutionEnv {
     capabilities;
     cwd;
     podName;
+    /** Cluster-internal pod address, captured when the pod reaches Running — the LSP `getHost` surface.
+     *  Lifecycle mirrors podName exactly (set on connect, cleared on suspend/destroy/dead-reconnect). */
     podIP;
     destroyed = false;
+    /** Set after a successful resumeVM so workspaceHandle() carries the snapshot it was restored from. */
     handleSnapshotId;
+    /** In-flight exec count — `suspendVM` refuses while a command runs (council #4 suspend×in-flight). */
     inFlightExecs = 0;
+    /** Memoized in-flight connect (lazy-connect; prevents concurrent double pod-create — the E2B race lesson). */
     connectPromise;
     cfg;
     deps;
@@ -72,17 +138,24 @@ export class RemoteK8sExecutionEnv {
             ...(config.s3Snapshot ? { s3Snapshot: config.s3Snapshot } : {}),
             ...(config.sessionId ? { sessionId: config.sessionId } : {}),
             ...(config.podSpecPatch ? { podSpecPatch: config.podSpecPatch } : {}),
-            ...(config.podEnv ? { podEnv: config.podEnv } : {}),
+            ...(config.podEnv ? { podEnv: config.podEnv } : {}), // RFC B5: region package-source env
         };
         this.cwd = this.cfg.mountPath;
         this.deps = deps ?? {};
+        // Workspace snapshots make this env suspendable (files durable across suspend/resume); without an S3
+        // store it stays the honest checkpoint + cold-rebuild degrade.
         this.capabilities = { isolation: true, suspendable: !!this.cfg.s3Snapshot };
+        // Clamp BOTH the ceiling AND the default to the pod lifetime — a short-lived pod must not advertise a default
+        // bigger than its max (the manager would clamp the actual spawn, making the advertised default a lie).
         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,
+            // core 1.207 design/116 detach (1.82): a running foreground exec is ADOPTED as a background shell
+            // (mid-flight ctrl+b) — the exec WebSocket keeps streaming into memory-mode drain buffers; kill works
+            // through the pgid the detach-capable exec prelude self-reported (buildDetachCapableExec).
             supportsDetach: true,
         };
     }
@@ -92,6 +165,8 @@ export class RemoteK8sExecutionEnv {
     workspaceHandle() {
         return { sandboxId: this.podName ?? "(unconnected)", provider: PROVIDER, mountPath: this.cwd, ...(this.handleSnapshotId ? { snapshotId: this.handleSnapshotId } : {}) };
     }
+    // ─────────────────────────────── auth / transport ───────────────────────────────
+    /** Resolved lazily so an in-cluster pod picks up its service account without explicit config. */
     creds() {
         const apiUrl = this.cfg.apiUrl ??
             (process.env.KUBERNETES_SERVICE_HOST ? `https://${process.env.KUBERNETES_SERVICE_HOST}:${process.env.KUBERNETES_SERVICE_PORT ?? "443"}` : undefined);
@@ -117,6 +192,7 @@ export class RemoteK8sExecutionEnv {
         }
         return { apiUrl: apiUrl.replace(/\/+$/, ""), token, ca };
     }
+    /** Control-plane REST call (pod create/get/delete), bounded by rpcTimeoutMs. Injectable for tests. */
     async request(method, apiPath, body, opts) {
         if (this.deps.request)
             return this.deps.request(method, apiPath, body, opts);
@@ -171,15 +247,22 @@ export class RemoteK8sExecutionEnv {
             ...(url.startsWith("wss:") ? execSocketTlsOptions(ca, this.cfg.insecureTls) : {}),
         });
     }
+    // ─────────────────────────────── lifecycle ───────────────────────────────
     async connect(config) {
         const policy = {
-            retryableCodes: ["connect_failed", "timeout", "transport_lost"],
+            retryableCodes: ["connect_failed", "timeout", "transport_lost"], // NOT auth_failed
             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 });
     }
+    /**
+     * Lazy-connect on first use — 🔴 core NEVER calls `connect()` (verified: the Runner only calls `resumeVM` on
+     * the resume path), so an adapter that demands an explicit connect can never work through the production
+     * hand-tool path (lazy-connect belongs in the adapter). Memoized so concurrent first ops share ONE
+     * pod create; a failed connect clears the memo (next op retries); `destroyed` is terminal.
+     */
     async ensureConnected() {
         if (this.podName)
             return ok(undefined);
@@ -188,7 +271,7 @@ export class RemoteK8sExecutionEnv {
         this.connectPromise ??= this.connect();
         const r = await this.connectPromise;
         if (!r.ok) {
-            this.connectPromise = undefined;
+            this.connectPromise = undefined; // don't cache the failure — the next op gets a fresh attempt
             return { ok: false, error: new ExecutionError("shell_unavailable", `k8s sandbox connect failed: ${r.error.message}`, r.error) };
         }
         return ok(undefined);
@@ -209,16 +292,24 @@ export class RemoteK8sExecutionEnv {
             spec: {
                 ...(this.cfg.runtimeClass ? { runtimeClassName: this.cfg.runtimeClass } : {}),
                 restartPolicy: "Never",
+                // Defense-in-depth (council DESIGN#1): the agent runs INSIDE this pod; never mount a k8s SA token into
+                // it. The adapter holds the only credential it needs (control-plane side) — the workload gets none, so
+                // an accidental cluster-wide default-SA binding can't hand the agent the API.
                 automountServiceAccountToken: false,
+                // Leak guard (the E2B-lifetime analogue): the pod self-terminates even if destroy() never runs.
                 activeDeadlineSeconds: Math.ceil(this.cfg.timeoutMs / 1000),
                 terminationGracePeriodSeconds: 1,
                 containers: [
                     {
                         name: "sandbox",
                         image: this.cfg.image,
+                        // RFC B5: when a pkg-source profile is injected, run the image's materializer ONCE at pod start
+                        // (root, before any exec — core's exec lanes are non-login `sh -c`, so the profile.d hook alone
+                        // wouldn't fire there). Script-absent images no-op; podEnv unset ⇒ command byte-identical to today.
                         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"],
+                        // RFC B5: operator-trusted region env (pkg-source selection). Absent = no env key at all (byte-identical).
                         ...(this.cfg.podEnv && Object.keys(this.cfg.podEnv).length > 0
                             ? { env: Object.entries(this.cfg.podEnv).map(([name, value]) => ({ name, value: String(value) })) }
                             : {}),
@@ -227,6 +318,9 @@ export class RemoteK8sExecutionEnv {
                 ],
             },
         };
+        // 🔴 ADDITIVE deployment patch: add RO oracle mounts / hardened securityContext for the L8
+        // immutable-mount probe + the graderEnvFactory. Applied AFTER the hard invariants above so it can never weaken
+        // them (applyPodSpecPatch only touches volumes/mounts/securityContext/labels). No-op when unset (byte-identical).
         if (this.cfg.podSpecPatch)
             applyPodSpecPatch(pod, this.cfg.podSpecPatch);
         let created;
@@ -245,6 +339,7 @@ export class RemoteK8sExecutionEnv {
         const name = created.json?.metadata?.name;
         if (!name)
             return { ok: false, error: new RemoteExecutionError("connect_failed", "pod create returned no name") };
+        // Poll until Running (schedule + image pull + Kata VM boot), bounded by readyTimeoutMs.
         const deadline = Date.now() + this.cfg.readyTimeoutMs;
         let podIP;
         for (;;) {
@@ -281,12 +376,16 @@ export class RemoteK8sExecutionEnv {
             }
             await new Promise((r) => setTimeout(r, 1000));
         }
+        // Destroy-race guard (the E2B lazy-connect BLOCKER lesson): if destroy() ran while we were creating the
+        // pod, kill the fresh pod and bail — never resurrect a destroyed env (destroyed is terminal).
         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;
+        // Workspace root (the image may not ship it) — via runExec DIRECTLY: this.exec() would re-enter
+        // ensureConnected and deadlock on the still-pending connect memo. Failure = unusable sandbox.
         const mk = await this.runExec(`mkdir -p ${shellQuote(this.cfg.mountPath)}`);
         if (!mk.ok || mk.value.exitCode !== 0) {
             await this.deletePod(name).catch(() => { });
@@ -296,6 +395,14 @@ export class RemoteK8sExecutionEnv {
         }
         return ok(this.workspaceHandle());
     }
+    /**
+     * Build a validated, presigned URL for a snapshot object — `<prefix>/<sessionId>/<snapshotId>.tar.gz`.
+     * 🔴 sessionId comes from the client (`body.sessionId`, security.ts) and is NOT charset-validated upstream, so
+     * each path segment is allowlisted here (`^[A-Za-z0-9][A-Za-z0-9._-]*$`) before it enters the object key: a
+     * segment of `..` / `../x` / one containing `/` would otherwise let one tenant's snapshot key normalize into
+     * another tenant's prefix (cross-tenant read on resume / clobber on suspend). Returns a typed error instead of
+     * signing a traversing key. Folds the old snapshotKey()+s3Presign() pair so the two call sites can't diverge.
+     */
     presignSnapshot(method, snapshotId) {
         const s3 = this.cfg.s3Snapshot;
         const prefix = s3.keyPrefix ?? "kata";
@@ -315,29 +422,48 @@ export class RemoteK8sExecutionEnv {
                 accessKey: s3.accessKey,
                 secretKey: s3.secretKey,
                 ...(s3.region ? { region: s3.region } : {}),
+                // Clamp the presigned-URL TTL to a 1h ceiling — a short-lived single-object credential must not become a
+                // long-lived bearer token via an over-large WORKSPACE_SNAPSHOT_TTL_SEC.
                 expiresSec: Math.min(s3.presignTtlSec ?? 600, 3600),
             }),
         };
     }
+    /** Redact a presigned URL (and any lingering signature) from text before it enters an error/log — the URL is a
+     *  short-lived bearer credential and must never reach a durable store (secret boundary). */
     redactUrl(text, url) {
         return text.split(url).join("<presigned-url>").replace(/X-Amz-Signature=[0-9a-f]+/gi, "X-Amz-Signature=<redacted>");
     }
+    /**
+     * Workspace-durable suspend: tar the workspace, upload to S3 via a short-lived adapter-presigned
+     * URL the pod curls (credentials never enter the sandbox), then delete the pod. The returned SnapshotId is
+     * opaque to core; we use a fresh id and persist the bytes under {@link snapshotKey}. NOT supported without an
+     * S3 store (returns the honest "unsupported" so durable suspend degrades to checkpoint + cold rebuild).
+     *
+     * 🔴 council #4 (suspend × in-flight exec): refuse while a command runs — tarring a mutating tree would
+     * snapshot a torn workspace. Core also won't suspend mid-tool, but the adapter enforces it independently.
+     */
     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)}`;
+        // A never-connected env (a plan-only task that suspended without touching the hand) has no workspace to
+        // capture — return a snapshotId with no object; resume tolerates the 404 as an empty workspace.
         if (!this.podName)
             return ok(snapshotId);
         const presigned = this.presignSnapshot("PUT", snapshotId);
         if (!presigned.ok)
             return presigned;
         const url = presigned.value;
+        // Materialize the archive to a pod-local temp file, THEN upload — a streamed `tar | curl -T -` sends
+        // Transfer-Encoding: chunked with no Content-Length, which MinIO rejects with HTTP 411 on a presigned PUT
+        // (live-verified). `curl -T <file>` sets Content-Length from the file size. Bytes still go pod→MinIO (never
+        // the worker); the temp file lives in the disposable pod and is removed regardless of curl's outcome.
         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 });
+        const r = await this.runExec(cmd, { timeoutMs: this.cfg.dataTimeoutMs, livenessMs: 0 }); // silent bulk upload → wall bound only
         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)
@@ -345,12 +471,24 @@ export class RemoteK8sExecutionEnv {
         const name = this.podName;
         this.podName = undefined;
         this.podIP = undefined;
-        await this.deletePod(name).catch(() => { });
+        await this.deletePod(name).catch(() => { }); // suspend = release the pod; the snapshot is the durable state
         return ok(snapshotId);
     }
+    /**
+     * Resume a workspace snapshot onto a FRESH pod (resume = executionEnvFactory rebuild + resumeVM):
+     * provision a pod, then download + untar the snapshot into the workspace. A missing object (empty/plan-only
+     * snapshot) resumes as a clean workspace.
+     *
+     * [1467]①(priorHandle 根保真)——k8s 走**诚实臂**而非绑定臂:pod 的 workspace volume 挂在**当前**
+     * 配置根(cfg.mountPath),往 priorHandle.mountPath 绑=往容器 rootfs untar 大工作区,ephemeral-storage
+     * 触顶即 pod 驱逐(恢复中途死,比「根变了 fail-closed reopen」更糟)。所以 untar 落当前根、handle 回报
+     * 真生效根(core 契约明许:「做不到就诚实返回实际 mountPath,勿回显未兑现值」);跨 K8S_MOUNT_PATH
+     * 变更窗的分歧由 core 侧 fail-closed reopen 兜底,审批不烧错根。
+     */
     async resumeVM(snapshotId, options) {
         if (!this.cfg.s3Snapshot)
             return unsupported("resumeVM");
+        // Validate + presign BEFORE provisioning a pod — a traversing/garbage snapshotId should fail fast, not leak a pod.
         const presigned = this.presignSnapshot("GET", snapshotId);
         if (!presigned.ok)
             return presigned;
@@ -358,11 +496,14 @@ export class RemoteK8sExecutionEnv {
         if (!c.ok)
             return c;
         const url = presigned.value;
+        // Capture the HTTP status (curl -s -w) and branch on it: 404 → empty/plan-only snapshot, leave the fresh
+        // empty workspace; non-200 → real error (exit 22); 200 → untar. (No `-f`: we need the status code, not a
+        // curl error exit, to distinguish the tolerated 404 from a genuine failure.)
         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 });
+        const r = await this.runExec(cmd, { timeoutMs: this.cfg.dataTimeoutMs, livenessMs: 0 }); // silent bulk download → wall bound only
         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)
@@ -370,12 +511,19 @@ export class RemoteK8sExecutionEnv {
         this.handleSnapshotId = snapshotId;
         return ok(this.workspaceHandle());
     }
+    /**
+     * Honest post-resume consistency (design/48 §5 council #8): the workspace FILES are restored byte-for-byte
+     * from the snapshot, so read-before-edit hashing already lines up — there's nothing to re-fetch. In-VM
+     * process state (a language server) is gone by design; core/the LSP manager re-establishes it lazily. So
+     * this is a successful no-op rather than the previous `unsupported` (which forced a cold rebuild).
+     */
     async postResumeInit() {
         if (!this.cfg.s3Snapshot)
             return unsupported("postResumeInit");
         return ok(undefined);
     }
     async reconnect(_sessionToken) {
+        // The pod either still runs (reuse) or is gone (fresh connect).
         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;
@@ -389,7 +537,10 @@ export class RemoteK8sExecutionEnv {
     async deletePod(name) {
         await this.request("DELETE", `/api/v1/namespaces/${this.cfg.namespace}/pods/${name}?gracePeriodSeconds=0`, undefined, { timeoutMs: this.cfg.rpcTimeoutMs });
     }
+    /** Delete the sandbox pod — the workspace is DISPOSABLE (vs SSH/ADB disconnect-only). Idempotent, never throws. */
     async destroy() {
+        // design/103 §3.7 backstop: kill/clear any background jobs while the pod is still alive (core's run-loop finally
+        // usually disposed already → this iterates an empty registry). After this the pod delete reaps anything left.
         await this.disposeBackgroundShells().catch(() => { });
         this.destroyed = true;
         const name = this.podName;
@@ -401,6 +552,7 @@ export class RemoteK8sExecutionEnv {
     async cleanup() {
         return this.destroy();
     }
+    // ─────────────────────────────── exec ───────────────────────────────
     execUrl(command) {
         const { apiUrl, token } = this.creds();
         const base = apiUrl.replace(/^http/, "ws");
@@ -412,7 +564,18 @@ export class RemoteK8sExecutionEnv {
             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) {
+    /**
+     * Run a command over the exec WebSocket. Frames: byte0=channel (1 stdout / 2 stderr / 3 status JSON with the
+     * REAL exit code). Bounds: caller wall-clock (explicit `timeout`) + zero-progress liveness (`livenessMs`) —
+     * a socket killed by either does NOT kill the remote process (disposable-pod posture, see header).
+     */
+    runExec(command, 
+    // 🔴 binary caveat (D2): runExec is SHARED by the model-facing TEXT exec / execStream (boundOutput:true —
+    // a `yes`/`cat big` must not OOM the durable worker) AND by readBinaryFile, which reads the file as base64 over
+    // execData→runExec and decodes r.value.stdout. Bounding that base64 stream would SILENTLY CORRUPT binary/large
+    // reads. So boundOutput DEFAULTS OFF: every data path (execData, snapshot tar up/down, mkdir) keeps EVERY byte
+    // byte-exact; ONLY exec()/execStream() opt in. stderr is always bounded (never the file payload).
+    opts) {
         let sock;
         let headers;
         let url;
@@ -424,19 +587,27 @@ export class RemoteK8sExecutionEnv {
             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) => {
+            // boundOutput (see signature): TEXT exec/execStream bound stdout to a rolling-TAIL (last 8MB + dropped marker,
+            // O(maxBytes)); data paths (boundOutput off) keep full bytes so readBinaryFile's base64 decodes losslessly.
+            // stderr is ALWAYS bounded — it never carries the base64 file payload.
             const boundOutput = !!opts?.boundOutput;
-            const outBufs = [];
-            const outTail = boundOutput ? new RollingTailBuffer() : undefined;
+            const outBufs = []; // data path (boundOutput off): full bytes
+            const outTail = boundOutput ? new RollingTailBuffer() : undefined; // text path: bounded stdout
             const errBuf = new RollingTailBuffer();
+            // Per-channel UTF-8 decoders for the STREAMING callbacks only (council BUG#1): a multibyte codepoint can
+            // straddle two WS frames → a per-frame `payload.toString("utf8")` emits U+FFFD. StringDecoder buffers the
+            // incomplete tail across writes. (The buffered path decodes once via Buffer.concat below — already safe.)
             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();
+            // design/116 detach: once set, the socket's frames belong to the ADOPTED shell — message/error/close route
+            // here instead of the (already-settled) foreground buffers, and the socket is NOT closed on settle.
             let spliceSink;
-            let sinkClosed = false;
+            let sinkClosed = false; // error+close can BOTH fire — notify the adopted shell's terminal exactly once
             let removeDetachListener;
-            const detachTee = opts?.detach?.tee;
+            const detachTee = opts?.detach?.tee; // fed on every fg frame; a later adoption takes the pair over as-is (review #3)
             const finish = (r) => {
                 if (settled)
                     return;
@@ -449,12 +620,19 @@ export class RemoteK8sExecutionEnv {
                     (sock.terminate ?? sock.close).call(sock);
                 }
                 catch {
+                    /* already gone */
                 }
                 resolvePromise(r);
             };
             const wallMs = opts?.timeoutMs;
             const wallTimer = wallMs ? setTimeout(() => finish({ ok: false, error: new ExecutionError("timeout", `command exceeded ${wallMs}ms`) }), wallMs) : undefined;
+            // zero-progress liveness (E2B class-fix semantics): on firing, re-check actual idleness and re-arm for
+            // EXACTLY the remaining window (the E2B waitWithLiveness/council-DESIGN-1 discipline — a full-window
+            // re-arm would let a hang sit for up to 2× livenessMs before detection).
             let livenessTimer;
+            // Per-call liveness override (0 = disabled): bulk data transfers (tar→S3 upload, S3→untar restore) are
+            // legitimately SILENT for their whole duration, so the zero-output liveness would false-positive a "hang";
+            // they rely on the wall-clock `timeoutMs` (dataTimeoutMs) instead. Defaults to the configured command bound.
             const livenessMs = opts?.livenessMs ?? this.cfg.livenessMs;
             const armLiveness = () => {
                 if (livenessMs <= 0)
@@ -481,8 +659,10 @@ export class RemoteK8sExecutionEnv {
                     return;
                 lastProgress = Date.now();
                 const channel = buf[0];
-                const payload = buf.subarray(1);
+                const payload = buf.subarray(1); // zero-copy view; `ws` gives each message its own buffer (no reuse),
                 if (spliceSink) {
+                    // Adopted: output frames feed the background shell's drain buffers; the status frame still lands in
+                    // `statusFrame` so the close handler can classify the adopted shell's terminal.
                     if (channel === 1 || channel === 2)
                         spliceSink.data(channel, payload);
                     else if (channel === 3)
@@ -491,11 +671,11 @@ export class RemoteK8sExecutionEnv {
                 }
                 if (channel === 1) {
                     if (boundOutput)
-                        outTail.push(payload);
+                        outTail.push(payload); // text path: bounded tail (streaming callback below still gets the full chunk)
                     else
-                        outBufs.push(payload);
+                        outBufs.push(payload); // data path: full bytes, safe to retain until the final Buffer.concat (council perf#4)
                     if (detachTee)
-                        feedMemStream(detachTee.out, payload, K8S_BG_MEM_CAP);
+                        feedMemStream(detachTee.out, payload, K8S_BG_MEM_CAP); // tee-from-start (review #3): one decoder spans the detach instant
                     if (outDecoder)
                         opts.onStdout(outDecoder.write(payload));
                 }
@@ -513,6 +693,8 @@ export class RemoteK8sExecutionEnv {
             sock.on("error", (...args) => {
                 const e = args[0];
                 if (spliceSink) {
+                    // Adopted: a socket error mid-background = the output feed is lost; outcome unknown → failed. The
+                    // process itself may still run in the pod (disposable-pod posture — teardown reaps it).
                     if (!sinkClosed) {
                         sinkClosed = true;
                         spliceSink.closed({ failed: true });
@@ -526,12 +708,16 @@ export class RemoteK8sExecutionEnv {
                     if (sinkClosed)
                         return;
                     sinkClosed = true;
+                    // Terminal classification mirrors the launch-mode poll: a status frame with an exit code ⇒ exited
+                    // (non-zero exit is a NORMAL result); no status ⇒ the transport died mid-background ⇒ failed.
                     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) {
+                    // closed without a status frame = the transport died mid-command, NOT a command result ([R78]#1).
+                    // Typed "transport_lost" since core 1.89 (outcome UNKNOWN — retry only per the op's idempotency).
                     finish({ ok: false, error: new ExecutionError("transport_lost", "exec socket closed without status — k8s transport lost mid-command") });
                     return;
                 }
@@ -547,21 +733,32 @@ export class RemoteK8sExecutionEnv {
                     finish(ok({ stdout: markTruncated(out.text, out.droppedBytes), stderr, exitCode: parsed.exitCode }));
                 }
                 else {
+                    // byte-exact: readBinaryFile decodes this stdout as base64; never truncate.
                     finish(ok({ stdout: Buffer.concat(outBufs).toString("utf8"), stderr, exitCode: parsed.exitCode }));
                 }
             });
+            // design/116 detach — wired AFTER every handler above exists (the host adapter's create-then-abort TDZ
+            // lesson): core's ToolDetachHub can hand an ALREADY-aborted signal (detach requested before the exec
+            // started), in which case onDetach runs synchronously right here.
             const detach = opts?.detach;
             if (detach) {
                 const onDetach = () => {
                     if (settled || spliceSink)
                         return;
-                    const out = outTail ? outTail.result() : { text: "", droppedBytes: 0 };
+                    const out = outTail ? outTail.result() : { text: "", droppedBytes: 0 }; // detach rides the exec path (boundOutput:true)
                     const err = errBuf.result();
                     const shellId = detach.adopt({ sock, reroute: (sink) => { spliceSink = sink; } });
                     if (shellId === undefined) {
+                        // Refused (limit / builder failure) → the foreground continues untouched. 🔴 review #5: `reroute` is a
+                        // builder SIDE EFFECT — if the builder ran it and then threw, adoptSync's catch returns undefined but
+                        // spliceSink is already set, which would silently reroute every subsequent fg frame into an unregistered
+                        // buffer AND make this exec never settle (close would notify a sink nobody owns). Un-splice defensively;
+                        // same-tick, so no frame can have landed in between.
                         spliceSink = undefined;
                         return;
                     }
+                    // Settle EARLY *without* closing the socket — the adopted shell owns it now. finish() is deliberately
+                    // NOT used (it terminates the socket); this is its detach twin.
                     settled = true;
                     clearTimeout(wallTimer);
                     clearTimeout(livenessTimer);
@@ -582,21 +779,29 @@ export class RemoteK8sExecutionEnv {
         const c = await this.ensureConnected();
         if (!c.ok)
             return c;
+        // design/116 detach (core 1.207, 1.82): the Bash tool threads a `detachSignal` for every exec once
+        // `supportsDetach` is advertised. `ExecOpts` doesn't type it yet (core-side seam) — read it structurally.
         const detachSignal = options?.detachSignal;
-        this.inFlightExecs++;
+        this.inFlightExecs++; // suspendVM refuses while > 0 (council #4: never snapshot a running command)
         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,
+                    boundOutput: true, // model-facing TEXT exec — bound the buffered return value (D2)
                     onStdout: options?.onStdout,
                     onStderr: options?.onStderr,
                 });
             }
+            // Detach-capable exec: the pgid prelude (buildDetachCapableExec) makes the running command adoptable —
+            // kill/dispose on the adopted shell reuse the SAME pod-side scripts as a spawned one. On detach, adoptSync
+            // splices the still-open exec socket into memory-mode drain buffers (SYNCHRONOUS — no await between the
+            // tee handover and the reroute, the host adapter's double-review contract).
             const adoptId = randomUUID();
             const dir = `${K8S_BG_DIR_ROOT}/exec-${adoptId}`;
+            // tee-from-start (Fable-5 review #3): runExec feeds every fg frame into this pair through its per-stream
+            // StringDecoder; adoption takes the pair over as-is, so ONE decoder spans the detach instant (no U+FFFD seam).
             const tee = { out: seedMemStream(""), err: seedMemStream("") };
             return await this.runExec(buildDetachCapableExec(dir, composed), {
                 signal: options?.abortSignal,
@@ -608,8 +813,11 @@ export class RemoteK8sExecutionEnv {
                     signal: detachSignal,
                     tee,
                     adopt: (io) => {
+                        // 🔴 builder contract (review #5): everything inside is NON-THROWING (object construction + the reroute
+                        // assignment). adoptSync's catch does NOT undo side effects — future logic that can throw must go before
+                        // `io.reroute` (the runExec caller also un-splices defensively on an undefined return).
                         const adopted = this.bgManager.adoptSync((ctx) => {
-                            const mem = { out: tee.out, err: tee.err };
+                            const mem = { out: tee.out, err: tee.err }; // the tee already holds the full fg history (truncation marker rides on the exec's OWN early result only — review LOW)
                             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),
@@ -625,13 +833,28 @@ export class RemoteK8sExecutionEnv {
             this.inFlightExecs--;
         }
     }
+    /**
+     * LSP surface (lsp/manager.ts `isLspCapable` duck-type, design/64 §13.1): cluster-internal address for a
+     * port on the sandbox pod. The E2B counterpart returns a public proxy host; a pod has none — the WORKER
+     * must be able to reach pod IPs (in-cluster deployment, or on-node), and the transport is plain `ws://`
+     * (cluster network, no TLS — the per-session bridge token still gates access like on E2B).
+     */
     async getHost(port) {
         const c = await this.ensureConnected();
         if (!c.ok || !this.podIP)
-            return undefined;
+            return undefined; // no IP captured (e.g. faked/older apiserver) → LSP degrades
         return `${this.podIP}:${port}`;
     }
+    /**
+     * Start a long-lived helper (the LSP bridge) detached from this exec session. Unlike E2B — which reaps a
+     * foreground command's process group on completion, forcing a native background API — k8s exec just closes
+     * the session: a `nohup`'d child with detached stdio survives, reparented to the container's PID 1 (the
+     * gate#2 background-gradle runs proved this through the production path). Output goes to /tmp for postmortem.
+     */
     async startBackground(command) {
+        // `command` is a COMPOUND shell line (lspStartCommand: `cd … && ENV=… node bridge.cjs`) — nohup takes a
+        // single executable, so wrap the whole line in `sh -c`. Caught live: `nohup cd …` silently started nothing
+        // and the bridge connect timed out (gate#2 k8s-LSP attempt 1).
         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)
@@ -643,7 +866,7 @@ export class RemoteK8sExecutionEnv {
         const c = await this.ensureConnected();
         if (!c.ok)
             throw new RemoteExecutionError("connect_failed", c.error.message, c.error);
-        this.inFlightExecs++;
+        this.inFlightExecs++; // suspendVM refuses while > 0 (council #4); decremented in the finally below
         const queue = [];
         let finished = false;
         let failure;
@@ -656,12 +879,21 @@ export class RemoteK8sExecutionEnv {
         };
         let lastChunk = Date.now();
         const idleMs = options?.readTimeoutMs ?? this.cfg.livenessMs;
+        // Total-output cap (D2): parity with the host/local-docker execStream — when the caller sets
+        // maxOutputBytes, count yielded bytes and abort+throw past the cap (the finally's ac.abort() then closes
+        // the exec socket). Previously k8s execStream IGNORED maxOutputBytes (it was the only adapter that did).
         const cap = options?.maxOutputBytes;
         let bytes = 0;
+        // Internal abort composed with the caller's: EVERY generator exit (normal end, idle-throw, consumer
+        // early-break via .return()) must settle runExec IMMEDIATELY — without this, the finally's `await done`
+        // would sit until runExec's own liveness fired (~minutes) with the exec socket held open (self-review A).
         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,
+            // The consumer reads from the onStdout/onStderr callbacks (full chunks); runExec's retained buffer is
+            // discarded here (only exitCode is used). boundOutput:true caps that otherwise-unbounded retained buffer
+            // with zero change to what the stream consumer sees (D2).
             boundOutput: true,
             onStdout: (d) => {
                 lastChunk = Date.now();
@@ -677,9 +909,12 @@ export class RemoteK8sExecutionEnv {
             if (r.ok)
                 exitCode = r.value.exitCode;
             else {
+                // Map the buffered-exec ExecutionErrorCode → a RemoteExecutionErrorCode. `spawn_error`/`shell_unavailable`
+                // mean the environment is fundamentally broken → "unknown" (non-retryable), NOT "connect_failed" (which
+                // the retry whitelist would re-attempt against a broken shell — council BUG#2).
                 const code = r.error.code === "aborted"
                     ? "aborted"
-                    : r.error.code === "transport_lost"
+                    : r.error.code === "transport_lost" // typed end-to-end since core 1.89 (was a message marker)
                         ? "transport_lost"
                         : r.error.code === "timeout"
                             ? "timeout"
@@ -720,11 +955,23 @@ export class RemoteK8sExecutionEnv {
             yield { type: "exit", exitCode };
         }
         finally {
-            ac.abort();
+            ac.abort(); // settle runExec now (no-op if already finished) — closes the socket, frees the timers
             await done.catch(() => { });
             this.inFlightExecs--;
         }
     }
+    // ─────────────────────────── design/103 background shell (TOB, path ①) ───────────────────────────
+    //
+    // kata/k8s takes path ① (design/103 §5.2): the pod filesystem buffers output, re-read by byte cursor each poll
+    // — unlike E2B there is no provider job handle, and closing the exec socket does NOT kill the remote process
+    // (disposable-pod posture, see file header), so termination is detected by an exit-sentinel file and kill goes
+    // through the process GROUP (`setsid` + self-reported pgid). Background ops run as short ephemeral execs and
+    // deliberately do NOT touch `inFlightExecs` (they are control-plane management, not a foreground command to
+    // snapshot; the detached job is killed before `suspendVM` by the core dispose saga, design/103 §3.7).
+    /**
+     * A background job cannot outlive its pod (`activeDeadlineSeconds` ≈ `timeoutMs`), so the BG ceiling is clamped to
+     * it (assigned in the constructor — `this.cfg` is set there, so a field initializer would read it pre-init).
+     */
     backgroundCapabilities;
     _bgManager;
     get bgManager() {
@@ -737,9 +984,11 @@ export class RemoteK8sExecutionEnv {
             async launch(command, options, ctx) {
                 const conn = await self.ensureConnected();
                 if (!conn.ok)
-                    throw new Error(`pod connect failed: ${conn.error.message}`);
+                    throw new Error(`pod connect failed: ${conn.error.message}`); // → manager wraps as spawn_failed
                 const jobId = randomUUID();
                 const dir = `${K8S_BG_DIR_ROOT}/${jobId}`;
+                // 🔴 secret-scrub red line (design/103 §3.1): cwd + env injected via the SAME `withCwdEnv` path as exec —
+                // the host process.env is never injected; only the scrubbed task env core passes reaches the child.
                 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");
@@ -749,10 +998,12 @@ export class RemoteK8sExecutionEnv {
                 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;
+                void ctx; // k8s is pull-model: termination is discovered in read(); ctx.onTerminal is intentionally unused
                 return { jobId, dir, stdoutCursor: 0, stderrCursor: 0 };
             },
             async read(state) {
+                // ADOPT (memory) mode: the still-open exec socket feeds the drain buffers; termination is PUSH-model
+                // (socket close → ctx.onTerminal), so `read` never reports terminal here — mirror of the E2B/host adopt.
                 if (state.adopt) {
                     const o = drainMemStream(state.adopt.mem.out);
                     const e = drainMemStream(state.adopt.mem.err);
@@ -770,15 +1021,20 @@ export class RemoteK8sExecutionEnv {
                 if (!p)
                     throw new Error("background poll: unparseable response");
                 if (p.gone) {
+                    // dir vanished while still owned (dispose clears the registry FIRST, so this isn't us) → abnormal end.
                     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;
+                // Terminal: exit sentinel present → exited (exit code known); else process group gone without a sentinel →
+                // failed (abnormal — a clean exit always writes the sentinel as the runner's last act before the group dies).
                 let terminal = p.exitCode !== undefined ? { failed: false, exitCode: p.exitCode } : !p.alive ? { failed: true } : undefined;
+                // 🔴 disk guard: direct redirect has no in-pod cap, so reap a runaway whose output exceeds K8S_BG_FILE_CAP
+                // (the kata VM isolates the blast to this disposable pod; the BG-timeout + activeDeadlineSeconds also bound it).
                 if (!terminal && (p.outTotal > K8S_BG_FILE_CAP || p.errTotal > K8S_BG_FILE_CAP)) {
-                    void bgExec(buildBgKillScript(state.dir), true).catch(() => { });
+                    void bgExec(buildBgKillScript(state.dir), true).catch(() => { }); // fire-and-forget reap
                     terminal = { failed: true };
                 }
                 return {
@@ -790,21 +1046,23 @@ export class RemoteK8sExecutionEnv {
                 };
             },
             async kill(state) {
-                await bgExec(buildBgKillScript(state.dir), true).catch(() => { });
+                await bgExec(buildBgKillScript(state.dir), true).catch(() => { }); // best-effort, idempotent
             },
             async disposeOne(state) {
+                // Adopted shells hold the (kept-open) exec socket — release it on EVERY dispose path, even when the pod
+                // is already being torn down (the socket is a worker-side resource, not a pod-side one).
                 const closeAdopted = () => {
                     if (!state.adopt)
                         return;
                     try {
                         (state.adopt.sock.terminate ?? state.adopt.sock.close).call(state.adopt.sock);
                     }
-                    catch { }
+                    catch { /* already gone */ }
                 };
                 if (self.destroyed) {
                     closeAdopted();
                     return;
-                }
+                } // pod teardown reaps the job; don't resurrect a connection
                 await bgExec(buildBgDisposeScript(state.dir), true).catch(() => { });
                 closeAdopted();
             },
@@ -820,8 +1078,11 @@ export class RemoteK8sExecutionEnv {
         return this.bgManager.kill(shellId);
     }
     disposeBackgroundShells(opts) {
+        // 签名统一带 opts(core 尾调 {except: keepAlive})。隔离 env 的留活是名义的——沙箱拆机进程必然随之
+        // 消亡(destroy 整体带走),core 的 envDying settle 会先给准确 killed 回执;透传保证签名不静默丢参。
         return this._bgManager ? this._bgManager.dispose(opts) : Promise.resolve();
     }
+    // ─────────────────────────────── FileSystem (over exec; real exit codes) ───────────────────────────────
     async absolutePath(p) {
         return ok(this.resolve(p));
     }
@@ -830,9 +1091,11 @@ export class RemoteK8sExecutionEnv {
     }
     async readBinaryFile(p, abortSignal) {
         const abs = this.resolve(p);
+        // base64 keeps the WS text-safe; the REAL exit code separates "empty file" from "read failed".
         const r = await this.execData(`base64 < ${shellQuote(abs)}`, abortSignal);
         if (!r.ok)
             return { ok: false, error: fileErrorFromExec(r.error, abs) };
+        // Non-zero base64 read → central classifier, not_found fallback (truncated-stderr tolerant — council BUG#3).
         if (r.value.exitCode !== 0)
             return { ok: false, error: classifyFsStderr(r.value.stderr, abs, "not_found") };
         return ok(new Uint8Array(Buffer.from(r.value.stdout.replace(/\s+/g, ""), "base64")));
@@ -852,6 +1115,11 @@ export class RemoteK8sExecutionEnv {
             lines = lines.slice(0, options.maxLines);
         return ok(lines);
     }
+    /** 父目录自建(与 host/local-docker/adb/ssh 同口径)。抽成共用是因为 `appendFile` 曾**绕过**它:
+     *  🔴 2026-07-25 实测的跨腿分叉 —— `appendFile` 直接调 `writeChunked`,整条路上没有 `mkdir -p`,于是
+     *  「直接 append 建一个新日志路径」在 k8s 腿上返 `not_found`,而其余 5 腿都成功(host/local-docker/adb 实测,
+     *  ssh/e2b 由方法体判据)。core 的后台输出镜像正是"每拍 append 一次"的形,这条分叉会让它在 k8s 腿上从第一拍
+     *  就失败,而 `mirrorFailed` 只会表现成一句「output file is INCOMPLETE」。 */
     async ensureParentDir(abs, abortSignal) {
         const dir = path.posix.dirname(abs);
         if (!dir || dir === "." || dir === "/")
@@ -868,15 +1136,21 @@ export class RemoteK8sExecutionEnv {
         const bad = await this.ensureParentDir(abs, abortSignal);
         if (bad)
             return bad;
-        return this.writeChunked(abs, content, true, abortSignal);
+        return this.writeChunked(abs, content, true, abortSignal); // truncate first
     }
     async appendFile(p, content, abortSignal) {
         const abs = this.resolve(p);
-        const bad = await this.ensureParentDir(abs, abortSignal);
+        const bad = await this.ensureParentDir(abs, abortSignal); // 见 ensureParentDir 旁注:此前这条路漏了它
         if (bad)
             return bad;
-        return this.writeChunked(abs, content, false, abortSignal);
+        return this.writeChunked(abs, content, false, abortSignal); // append from byte 0
     }
+    /**
+     * Write `content` to `abs` via argv-embedded base64, chunked at WRITE_CHUNK_BYTES (no stdin on the exec
+     * channel we use; v4 has no per-channel close). `truncateFirst` → the FIRST chunk uses `>` (overwrite),
+     * the rest `>>` (append); `false` → all chunks `>>`. Empty content still runs exactly one command so an
+     * empty file is created (write) / left intact (append). Shared by writeFile/appendFile (council DESIGN#2).
+     */
     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) {
@@ -890,6 +1164,9 @@ export class RemoteK8sExecutionEnv {
         }
         return ok(undefined);
     }
+    // ── design/158 B6:POSIX shell-out 文件面全部委托共享基座(posix-shell-fs.ts)─────────────────────
+    // 六裁决(`--`/classifyFsStderr/ls -1A/mv 后缀形/temp 位置参数化/`[ -e ]||[ -L ]` exists)与
+    // readLink・lstat 契约见基座头注;本腿此前的 fileErrorFrom 分类形与 exists 形即基座正形的出处。
     posixFsInst;
     get posixFs() {
         return (this.posixFsInst ??= createPosixShellFs({
@@ -925,6 +1202,8 @@ export class RemoteK8sExecutionEnv {
     async createTempFile(options) {
         return this.posixFs.createTempFile(options);
     }
+    // ─────────────────────────────── helpers ───────────────────────────────
+    /** exec with the data-transfer bound (large reads/writes legitimately run longer than a control op). */
     async execData(command, abortSignal) {
         const c = await this.ensureConnected();
         if (!c.ok)
@@ -943,7 +1222,14 @@ export class RemoteK8sExecutionEnv {
         return parts.join(" ");
     }
 }
+/**
+ * `ExecutionEnvFactory` for the k8s pod-sandbox backend — one fresh (unconnected) env per task; the pod is
+ * created lazily on connect and deleted by `destroy()` (Runner-owned lifetime; `activeDeadlineSeconds` is the
+ * leak guard if destroy never runs).
+ */
 export function k8sExecutionEnvFactory(config) {
+    // Thread the task's sessionId so workspace-snapshot keys are namespaced per session
+    // (workspaces/<prefix>/<sessionId>/<snapshotId>.tar.gz).
     return (ctx) => new RemoteK8sExecutionEnv({ ...config, sessionId: ctx.sessionId });
 }
 //# sourceMappingURL=remote-env-k8s.js.map