@sema-agent/server 1.322.0 → 2.0.0

package/dist/plugins/image-index-sql.js

@@ -1,8 +1,56 @@
+/**
+ * Sandbox-image-pool INDEX store (IMAGE-API-DESIGN.md §1, pool design §8) — SINGLE-FILE DUAL-DIALECT
+ * (design/158 A12 定型半场). ONE implementation, TWO dialects; the historical `TiDBImageIndex` /
+ * `PgImageIndex` class names survive as thin ctor subclasses so every consumer (store-backend.ts,
+ * pg-pool.ts, the unit + real-DB suites) is untouched.
+ *
+ * One row per published/building image DIGEST — the immutable runtime ref (design §6: refs are @sha256:...).
+ * A queryable projection of build.sh's replay-sufficient `sandbox-manifest.json` + the publish lifecycle
+ * `status` (building → published → deprecated / failed). This is the SINGLE SOURCE OF TRUTH for "what can a
+ * sandbox run"; `POST /v1/images/select` resolves a profile → digest off it (the §7 per-sandbox hot path).
+ *
+ * Visibility is enforced IN THE QUERY (Codex A1, mirrors the assistant per-user scoping): a tenant principal
+ * sees `public` rows + its OWN `tenant` rows only; an operator sees all. mapRow/ImageRow are the row-mapping
+ * surface shared by BOTH dialects — they live in the backend-neutral store-contracts.ts (design/158 A3 沉底).
+ *
+ * ── Dialect deltas, kept EXPLICIT ────────────────────────────────────────────────────────────────────
+ *   - `?` placeholders vs positional `$n` (and the placeholder-arity fallout in `list`/`setStatus`, which
+ *     track a running `$n` index; TiDB's `?` needs no such bookkeeping).
+ *   - upsert form: `ON DUPLICATE KEY UPDATE … VALUES(col)` vs `ON CONFLICT (id) DO UPDATE SET … EXCLUDED.col`.
+ *   - the MONOTONIC de-publish guard (IMAGE-API-DESIGN.md §P2.10 / wq64gmm5e): `IF(status='published', old,
+ *     new)` vs `CASE WHEN … status = 'published' THEN old ELSE new END` — status/visibility/tenant_id/signed
+ *     are ALL preserved on a live published row in BOTH dialects.
+ *   - JSON columns: TiDB `JSON.stringify` verbatim vs PG `pgSafeJsonStringify` + `$n::jsonb` casts (lossy —
+ *     this is an observation-layer blob, not a trust-boundary payload, so `pgSafeJsonStringify`'s U+FFFD
+ *     replacement is acceptable; codex R15).
+ *   - PG-only identity-axis validation (codex R17-H1/R19): `repo` (the `idFor` hash input + the `(repo,digest)`
+ *     unique-key equivalence premise) and `tenantId` reject unstorable bytes UP FRONT (`pgHasUnstorable` →
+ *     `PgUnstorableError`) rather than silently mangling them — a rewrite would fork the hash id from the
+ *     stored column (same `(repo,digest)` collides the unique key while `ON CONFLICT (id)` doesn't match,
+ *     wedging registration permanently). TiDB has no equivalent NUL/lone-surrogate constraint, so it stores
+ *     verbatim. Same-family scalar sanitize (tag/recipeGitSha/generatorVersion/supersedes — codex R16) is
+ *     PG-only for the same reason; identity columns (repo/tenantId/digest/manifestSha) are reject-not-rewrite.
+ *   - null-safe ordering trick: `ORDER BY (build_date IS NULL), build_date DESC` vs `ORDER BY build_date DESC
+ *     NULLS LAST` (same semantics, dialect-native syntax).
+ *   - capability-flag predicate: `JSON_EXTRACT(capabilities, '$.key') = true` vs `capabilities -> 'key' =
+ *     'true'::jsonb` (NOT a `::boolean` cast, which hard-errors on non-boolean jsonb and aborts the query;
+ *     the jsonb equality yields false instead, matching MySQL's exclude-don't-throw semantics for a present
+ *     but non-boolean capability value, e.g. `nestedBuildMode`).
+ *   - affectedRows vs rowCount, BIGINT (`size_bytes`) read back as a STRING on PG (via SqlDriver / mapImageRow).
+ *   - schema ownership: TiDB DDL lives in tidb-pool.ts; the PG DDL is exported from HERE
+ *     (PG_IMAGE_INDEX_SCHEMA + ensureSchema, self-contained for the integration test).
+ */
 import { createHash } from "node:crypto";
 import { pgSafeJsonStringify, pgSanitizeText, pgHasUnstorable, PgUnstorableError } from "./pg-safe-json.js";
-import { mapImageRow as mapRow, } from "./store-contracts.js";
+import { 
+// mapRow/ImageRow are the row-mapping surface shared by BOTH SQL twins — they live in the
+// backend-neutral store-contracts.ts (design/158 A3 沉底; no adapter imports its twin).
+mapImageRow as mapRow, } from "./store-contracts.js";
 import { mysqlDriver, pgDriver } from "./sql-driver.js";
 export { mapImageRow as mapRow } from "./store-contracts.js";
