@sema-agent/server 7.43.0 → 7.44.0

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

@@ -1,55 +1,7 @@
-/**
- * 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 { 
-// 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 { mapImageRow as mapRow, } from "./store-contracts.js";
 import { mysqlDriver, pgDriver } from "./sql-driver.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) COLLATE "C"  NOT NULL,
@@ -80,14 +32,12 @@ export const PG_IMAGE_INDEX_SCHEMA = [
     `CREATE INDEX IF NOT EXISTS idx_sandbox_image_index_digest ON sandbox_image_index (digest)`,
     `CREATE INDEX IF NOT EXISTS idx_sandbox_image_index_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: [] };
@@ -95,7 +45,6 @@ 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 };
@@ -121,7 +70,6 @@ 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,
@@ -136,17 +84,12 @@ 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 ?? []), // R15:元数据 jsonb 四位=观测层(嵌套值可含外部构建产物文本)
-        // codex R16:register 面标量只做类型检查——tag/tenantId/generatorVersion/supersedes 可携脏字节,
-        // 同族观测标量一并 sanitize(digest/manifestSha 恒 hex 恒等;identity 值 sanitize 恒等=零行为差)。
-        e.repo, // R17-H1:repo=身份(idFor 哈希输入)——入口拒绝式,列存原文(见 upsert/registerBuilding)
+        pgSafeJsonStringify(e.bands ?? []),
+        e.repo,
         pgSanitizeText(e.tag),
         e.digest,
         pgSafeJsonStringify(e.toolchainVersions ?? {}),
@@ -155,7 +98,7 @@ function pgUpsertParams(e, id, now) {
         e.sizeBytes,
         e.status,
         e.visibility,
-        e.tenantId ?? null, // R19:tenantId=租户身份轴——入口拒绝式(改写=可见性归属漂移),列存原文
+        e.tenantId ?? null,
         e.manifestSha ?? null,
         e.recipeGitSha == null ? null : pgSanitizeText(e.recipeGitSha),
         e.generatorVersion == null ? null : pgSanitizeText(e.generatorVersion),
@@ -166,33 +109,18 @@ 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.
-     *
-     * @deprecated #193 车7(staleness-sweep P2-11):**生产零调用**——曾声称的 operator
-     * `/v1/images/register` 路径实际走 `registerBuilding`(routes/images.ts),本方法只剩集成测试当
-     * seed 口在用。危险语义原样保留着:UNCONDITIONAL upsert 会把 `published` 行打回 `building`
-     * (正是 §P2.10 静默 de-publish 病的成因,`registerBuilding` 因此才带 STATUS-MONOTONIC 守卫)。
-     * **禁止新增生产调用**;测试 seed 请优先走 `registerBuilding`(不需要覆盖语义时)。留而不删的
-     * 唯一理由=16 处 pg 集成测试 seed 依赖,整删随该套件下次翻新一并做。
-     */
     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)");
@@ -224,32 +152,7 @@ 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` (#193 车7 更正:那条 operator `/v1/images/register` 路径
-     * **也走本方法**——routes/images.ts:446 `idx.registerBuilding(...)`;`upsert` 已 @deprecated,只剩
-     * 测试 seed 在用)。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)");
@@ -295,15 +198,10 @@ 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);
@@ -318,13 +216,6 @@ 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;
@@ -341,7 +232,6 @@ 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}`);
             }
@@ -371,11 +261,6 @@ 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);
             }
@@ -401,13 +286,11 @@ 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=?"];
@@ -431,13 +314,11 @@ 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.js

@@ -1,36 +1,13 @@
-/**
- * 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`, // direct redirect → streaming-visible output
+        `sh ${q("cmd.sh")} > ${q("out")} 2> ${q("err")} < /dev/null`,
         `__RC=$?`,
-        `echo $__RC > ${q("exit.tmp")} 2>/dev/null && mv ${q("exit.tmp")} ${q("exit")} 2>/dev/null`, // exit sentinel = atomic
+        `echo $__RC > ${q("exit.tmp")} 2>/dev/null && mv ${q("exit.tmp")} ${q("exit")} 2>/dev/null`,
     ].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}`);
@@ -38,28 +15,14 @@ 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) => 
-    // 🔴 (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.
-    [
+    const slice = (file, cursor) => [
         `__N=$((__T - ${cursor}))`,
         `if [ "$__N" -gt 0 ]; then`,
         `  if [ "$__N" -le ${readCap} ]; then tail -c +$(( ${cursor} + 1 )) ${d}/${file} 2>/dev/null | head -c "$__N" | base64;`,
@@ -68,8 +31,6 @@ 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 - )`,
@@ -85,33 +46,15 @@ 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 [
@@ -121,54 +64,27 @@ 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('"$$"')}`, // no setsid → best-effort $$ (pre-fix behavior; the pod base image ships setsid)
+        `  ${writePgid('"$$"')}`,
         `  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.js

@@ -1,26 +1,7 @@
-/**
- * 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];
@@ -30,12 +11,6 @@ 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];
@@ -49,8 +24,6 @@ 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;
@@ -70,16 +43,12 @@ 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;
@@ -94,19 +63,10 @@ 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);
@@ -114,7 +74,6 @@ 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 };