+/** PG translation of the `sandbox_image_index` DDL in tidb-pool.ts (JSON→JSONB, DATETIME(3)→TIMESTAMPTZ(3),
+ *  TINYINT(1)→SMALLINT(布尔列 PG 映射归一,clay 批 2026-07-26 —— 两方言读回同为 number,写入 0/1,
+ *  读侧 `!!` 保持,出口 JS 类型不变), inline UNIQUE KEY/KEY → separate CREATE UNIQUE INDEX / CREATE INDEX). */
 export const PG_IMAGE_INDEX_SCHEMA = [
     `CREATE TABLE IF NOT EXISTS sandbox_image_index (
      id                 VARCHAR(64)  NOT NULL,
@@ -33,12 +81,14 @@ export const PG_IMAGE_INDEX_SCHEMA = [
     `CREATE INDEX IF NOT EXISTS idx_digest ON sandbox_image_index (digest)`,
     `CREATE INDEX IF NOT EXISTS idx_tenant ON sandbox_image_index (tenant_id, status)`,
 ];
+/** Idempotent self-contained schema apply (for the integration test; central aggregation is done separately). */
 export async function ensureSchema(pool) {
     for (const stmt of PG_IMAGE_INDEX_SCHEMA)
         await pool.query(stmt);
 }
 const MAX_LIMIT = 200;
 const DEFAULT_LIMIT = 50;
+/** `(visibility='public' OR tenant_id=?)` unless operator. TiDB form — `?` needs no index bookkeeping. */
 function visibilityClauseTidb(viewer) {
     if (viewer.operator)
         return { sql: "1=1", params: [] };
@@ -46,6 +96,7 @@ function visibilityClauseTidb(viewer) {
         return { sql: "(visibility='public' OR tenant_id=?)", params: [viewer.tenantId] };
     return { sql: "visibility='public'", params: [] };
 }
+/** PG form — positional `$n`, with a running index the caller continues from (PG has no anonymous `?`). */
 function visibilityClausePg(viewer, startIdx) {
     if (viewer.operator)
         return { sql: "1=1", params: [], nextIdx: startIdx };
@@ -71,6 +122,7 @@ function decodeCursor(c) {
         return null;
     }
 }
+/** TiDB upsert/registerBuilding params — the array literal is IDENTICAL text at both TiDB call sites. */
 function tidbUpsertParams(e, id, now) {
     return [
         id, e.profile, JSON.stringify(e.bands ?? []), e.repo, e.tag, e.digest,
@@ -85,12 +137,17 @@ const PG_UPSERT_COLS = "(id, profile, bands, repo, tag, digest, toolchain_versio
     "status, visibility, tenant_id, manifest_sha, recipe_git_sha, generator_version, build_date, supersedes, " +
     "signed, created_at, updated_at)";
 const PG_UPSERT_VALUES = "($1,$2,$3::jsonb,$4,$5,$6,$7::jsonb,$8::jsonb,$9::jsonb,$10,$11,$12,$13,$14,$15,$16,$17,$18,$19,$20,$21)";
+/** PG upsert/registerBuilding params — deep-sanitized JSON (observation-layer, R15) + same-family scalar
+ *  sanitize (R16); identity columns (repo/tenantId/digest/manifestSha) are reject-not-rewrite (validated by
+ *  the caller BEFORE this runs — see the `pgHasUnstorable` guards in `upsert`/`registerBuilding`). */
 function pgUpsertParams(e, id, now) {
     return [
         id,
         pgSanitizeText(e.profile),
-        pgSafeJsonStringify(e.bands ?? []),
-        e.repo,
+        pgSafeJsonStringify(e.bands ?? []), // R15:元数据 jsonb 四位=观测层(嵌套值可含外部构建产物文本)
+        // codex R16:register 面标量只做类型检查——tag/tenantId/generatorVersion/supersedes 可携脏字节,
+        // 同族观测标量一并 sanitize(digest/manifestSha 恒 hex 恒等;identity 值 sanitize 恒等=零行为差)。
+        e.repo, // R17-H1:repo=身份(idFor 哈希输入)——入口拒绝式,列存原文(见 upsert/registerBuilding)
         pgSanitizeText(e.tag),
         e.digest,
         pgSafeJsonStringify(e.toolchainVersions ?? {}),
@@ -99,7 +156,7 @@ function pgUpsertParams(e, id, now) {
         e.sizeBytes,
         e.status,
         e.visibility,
-        e.tenantId ?? null,
+        e.tenantId ?? null, // R19:tenantId=租户身份轴——入口拒绝式(改写=可见性归属漂移),列存原文
         e.manifestSha ?? null,
         e.recipeGitSha == null ? null : pgSanitizeText(e.recipeGitSha),
         e.generatorVersion == null ? null : pgSanitizeText(e.generatorVersion),
@@ -110,18 +167,24 @@ function pgUpsertParams(e, id, now) {
         now,
     ];
 }
+/** Dual-dialect INDEX store. See the file header for the dialect-delta ledger. */
 export class SqlImageIndex {
     db;
     constructor(db) {
         this.db = db;
     }
+    /** Pick the dialect's SQL text. Both statements stay written out at the call site ON PURPOSE. */
     q(tidb, pg) {
         return this.db.dialect === "tidb" ? tidb : pg;
     }
+    /** Stable index id = sha256(repo@digest) — identity is the digest, not the mutable tag. */
     static idFor(repo, digest) {
         return createHash("sha256").update(`${repo}@${digest}`).digest("hex").slice(0, 64);
     }
+    /** Register or update an index row (idempotent on repo+digest). Returns the row id. */
     async upsert(e) {
+        // 🔴 PG-only identity-axis validation (codex R17-H1/R19) — TiDB has no NUL/lone-surrogate column
+        // constraint, so it stores repo/tenantId verbatim; PG rejects up front (see file-header dialect delta).
         if (this.db.dialect === "pg") {
             if (pgHasUnstorable(e.repo))
                 throw new PgUnstorableError("image repo (identity)");
@@ -153,7 +216,31 @@ export class SqlImageIndex {
            supersedes = EXCLUDED.supersedes, signed = EXCLUDED.signed, updated_at = EXCLUDED.updated_at`), this.db.dialect === "tidb" ? tidbUpsertParams(e, id, now) : pgUpsertParams(e, id, now));
         return id;
     }
+    /**
+     * STATUS-MONOTONIC register (IMAGE-API-DESIGN.md §P2.10 MUST-FIX) — the auto-register path the bake runner uses.
+     *
+     * `upsert` does an UNCONDITIONAL upsert: a re-ingested `done` (at-least-once from the runner) or a P2 bake of
+     * a digest P3 already PROMOTED would flip a live `published` row back to `building`, and `latestPublished`
+     * (`WHERE status='published'`) then DE-PUBLISHES a live, in-use image → sandbox-create 404s. This guarded path
+     * NEVER downgrades a `published` row: on a fresh row it inserts (`status:'building'` by default); on an
+     * existing row it updates the manifest projection + bumps `updated_at` but writes `status` only when the row
+     * isn't already `published` — a late/duplicate `done` for an already-promoted digest is a no-op on the
+     * lifecycle, never a regression. Returns the row id.
+     *
+     * Distinct from the unconditional `upsert` (kept for the seed + the operator `/v1/images/register` path); this
+     * is the bake auto-register's ONLY write into the index. Default status is `building` (P2 registers
+     * node-local/quarantine `building` artifacts; P3's verify gate is what flips `building → published`).
+     *
+     * The `IF(...published...)` (TiDB) / `CASE WHEN...published...` (PG) guards are the monotonic de-publish
+     * defense: once a row is `published` and live, a re-register must NOT downgrade `status` NOR flip the
+     * columns `latestPublished` filters on. wq64gmm5e: guarding only `status` left `visibility`/`tenant_id`
+     * (and `signed`) overwritable, so a re-register with visibility=private/tenant or a different tenant_id
+     * silently dropped a live row out of every viewer's `latestPublished` — an effective de-publish. ALL FOUR
+     * (status/visibility/tenant_id/signed) are gated identically in BOTH dialects; non-published rows still
+     * take the freshest projection.
+     */
     async registerBuilding(e) {
+        // 🔴 PG-only identity-axis validation (codex R17-H1/R19) — same rationale as `upsert` above.
         if (this.db.dialect === "pg") {
             if (pgHasUnstorable(e.repo))
                 throw new PgUnstorableError("image repo (identity)");
@@ -199,10 +286,15 @@ export class SqlImageIndex {
         const { rows } = await this.db.query(this.q("SELECT * FROM sandbox_image_index WHERE id=? LIMIT 1", "SELECT * FROM sandbox_image_index WHERE id = $1 LIMIT 1"), [id]);
         return rows[0] ? mapRow(rows[0]) : null;
     }
+    /** By immutable digest — what a running sandbox was built from. */
     async getByDigest(digest) {
         const { rows } = await this.db.query(this.q("SELECT * FROM sandbox_image_index WHERE digest=? ORDER BY updated_at DESC LIMIT 1", "SELECT * FROM sandbox_image_index WHERE digest = $1 ORDER BY updated_at DESC LIMIT 1"), [digest]);
         return rows[0] ? mapRow(rows[0]) : null;
     }
+    /** The newest PUBLISHED, viewer-visible digest for a profile — the `select` resolution.
+     *  🔴 genuinely-divergent shape (not just SQL text): TiDB's `visibilityClauseTidb` needs no placeholder
+     *  index (anonymous `?`); PG's `visibilityClausePg` threads a running `$n` index the caller continues
+     *  from. Also the null-safe ORDER BY trick differs ((build_date IS NULL) vs NULLS LAST) — same semantics. */
     async latestPublished(profile, viewer) {
         if (this.db.dialect === "tidb") {
             const vis = visibilityClauseTidb(viewer);
@@ -217,6 +309,13 @@ export class SqlImageIndex {
         ORDER BY build_date DESC NULLS LAST, created_at DESC LIMIT 1`, [profile, ...vis.params]);
         return rows[0] ? mapRow(rows[0]) : null;
     }
+    /**
+     * Paginated, viewer-scoped catalog query (the UI's list). Keyset cursor on (created_at, id) desc.
+     * 🔴 genuinely-divergent shape: the PG arm threads an explicit `$n` index through every optional predicate
+     * (node-pg has no anonymous placeholder); the TiDB arm just appends `?` in call order. Kept as two full
+     * branches rather than a shared placeholder-numbering helper (sql-driver.ts STEP 3/4) — a reviewer sees each
+     * dialect's real query shape, not a generated abstraction over it.
+     */
     async list(filter) {
         const limit = Math.min(Math.max(1, filter.limit ?? DEFAULT_LIMIT), MAX_LIMIT);
         let rawRows;
@@ -233,6 +332,7 @@ export class SqlImageIndex {
                 params.push(filter.status);
             }
             if (filter.capability) {
+                // JSON boolean true for the capability key.
                 where.push("JSON_EXTRACT(capabilities, ?) = true");
                 params.push(`$.${filter.capability}`);
             }
@@ -262,6 +362,11 @@ export class SqlImageIndex {
                 params.push(filter.status);
             }
             if (filter.capability) {
+                // JSON boolean true for the capability key. Compare at the jsonb layer (NOT a ::boolean cast): a
+                // `::boolean` cast HARD-ERRORS on any non-boolean jsonb value (string/number/JSON null) and aborts the
+                // whole query, whereas `= 'true'::jsonb` yields false for those — faithfully reproducing MySQL's
+                // `JSON_EXTRACT(...) = true` semantics (a present-but-non-boolean cap, e.g.
+                // nestedBuildMode="rootless-buildkit", simply excludes the row).
                 where.push(`capabilities -> $${idx++} = 'true'::jsonb`);
                 params.push(filter.capability);
             }
@@ -287,11 +392,13 @@ export class SqlImageIndex {
             nextCursor = encodeCursor({ createdAt: last.createdAt, id: last.id });
         }
         if (filter.latestOnly) {
+            // collapse to the newest row per profile (rows are already build/created-desc within the page).
             const seen = new Set();
             entries = entries.filter((e) => (seen.has(e.profile) ? false : (seen.add(e.profile), true)));
         }
         return { entries, nextCursor };
     }
+    /** Lifecycle transition (atomic-publish: building→published, or →failed/deprecated). */
     async setStatus(id, status, opts) {
         if (this.db.dialect === "tidb") {
             const sets = ["status=?", "updated_at=?"];
@@ -315,11 +422,13 @@ export class SqlImageIndex {
         await this.db.query(`UPDATE sandbox_image_index SET ${sets.join(", ")} WHERE id = $${idx}`, params);
     }
 }
+/** MySQL-protocol (TiDB) binding — historical class name + ctor shape preserved. */
 export class TiDBImageIndex extends SqlImageIndex {
     constructor(pool) {
         super(mysqlDriver(pool));
     }
 }
+/** PostgreSQL binding — historical class name + ctor shape preserved. */
 export class PgImageIndex extends SqlImageIndex {
     constructor(pool) {
         super(pgDriver(pool));

package/dist/plugins/k8s-bg-scripts.d.ts

@@ -1,9 +1,42 @@
+/** The detached runner (base64'd into the pod, run under `setsid`). Self-reports pgid; streams output to out/err. */
 export declare function buildBgRunnerScript(dir: string): string;
+/** Short foreground launcher: writes cmd.sh + runner.sh, then `setsid`s the runner detached and returns immediately. */
 export declare function buildBgLauncherScript(dir: string, cmdShB64: string, runnerShB64: string): string;
+/** Poll script: emit totals + liveness + exit, then the new bytes per stream (base64, bounded by `readCap`). */
 export declare function buildBgPollScript(dir: string, stdoutCursor: number, stderrCursor: number, readCap: number): string;
+/** KillShell: graceful SIGTERM to the group, then a forced SIGKILL (idempotent — a dead group just errors out).
+ *  The `|| kill <pid>` fallback covers an ADOPTED exec whose pgid prelude self-reported `$$` without a `setsid`
+ *  (whether the k8s-exec'd sh is a group leader is runtime-dependent); a launch-mode runner is always setsid'd,
+ *  so its group kill succeeds and the fallback never fires there. */
 export declare function buildBgKillScript(dir: string): string;
+/** dispose: forced SIGKILL to the group + remove the job dir (no grace — teardown). Best-effort.
+ *  ⚠️ Deliberately NO pgid-wait (unlike {@link buildBgKillScript}, review #4): a create-then-abort adopt disposed
+ *  in the pre-mkdir window escapes THIS script — but every dispose path ends in pod deletion (task-end destroy;
+ *  suspendVM deletes the pod after the snapshot), so the escape is pod-lifetime-bounded, and a wait here would
+ *  add 2s × N shells to the suspend/teardown path for a sub-second window. Kill (the model-facing wall) waits. */
 export declare function buildBgDisposeScript(dir: string): string;
+/**
+ * design/116 detach: wrap a foreground exec so it is ADOPTABLE mid-flight, running the command as a real
+ * process-group LEADER so an adopted shell's KillShell / BG hard wall reap the WHOLE subtree.
+ *
+ * 🔴 review MED (why `setsid`, not bare `$$`): the wrapper `sh` that `kubectl exec` starts has a RUNTIME-DEPENDENT
+ * process group — under many container runtimes it is NOT its own group leader (its pgid is some ancestor's), so
+ * writing `$$` as the pgid and later `kill -$$` targets a group that does not exist → the fallback `kill $$` reaps
+ * only the wrapper, orphaning the command's children PAST the §3.6 hard wall (they keep streaming into the adopted
+ * shell's buffer until the pod's `activeDeadlineSeconds`). `setsid` starts the command in a NEW session ⇒ a new
+ * process group whose leader pid IS the backgrounded job pid, so `kill -<pid>` reaps the command and every
+ * descendant. The command's stdout/stderr fds (the exec socket's channels) are INHERITED across setsid — only the
+ * controlling terminal is dropped (there is none: kubectl-exec here is non-tty) — so output/exit still flow on the
+ * SAME WebSocket, which IS the adopted shell's feed. `wait` propagates the real exit code.
+ *
+ * The command is base64'd into a pod-side `cmd.sh` (no quoting hazard, mirrors the launch path). The pgid is written
+ * atomically (tmp+mv) AFTER the job forks, so a poll never reads a half-written id. Every step is best-effort: a pod
+ * without `setsid` (rare on the kata base image) degrades to the `$$` path (the pre-fix behavior), and a read-only
+ * /tmp degrades to a pgid-less adopt (kill no-ops; the disposable pod's teardown reaps) — never a broken exec. The
+ * EXIT trap removes the dir when the command ends normally, so non-detached execs don't litter the pod.
+ */
 export declare function buildDetachCapableExec(dir: string, command: string): string;
+/** Parsed background poll response. `gone` = the job dir vanished (abnormal). Byte counts drive cursor/dropped accounting. */
 export interface ParsedBgPoll {
     gone: boolean;
     outTotal: number;
@@ -15,5 +48,6 @@ export interface ParsedBgPoll {
     stderr: string;
     stderrBytes: number;
 }
+/** Parse {@link buildBgPollScript} stdout. Markers contain `_` (absent from the base64 alphabet) so they never collide. */
 export declare function parseBgPollOutput(raw: string): ParsedBgPoll | undefined;
 //# sourceMappingURL=k8s-bg-scripts.d.ts.map

package/dist/plugins/k8s-bg-scripts.js

@@ -1,13 +1,36 @@
+/**
+ * design/103 background-shell pod-side scripts (pure, exported for testing) + design/116 detach-capable exec —
+ * the k8s adapter's text generation/parsing layer for background shells (`buildBg*Script` ×5 +
+ * `buildDetachCapableExec` + `parseBgPollOutput`). Split out of `remote-env-k8s.ts` (design/158 A13,
+ * internal-lossless — `remote-env-k8s.ts` re-exports every symbol below unchanged).
+ *
+ * The pod-side runner is `setsid`'d into its OWN session so the whole job (cmd + its grandchildren) shares one
+ * process group we can group-kill (`kill -<pgid>`); the session leader self-reports its pgid (`$$`) so we never
+ * depend on `setsid &`'s `$!` (which is the short-lived parent). The command writes DIRECTLY to pod files (out/err),
+ * re-read by byte cursor each poll (path ① — survives the consume-once exec seam).
+ *
+ * 🔴 Why DIRECT redirect (`> out 2> err`), not a FIFO+`head` cap: on-box kata verification proved a FIFO+`head`
+ * pipeline block-buffers `head`'s stdout → the `out` file stays EMPTY until head's stdio buffer fills (KBs) or EOF,
+ * so `pollBackground` sees nothing for a slow streamer (the whole dev-server use case). Direct redirect makes the
+ * shell write each `echo` straight to the file → immediately pollable (the command's OWN buffering still applies,
+ * same as TOC/E2B's pipe). DISK bound: the pod has no native ephemeral cap, so a runaway producer is bounded by
+ * (a) the BG-timeout hard wall + pod `activeDeadlineSeconds`, and (b) a control-plane size guard in the driver's
+ * read() that reaps a job whose output exceeds `K8S_BG_FILE_CAP` (kata VM isolation already contains the blast to
+ * this one disposable pod). per-poll TRANSFER stays bounded by the readCap in buildBgPollScript regardless.
+ */
 import { shellQuote } from "./remote-shell.js";
+/** The detached runner (base64'd into the pod, run under `setsid`). Self-reports pgid; streams output to out/err. */
 export function buildBgRunnerScript(dir) {
     const q = (name) => shellQuote(`${dir}/${name}`);
     return [
+        // 🔴 self-report the pgid: $$ is this (session-leader) shell's pid == the session/group id. Atomic write.
         `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`,
+        `sh ${q("cmd.sh")} > ${q("out")} 2> ${q("err")} < /dev/null`, // direct redirect → streaming-visible output
         `__RC=$?`,
-        `echo $__RC > ${q("exit.tmp")} 2>/dev/null && mv ${q("exit.tmp")} ${q("exit")} 2>/dev/null`,
+        `echo $__RC > ${q("exit.tmp")} 2>/dev/null && mv ${q("exit.tmp")} ${q("exit")} 2>/dev/null`, // exit sentinel = atomic
     ].join("\n");
 }
+/** Short foreground launcher: writes cmd.sh + runner.sh, then `setsid`s the runner detached and returns immediately. */
 export function buildBgLauncherScript(dir, cmdShB64, runnerShB64) {
     const d = shellQuote(dir);
     const q = (name) => shellQuote(`${dir}/${name}`);
@@ -15,14 +38,28 @@ export function buildBgLauncherScript(dir, cmdShB64, runnerShB64) {
         `mkdir -p ${d} && chmod 700 ${d}`,
         `printf %s '${cmdShB64}' | base64 -d > ${q("cmd.sh")}`,
         `printf %s '${runnerShB64}' | base64 -d > ${q("runner.sh")}`,
+        // detach into a new session (survives the exec socket close — disposable-pod posture / startBackground precedent)
         `setsid sh ${q("runner.sh")} >/dev/null 2>&1 &`,
+        // 🔴 Do NOT report launched until the runner has self-reported its pgid — otherwise a killBackground
+        // / timeout landing in the gap finds no pgid, no-ops, yet the manager marks the shell killed → a LEAKED process
+        // group. Bounded (~2s); the runner writes pgid as its very FIRST action, so this is one iteration in practice.
         `__i=0; while [ ! -s ${q("pgid")} ] && [ $__i -lt 40 ]; do __i=$((__i+1)); sleep 0.05; done`,
+        // 🔴 (workflow MED) Only report launched if the runner actually started (pgid present). If setsid is missing or the
+        // runner crashed before writing pgid, report failure → the driver surfaces spawn_failed instead of a phantom
+        // "running" shell that never ends until the BG timeout.
         `if [ -s ${q("pgid")} ]; then echo SEMABG_LAUNCHED; else echo SEMABG_NOPGID; fi`,
     ].join("\n");
 }
+/** Poll script: emit totals + liveness + exit, then the new bytes per stream (base64, bounded by `readCap`). */
 export function buildBgPollScript(dir, stdoutCursor, stderrCursor, readCap) {
     const d = shellQuote(dir);
-    const slice = (file, cursor) => [
+    const slice = (file, cursor) => 
+    // 🔴 (workflow MED) Read is bounded to the wc SNAPSHOT (__T), not to the live EOF — `head -c` caps the tail so a
+    // producer writing between `wc -c` and `tail` cannot return bytes past __T (the driver advances the cursor to __T,
+    // so reading past it would DUPLICATE next poll AND defeat the readCap transfer bound). ≤readCap new bytes → the
+    // whole increment [cursor, __T); otherwise the LAST readCap bytes [__T-readCap, __T) (recent tail, like TOC) and
+    // the control plane records the gap as bytesDroppedBeforeCursor.
+    [
         `__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;`,
@@ -31,6 +68,8 @@ export function buildBgPollScript(dir, stdoutCursor, stderrCursor, readCap) {
     ].join("\n");
     return [
         `if [ ! -d ${d} ]; then echo SEMABG_GONE; exit 0; fi`,
+        // `$(( ... + 0 ))` normalizes the byte count: it both defaults empty→0 AND strips the leading whitespace that
+        // BSD/macOS `wc -c < file` emits (GNU/Debian pods don't pad, but keep the META line parseable on either).
         `__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 - )`,
@@ -46,15 +85,33 @@ export function buildBgPollScript(dir, stdoutCursor, stderrCursor, readCap) {
         `echo SEMABG_X`,
     ].join("\n");
 }
+/** KillShell: graceful SIGTERM to the group, then a forced SIGKILL (idempotent — a dead group just errors out).
+ *  The `|| kill <pid>` fallback covers an ADOPTED exec whose pgid prelude self-reported `$$` without a `setsid`
+ *  (whether the k8s-exec'd sh is a group leader is runtime-dependent); a launch-mode runner is always setsid'd,
+ *  so its group kill succeeds and the fallback never fires there. */
 export function buildBgKillScript(dir) {
     const d = shellQuote(dir);
     return [
+        // 🔴 review LOW (Fable-5 #4 tightened): an ADOPTED shell (create-then-abort detach) can be killed in the
+        // sub-second window BEFORE its detach-capable exec even ran `mkdir` — let alone forked the job + wrote pgid.
+        // A bare read (or a dir-existence gate: the dir does not exist YET in that window, indistinguishable from
+        // "already ended + EXIT-trap-removed") would skip the kill yet report SEMABG_KILLED — a silent no-op, the
+        // command escapes the wall. So wait UNCONDITIONALLY for the pgid file (bounded ~2s, mirroring the LAUNCH
+        // path's pre-report pgid gate). Cost of the removed dir-gate: a kill racing the command's natural end (dir
+        // already EXIT-trap-removed) idles the full ~2s before no-op'ing — acceptable, because driver.kill only runs
+        // while the manager still believes the shell is running (that overlap window is sub-second), and the pod is
+        // disposable. For a launch-mode shell pgid is already present → first iteration exits (no-op).
         `__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");
 }
+/** dispose: forced SIGKILL to the group + remove the job dir (no grace — teardown). Best-effort.
+ *  ⚠️ Deliberately NO pgid-wait (unlike {@link buildBgKillScript}, review #4): a create-then-abort adopt disposed
+ *  in the pre-mkdir window escapes THIS script — but every dispose path ends in pod deletion (task-end destroy;
+ *  suspendVM deletes the pod after the snapshot), so the escape is pod-lifetime-bounded, and a wait here would
+ *  add 2s × N shells to the suspend/teardown path for a sub-second window. Kill (the model-facing wall) waits. */
 export function buildBgDisposeScript(dir) {
     const d = shellQuote(dir);
     return [
@@ -64,27 +121,54 @@ export function buildBgDisposeScript(dir) {
         `echo SEMABG_DISPOSED`,
     ].join("\n");
 }
+/**
+ * design/116 detach: wrap a foreground exec so it is ADOPTABLE mid-flight, running the command as a real
+ * process-group LEADER so an adopted shell's KillShell / BG hard wall reap the WHOLE subtree.
+ *
+ * 🔴 review MED (why `setsid`, not bare `$$`): the wrapper `sh` that `kubectl exec` starts has a RUNTIME-DEPENDENT
+ * process group — under many container runtimes it is NOT its own group leader (its pgid is some ancestor's), so
+ * writing `$$` as the pgid and later `kill -$$` targets a group that does not exist → the fallback `kill $$` reaps
+ * only the wrapper, orphaning the command's children PAST the §3.6 hard wall (they keep streaming into the adopted
+ * shell's buffer until the pod's `activeDeadlineSeconds`). `setsid` starts the command in a NEW session ⇒ a new
+ * process group whose leader pid IS the backgrounded job pid, so `kill -<pid>` reaps the command and every
+ * descendant. The command's stdout/stderr fds (the exec socket's channels) are INHERITED across setsid — only the
+ * controlling terminal is dropped (there is none: kubectl-exec here is non-tty) — so output/exit still flow on the
+ * SAME WebSocket, which IS the adopted shell's feed. `wait` propagates the real exit code.
+ *
+ * The command is base64'd into a pod-side `cmd.sh` (no quoting hazard, mirrors the launch path). The pgid is written
+ * atomically (tmp+mv) AFTER the job forks, so a poll never reads a half-written id. Every step is best-effort: a pod
+ * without `setsid` (rare on the kata base image) degrades to the `$$` path (the pre-fix behavior), and a read-only
+ * /tmp degrades to a pgid-less adopt (kill no-ops; the disposable pod's teardown reaps) — never a broken exec. The
+ * EXIT trap removes the dir when the command ends normally, so non-detached execs don't litter the pod.
+ */
 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 [
+        // Decode the command into a VARIABLE (not a pod-side file): a read-only-/tmp degrade must still RUN the command
+        // (review's degrade-safety case) — a file target under an un-creatable dir would leave nothing to run. `sh -c
+        // "$__cmd"` is byte-equivalent to sourcing a cmd.sh whose content is $__cmd. base64 has no quoting hazard.
         `__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 backgrounds the job as a new-session group leader; $! is that leader's pid == its pgid. Output fds are
+        // inherited (the exec socket), only the tty is dropped. `wait` blocks the wrapper until the job ends (or is
+        // group-killed) and yields its exit code — so exec/adopt semantics are unchanged, only the reap target is fixed.
         `  setsid sh -c "$__cmd" &`,
         `  __pg=$!`,
         `  ${writePgid('"$__pg"')}`,
         `  wait "$__pg"; __rc=$?`,
         `else`,
-        `  ${writePgid('"$$"')}`,
+        `  ${writePgid('"$$"')}`, // no setsid → best-effort $$ (pre-fix behavior; the pod base image ships setsid)
         `  sh -c "$__cmd"; __rc=$?`,
         `fi`,
         `exit $__rc`,
     ].join("\n");
 }
+/** Parse {@link buildBgPollScript} stdout. Markers contain `_` (absent from the base64 alphabet) so they never collide. */
 export function parseBgPollOutput(raw) {
     if (raw.includes("SEMABG_GONE")) {
         return { gone: true, outTotal: 0, errTotal: 0, alive: false, stdout: "", stdoutBytes: 0, stderr: "", stderrBytes: 0 };

package/dist/plugins/k8s-exec-protocol.d.ts

@@ -1,17 +1,50 @@
+/**
+ * The confined, ADDITIVE pod-spec patch ({@link PodSpecPatch}/{@link applyPodSpecPatch}) + the exec-socket TLS
+ * shape ({@link execSocketTlsOptions}) + the v4 channel status-frame parse ({@link exitCodeFromStatus}) — the
+ * k8s adapter's protocol/patch layer, independent of pod lifecycle. Split out of `remote-env-k8s.ts` (design/158
+ * A13, internal-lossless — `remote-env-k8s.ts` re-exports every symbol below unchanged).
+ */
+/**
+ * The confined, ADDITIVE pod-spec patch. Every field is purely additive —
+ * none can override the hard isolation invariants. This is the seam the RSI L8 immutable-mount probe + the
+ * graderEnvFactory need.
+ */
 export interface PodSpecPatch {
+    /** Appended to spec.volumes (e.g. a read-only configMap/secret/emptyDir for the immutable-oracle mount). */
     volumes?: unknown[];
+    /** Appended to the sandbox container's volumeMounts (e.g. { name, mountPath, readOnly:true } — the RO mount). */
     volumeMounts?: unknown[];
+    /** Merged into the POD-level securityContext (runAsNonRoot, fsGroup, seccompProfile, …). */
     podSecurityContext?: Record<string, unknown>;
+    /** Merged into the sandbox CONTAINER's securityContext (readOnlyRootFilesystem, capabilities.drop,
+     *  allowPrivilegeEscalation:false, …) — the hardening the L8 immutable-mount/isolation probes assert. */
     containerSecurityContext?: Record<string, unknown>;
+    /** Extra labels merged into metadata.labels (e.g. a grader/probe tag). */
     labels?: Record<string, string>;
 }
+/**
+ * Apply a {@link PodSpecPatch} to a sandbox pod object IN PLACE — purely ADDITIVE. Volumes + volumeMounts are
+ * APPENDED (never replaced); securityContext objects are shallow-MERGED onto any existing; labels are merged. It
+ * deliberately touches ONLY spec.volumes / spec.securityContext / containers[0].{volumeMounts,securityContext} /
+ * metadata.labels — so the hard isolation invariants (runtimeClassName, automountServiceAccountToken,
+ * restartPolicy, activeDeadlineSeconds, image, command) are preserved by construction. Pure + exported for testing.
+ */
 export declare function applyPodSpecPatch(pod: {
     metadata: {
         labels?: Record<string, string>;
     };
     spec: Record<string, unknown>;
 }, patch: PodSpecPatch): void;
+/**
+ * TLS options for the exec WebSocket, shaped for BOTH runtimes (2026-06-11 in-cluster drill finding):
+ * Bun's `ws` shim IGNORES node-ws's top-level `ca`/`rejectUnauthorized` (handshake fails against a
+ * cluster CA even with rejectUnauthorized:false) and reads a Bun-specific `tls` sub-object instead;
+ * Node's real `ws` uses the top-level keys and passes the unknown `tls` key harmlessly through to
+ * tls.connect. One merged shape serves both. Live-proven on build-host (probe: top-level ca → TLS handshake
+ * failed; tls.ca → OPEN).
+ */
 export declare function execSocketTlsOptions(ca: string | undefined, insecureTls: boolean): Record<string, unknown>;
+/** Parse the v4.channel.k8s.io status frame (channel 3) into an exit code, or a typed failure. */
 export declare function exitCodeFromStatus(statusJson: string): {
     exitCode: number;
 } | {

package/dist/plugins/k8s-exec-protocol.js

@@ -1,7 +1,26 @@
+/**
+ * The confined, ADDITIVE pod-spec patch ({@link PodSpecPatch}/{@link applyPodSpecPatch}) + the exec-socket TLS
+ * shape ({@link execSocketTlsOptions}) + the v4 channel status-frame parse ({@link exitCodeFromStatus}) — the
+ * k8s adapter's protocol/patch layer, independent of pod lifecycle. Split out of `remote-env-k8s.ts` (design/158
+ * A13, internal-lossless — `remote-env-k8s.ts` re-exports every symbol below unchanged).
+ */
+/**
+ * Apply a {@link PodSpecPatch} to a sandbox pod object IN PLACE — purely ADDITIVE. Volumes + volumeMounts are
+ * APPENDED (never replaced); securityContext objects are shallow-MERGED onto any existing; labels are merged. It
+ * deliberately touches ONLY spec.volumes / spec.securityContext / containers[0].{volumeMounts,securityContext} /
+ * metadata.labels — so the hard isolation invariants (runtimeClassName, automountServiceAccountToken,
+ * restartPolicy, activeDeadlineSeconds, image, command) are preserved by construction. Pure + exported for testing.
+ */
 export function applyPodSpecPatch(pod, patch) {
+    // 🔴 wq64gmm5e: a securityContext patch is a HARDENING seam — it may only TIGHTEN, never weaken the isolation
+    // the L8 gradeP1 premise depends on. A blind spread let privileged:true / allowPrivilegeEscalation:true /
+    // capabilities.add[SYS_ADMIN] / readOnlyRootFilesystem:false through verbatim (and the "cannot weaken" test was
+    // fake-green). Fail CLOSED on any privilege-escalating key so the docstring claim is actually enforced.
     assertHardeningOnly(patch.podSecurityContext, "podSecurityContext");
     assertHardeningOnly(patch.containerSecurityContext, "containerSecurityContext");
     if (patch.labels) {
+        // Additive + identity-preserving: merge the patch labels, then re-assert the base identity labels LAST so a
+        // patch can never clobber the app/managed-by labels the RBAC selectors + reaper key on (wq64gmm5e).
         const identity = {};
         for (const k of ["app", "managed-by"]) {
             const v = pod.metadata.labels?.[k];
@@ -11,6 +30,12 @@ export function applyPodSpecPatch(pod, patch) {
         pod.metadata.labels = { ...pod.metadata.labels, ...patch.labels, ...identity };
     }
     const spec = pod.spec;
+    // 🔴 Volumes are the SAME isolation-breach class as a privileged securityContext (review: workflow HIGH). Kata
+    // passes a hostPath through into the guest VM (virtio-fs/9p host share — NOT blocked by the VM boundary), so a
+    // `hostPath:{path:"/"}` volume mounts the k3s NODE root (containerd sock, other pods, host secrets) into the
+    // sandbox — defeating the L8 immutable-oracle integrity premise as completely as privileged:true. Reject any
+    // host-backed volume source; only pod-local sources (emptyDir/configMap/secret/projected/downwardAPI/ephemeral)
+    // are additive-safe.
     assertVolumesPodLocal(patch.volumes, "volumes");
     if (patch.volumes?.length)
         spec.volumes = [...(spec.volumes ?? []), ...patch.volumes];
@@ -24,6 +49,8 @@ export function applyPodSpecPatch(pod, patch) {
             container.securityContext = { ...(container.securityContext ?? {}), ...patch.containerSecurityContext };
     }
 }
+/** Fail-closed direction guard for a securityContext patch: reject any key that WEAKENS isolation. A patch may
+ *  drop capabilities + tighten, never escalate. Throws (caller surfaces as a provisioning failure). */
 function assertHardeningOnly(sc, where) {
     if (!sc)
         return;
@@ -43,12 +70,16 @@ function assertHardeningOnly(sc, where) {
     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)`);
+    // procMount:"Unmasked" re-exposes the masked /proc paths; seccompProfile:"Unconfined" disables syscall filtering —
+    // both WEAKEN confinement (review: workflow HIGH secondary), so they belong on the fail-closed list.
     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)');
 }
+/** Fail-closed guard for patch volumes: a Kata guest shares hostPath/csi/flexVolume sources from the NODE, so only
+ *  POD-LOCAL sources are additive-safe. Reject anything host-backed. Throws (caller surfaces as a provisioning fail). */
 function assertVolumesPodLocal(volumes, where) {
     if (!volumes?.length)
         return;
@@ -63,10 +94,19 @@ function assertVolumesPodLocal(volumes, where) {
         }
     }
 }
+/**
+ * TLS options for the exec WebSocket, shaped for BOTH runtimes (2026-06-11 in-cluster drill finding):
+ * Bun's `ws` shim IGNORES node-ws's top-level `ca`/`rejectUnauthorized` (handshake fails against a
+ * cluster CA even with rejectUnauthorized:false) and reads a Bun-specific `tls` sub-object instead;
+ * Node's real `ws` uses the top-level keys and passes the unknown `tls` key harmlessly through to
+ * tls.connect. One merged shape serves both. Live-proven on build-host (probe: top-level ca → TLS handshake
+ * failed; tls.ca → OPEN).
+ */
 export function execSocketTlsOptions(ca, insecureTls) {
     const caList = ca ? [ca] : undefined;
     return { ca: caList, rejectUnauthorized: !insecureTls, tls: { ca: caList, rejectUnauthorized: !insecureTls } };
 }
+/** Parse the v4.channel.k8s.io status frame (channel 3) into an exit code, or a typed failure. */
 export function exitCodeFromStatus(statusJson) {
     try {
         const s = JSON.parse(statusJson);
@@ -74,6 +114,7 @@ export function exitCodeFromStatus(statusJson) {
             return { exitCode: 0 };
         const cause = s.details?.causes?.find((c) => c.reason === "ExitCode");
         if (cause?.message?.trim()) {
+            // trim-guard: Number("")/Number(" ") === 0 — an empty message must NOT read as a fake exit 0 on a Failure
             const code = Number(cause.message);
             if (Number.isFinite(code))
                 return { exitCode: code };