@sema-agent/server 7.43.0 → 7.44.0

package/dist/auth-bridge.js

@@ -1,25 +1,9 @@
-/**
- * 鉴权桥 verifier(REGISTRY-REBUILD §5 M3 service 半场)——验 registry 铸的用户 access JWT,
- * `sub` 直喂既有 x-agent-principal 体系。规范=`@sema-agent/registry-core/api/auth-bridge` R1-R10(零 IO 纯契约,
- * 决策函数直接复用);本模块补齐 IO+crypto 半场:JWKS 拉取/缓存、RS256 真验签(node:crypto,零新依赖)。
- *
- * 信任模型:worker 已信 registry 的 effective config,同一信任根延伸到它的 JWKS——零新配置项
- * (issuer/jwksUrl 默认从 SEMA_REGISTRY_URL 派生;split 部署可 env 显式覆盖)。既有 SERVICE_AUTH_TOKEN(S)
- * 分支不动:bearer 长得像 JWT(三段 base64url)才走本分支(looksLikeJwt=路由预过滤,非校验)。
- *
- * R10:本模块任何路径不 log token/签名段/密钥材料——只 log kid + 错误码 + iss。
- */
 import { createPublicKey, verify as cryptoVerify } from "node:crypto";
 import { AUTH_BRIDGE_ALGS, DEFAULT_CLOCK_SKEW_SEC, DEFAULT_JWKS_REFRESH_MIN_INTERVAL_SEC, DEFAULT_OFFLINE_GRACE_SEC, REGISTRY_JWKS_PATH, RegistryJwks, classifyTimeClaims, jwksWithinOfflineGrace, shouldForceJwksRefresh, toVerifiedIdentity, } from "@sema-agent/registry-core/api/auth-bridge";
 const DEFAULT_JWKS_TTL_SEC = 15 * 60;
-/** JWKS 响应体字节上限(一个配错或超大响应的端点不应让 worker 无界缓冲;正常 JWKS 千字节级)。 */
 const MAX_JWKS_BYTES = 256 * 1024;
-/** 整 token 长度上限(签名段无独立上限,故对整 bearer 统一设限;正常 JWT ~1KiB)。 */
 const MAX_TOKEN_CHARS = 16 * 1024;
-/** 单段解码上限(header/payload)。 */
 const MAX_SEGMENT_BYTES = 64 * 1024;
-/** base64url 字符集严格校验——Node 的 base64url 解码会容忍集外字符(仍解出同一字节),而契约要求"三段
- *  base64url"形态严格,故解码前每段必须匹配该字符集。 */
 const B64URL_RE = /^[A-Za-z0-9_-]+$/;
 function b64urlJson(seg) {
     if (seg.length > MAX_SEGMENT_BYTES || !B64URL_RE.test(seg))
@@ -33,10 +17,6 @@ function b64urlJson(seg) {
     }
 }
 const stripSlash = (s) => s.replace(/\/+$/, "");
-/**
- * registry-JWT verifier(单例,进程级 JWKS 缓存)。`verify(bearer)` 全程不 throw——一切异常折为
- * AUTH_BRIDGE_ERROR_CODES(HTTP 面由调用方恒答 generic 401,码只进日志/metrics,R9)。
- */
 export function createRegistryJwtVerifier(opts) {
     const issuer = stripSlash(opts.issuer);
     const jwksUrl = opts.jwksUrl ?? `${issuer}${REGISTRY_JWKS_PATH}`;
@@ -46,14 +26,12 @@ export function createRegistryJwtVerifier(opts) {
     const jwksTtlSec = opts.jwksTtlSec ?? DEFAULT_JWKS_TTL_SEC;
     const doFetch = opts.fetchImpl ?? fetch;
     const now = opts.nowMs ?? Date.now;
-    // 进程级缓存(R3/R8 的状态面;shouldForceJwksRefresh/jwksWithinOfflineGrace 消费的快照即它)。
     const keys = new Map();
     let lastFetchAttemptMs;
     let lastFetchSuccessMs;
-    let inflight; // 并发 verify 合并成一次拉取(大量未知 kid 时不重复拉取)
+    let inflight;
     const fail = (error, kid) => {
         opts.metrics?.inc("auth_bridge_verify_total", { outcome: error });
-        // R10:仅 kid+码+iss。kid 来自**调用方可控**的 token header(16K token 上限内可到 ~10KB)——截断防日志放大。
         opts.logger?.warn?.("auth_bridge_rejected", { error, ...(kid ? { kid: kid.slice(0, 128) } : {}), iss: issuer });
         return { ok: false, error };
     };
@@ -66,19 +44,16 @@ export function createRegistryJwtVerifier(opts) {
                 const res = await doFetch(jwksUrl, { redirect: "error", signal: AbortSignal.timeout(10_000) });
                 if (!res.ok)
                     throw new Error(`jwks HTTP ${res.status}`);
-                // 先看 Content-Length 早拒;chunked/无 CL 的响应会整体读入后按字节拒(非流式截断——jwksUrl 是
-                // operator 钉死的可信 registry + redirect:"error" + 10s timeout,瞬时内存风险接受,诚实记档)。
                 const cl = Number(res.headers.get("content-length"));
                 if (Number.isFinite(cl) && cl > MAX_JWKS_BYTES)
                     throw new Error("jwks content-length too large");
                 const buf = Buffer.from(await res.arrayBuffer());
                 if (buf.byteLength > MAX_JWKS_BYTES)
                     throw new Error("jwks body too large");
-                const doc = RegistryJwks.parse(JSON.parse(buf.toString("utf8"))); // zod:形状不对=拉取失败(R8 路),绝不采用半坏文档
+                const doc = RegistryJwks.parse(JSON.parse(buf.toString("utf8")));
                 const next = new Map();
                 for (const k of doc.keys) {
                     try {
-                        // 公钥成员 only(契约警告:即便 registry 出 bug 带了私有成员也绝不使用/回显)。
                         next.set(k.kid, createPublicKey({ key: { kty: "RSA", n: k.n, e: k.e }, format: "jwk" }));
                     }
                     catch {
@@ -91,7 +66,6 @@ export function createRegistryJwtVerifier(opts) {
                 lastFetchSuccessMs = now();
             }
             catch (e) {
-                // 失败=保留旧缓存(R8 离线宽限判定在 verify 侧);只记账不 throw。
                 opts.logger?.warn?.("auth_bridge_jwks_fetch_failed", { iss: issuer, error: String(e).slice(0, 200) });
             }
             finally {
@@ -101,8 +75,6 @@ export function createRegistryJwtVerifier(opts) {
         return inflight;
     }
     async function verify(bearer) {
-        // 延迟观测(auth_bridge_verify_seconds):热路径(kid 命中)应为亚毫秒级;冷路径(JWKS 拉取)带一次
-        // 网络 RTT——首请求/轮换时的尾延迟在这根直方图上可见,不用猜。
         const t0 = now();
         try {
             return await verifyInner(bearer);
@@ -115,57 +87,43 @@ export function createRegistryJwtVerifier(opts) {
         if (bearer.length > MAX_TOKEN_CHARS)
             return fail("malformed");
         const parts = bearer.split(".");
-        // 三段非空 + 每段 base64url 字符集(b64urlJson 已校验 header/payload;签名段在此单独校验)。
         if (parts.length !== 3 || parts.some((p) => p.length === 0) || !B64URL_RE.test(parts[2]))
             return fail("malformed");
         const header = b64urlJson(parts[0]);
         const payload = b64urlJson(parts[1]);
         if (!header || !payload)
             return fail("malformed");
-        // R1 — alg 固定在调用侧:只接受 RS256,不读 token 的 alg 字段来决定验法(none/HS*/ES*/PS* 一律拒)。
-        // 错误码归类跟契约(AUTH_BRIDGE_ERROR_CODES 注释):disallowed alg / 缺 kid = `malformed`
-        // (invalid_signature 留给"键在、验签不过"——异源复审对齐,跨侧 metrics 口径一致)。
         if (header.alg !== AUTH_BRIDGE_ALGS[0])
             return fail("malformed");
         const kid = typeof header.kid === "string" ? header.kid : undefined;
         if (!kid)
             return fail("malformed");
-        // R4 — issuer 先于取键比较(iss 不对根本不必碰 JWKS)。
         const iss = typeof payload.iss === "string" ? stripSlash(payload.iss) : undefined;
         if (iss !== issuer)
             return fail("unknown_issuer", kid);
-        // R5 — 时间窗(60s 偏移;exp 必须在)。
         if (classifyTimeClaims(payload, Math.floor(now() / 1000), clockSkewSec) !== "ok")
             return fail("expired", kid);
-        // R2/R3 — 取键。热路径:kid 命中 ⇒ 直用,零 fetch(TTL 陈旧只在无在途拉取且过节流时【后台】刷一次
-        // [void,不 await],不阻塞验证)。kid miss ⇒ 先 await 任何在途拉取(并发请求不应被 lastFetchAttemptMs
-        // 节流跳过而错过正在完成的刷新),再查;仍 miss 且过节流 ⇒ 强制刷一次。
         const snapshot = () => ({ cachedKids: [...keys.keys()], lastFetchAttemptMs, nowMs: now() });
         if (keys.has(kid)) {
             const ttlStale = lastFetchSuccessMs === undefined || now() - lastFetchSuccessMs > jwksTtlSec * 1000;
             if (ttlStale && !inflight && (lastFetchAttemptMs === undefined || now() - lastFetchAttemptMs >= refreshMin * 1000)) {
-                void refreshJwks(); // 后台刷新,当前请求继续用现有 key
+                void refreshJwks();
             }
         }
         else {
             if (inflight)
-                await inflight; // 有在途拉取:等它完成再查(可能正好带来这个 kid)
+                await inflight;
             if (!keys.has(kid) && shouldForceJwksRefresh(kid, snapshot(), { jwksRefreshMinIntervalSec: refreshMin }))
                 await refreshJwks();
         }
         const key = keys.get(kid);
         if (!key) {
-            // R8 — kid 仍未命中:有【活】缓存(有成功拉取且在 24h 宽限内)⇒ 键该在却不在=token 与当前键集不符
-            // (invalid_signature)。从没成功拉过 / 超宽限 ⇒ jwks_unavailable(失败即拒:不用 `keys.size>0` 兜底,
-            // 因为超宽限的陈旧缓存 size>0 时也不应把 unavailable 归成 invalid_signature)。
             const graceOk = lastFetchSuccessMs !== undefined && jwksWithinOfflineGrace({ lastFetchSuccessMs, nowMs: now() }, { offlineGraceSec });
             return graceOk ? fail("invalid_signature", kid) : fail("jwks_unavailable", kid);
         }
         if (lastFetchSuccessMs !== undefined && !jwksWithinOfflineGrace({ lastFetchSuccessMs, nowMs: now() }, { offlineGraceSec })) {
-            // 缓存超出 24h 离线宽限——即便 kid 命中也拒(R8:宽限后不再使用陈旧键)。
             return fail("jwks_unavailable", kid);
         }
-        // 真验签(RS256 = RSASSA-PKCS1-v1_5 + SHA-256 over `header.payload`)。
         let sigOk = false;
         try {
             sigOk = cryptoVerify("RSA-SHA256", Buffer.from(`${parts[0]}.${parts[1]}`, "utf8"), key, Buffer.from(parts[2], "base64url"));
@@ -175,7 +133,6 @@ export function createRegistryJwtVerifier(opts) {
         }
         if (!sigOk)
             return fail("invalid_signature", kid);
-        // R6/R7/R9 — 身份映射(契约纯函数)。
         const mapped = toVerifiedIdentity(payload, opts.audience ? { audience: opts.audience } : undefined);
         if (!mapped.ok)
             return fail(mapped.error, kid);

package/dist/auth-keys.js

@@ -1,15 +1,3 @@
-/**
- * AUTH KEY-SET parsing (design/158 A4) — the env→key-set decoders for the two D-G credential planes, moved VERBATIM
- * out of security.ts: {@link parseApprovalHmacKeys} (APPROVAL_HMAC_KEYS — the rotating HMAC secret set, decision
- * INTEGRITY) and {@link parsePrincipalJwks} (PRINCIPAL_JWT_PUBKEYS — the rotating issuer public-key set, principal
- * IDENTITY). config.ts consumes ONLY these two functions + their row types at env-load time, and importing them from
- * security.ts made the base config layer value-depend on the whole 55KiB auth module (lens2 §F). This file is a pure
- * leaf (JSON.parse + shape filters, zero repo imports); the VERIFIERS that consume the parsed key-sets
- * (verifyApprovalHmac / verifyPrincipalJwt) stay in ./approval-hmac.ts and ./principal-jwt.ts; consumers import these four names from HERE ([2354] 兼容面全清).
- */
-/** Parse APPROVAL_HMAC_KEYS — a sema-registry-managed, rotating key-SET, as a JSON array of {kid,key,status}.
- *  Empty / unset / unparseable ⇒ `[]` ⇒ HMAC verification is OFF (D-G inactive; back-compat, BFF-only door).
- *  fail-closed 语义与改前**逐字相同**;新增的只有 `onReject`(#210:每一条被丢弃的条目都要说出来)。 */
 export function parseApprovalHmacKeys(raw, onReject) {
     if (!raw)
         return [];
@@ -18,9 +6,6 @@ export function parseApprovalHmacKeys(raw, onReject) {
         v = JSON.parse(raw);
     }
     catch {
-        // ⚠️ 解析器自带的 message **不能**转述:V8 的 `JSON.parse` 报错里嵌了输入片段
-        // (`Unexpected token 'T', "TOP_SECRET"... is not valid JSON`),而这条 env 的内容就是对称密钥 ——
-        // 把它写进 boot 日志等于把密钥前缀印出来。只说「不是合法 JSON」,定位靠 env 名本身。
         onReject({ index: "-", reason: "not valid JSON (value withheld: this env holds secrets)" });
         return [];
     }
@@ -43,10 +28,6 @@ export function parseApprovalHmacKeys(raw, onReject) {
     });
     return out;
 }
-/** Parse PRINCIPAL_JWT_PUBKEYS — a JSON array of {kid,alg,key,status}. Empty/unset/malformed ⇒ [] ⇒ no trust
- *  anchor ⇒ the direct door cannot open (D-G inactive). Each entry must have kid + a pinned alg + a PEM key.
- *  #210: fail-closed 语义逐字不变,但每条被丢弃的条目经 `onReject` 报出(序号 + 缺陷字段名,不带值)——
- *  这里的 key 是**公**钥,但 reason 仍只说字段名,与 HMAC 那条同形(两个出口的口径不该分岔)。 */
 export function parsePrincipalJwks(raw, onReject) {
     if (!raw)
         return [];
@@ -56,8 +37,6 @@ export function parsePrincipalJwks(raw, onReject) {
         v = JSON.parse(raw);
     }
     catch {
-        // 同 parseApprovalHmacKeys:不转述 V8 的 message(它嵌输入片段)。这一口装的是**公**钥,但两个出口
-        // 的口径不该分岔 —— 一个「视情况才脱敏」的规矩,迟早会在错的那一侧被抄走。
         onReject({ index: "-", reason: "not valid JSON (value withheld)" });
         return [];
     }
@@ -73,8 +52,6 @@ export function parsePrincipalJwks(raw, onReject) {
             return;
         }
         const bad = ["kid", "key"].filter((f) => typeof e[f] !== "string");
-        // alg 单列:缺席与「不在闭集」是两种手滑,但都必须点名 `alg` —— 运维看到字段名才知道去改哪一格
-        // (alg-confusion 防线就挂在这条钉上,静默滤掉等于防线自己消失了没人知道)。
         if (typeof e.alg !== "string")
             bad.push("alg");
         else if (!ALGS.has(e.alg))

package/dist/bake-runner/main.js

@@ -1,12 +1,3 @@
-/**
- * bake-runner ENTRYPOINT (IMAGE-API-DESIGN.md §P2.0/§P2.12) — the privileged build-host daemon. It wires the REAL I/O
- * (HTTP to image-api, the setsid-detached build.sh child, the fs manifest read, git checkout, df) into the
- * I/O-injected `BakeRunner` core (./runner.ts). This process runs ONLY on the build-host build host — it CANNOT be
- * unit-run here (no docker/ctr/recipes); the testable logic is the pure protocol + the runner orchestration.
- *
- * Crown-jewel discipline (§P2.4e): the only secrets are BAKE_RUNNER_TOKEN (the operator-principal bearer for
- * claim/heartbeat) and the per-bake ingest secret minted by image-api at claim — neither is ever logged.
- */
 import { spawn, exec as execCb } from "node:child_process";
 import { readFile } from "node:fs/promises";
 import { promisify } from "node:util";
@@ -15,12 +6,6 @@ import { parseNumOrFailNonNegative } from "../config.js";
 import { shellQuote as shellSafe } from "../plugins/remote-shell.js";
 import { BakeRunner, } from "./runner.js";
 const exec = promisify(execCb);
-// 鲁棒性批5 A3(2026-08-05):claim/ingest/heartbeat 三个 fetch 此前零超时——bake-runner 的整条 loop()
-// 是这台构建宿主机唯一的主循环,一次悬挂的 image-api 连接(网络分区/黑洞 TCP)会让 claim/heartbeat 永久
-// 挂起,直到底层 socket 超时(可能几十分钟),期间既不上报心跳也不能认领新 bake——整机静默停摆。
-// 上界两档:claim/ingest 不在心跳热路径,给 30s 吃满慢网 RTT + 大 body;heartbeat 必须显著小于
-// BAKE_HEARTBEAT_MS 的默认量级(30s)——否则一次超时本身就吃掉一整个心跳周期,取 10s(同
-// fleet-client.ts `FLEET_CLIENT_FETCH_TIMEOUT_MS` 判据的普适形)。
 const BAKE_CLAIM_INGEST_FETCH_TIMEOUT_MS = 30_000;
 const BAKE_HEARTBEAT_FETCH_TIMEOUT_MS = 10_000;
 function loadEnv() {
@@ -38,26 +23,14 @@ function loadEnv() {
         recipeDir: process.env.RECIPE_DIR || "/opt/recipes",
         buildShPath: process.env.BUILD_SH_PATH || "e2b-template/dev-sandbox/build.sh",
         dataDir: process.env.BAKE_DATA_DIR || "/data",
-        // A2/E5 (gap-sweep 2026-08-01): these were bare `Number(process.env.X || default)` — a unit-suffixed or
-        // typo'd value (`"30s"`) silently became NaN, and NaN survives every downstream `??`/`?? default` guard
-        // (those only catch null/undefined). The fallout is a SILENT-LOOSENING pair: `clock.sleep(NaN)` resolves
-        // ~immediately (`setTimeout(fn, NaN)` behaves like a 0ms timer) turning the lease heartbeat into a tight
-        // POST loop against image-api, and `freeGb < NaN` is always false so the pre-flight disk guard silently
-        // never fires. `parseNumOrFailNonNegative` (config.ts, shared with leader/wire.ts's four resource knobs)
-        // fails loud at bake-runner startup instead — non-numeric OR negative both throw; unset/empty still falls
-        // back to the documented default (zero behavior change on the happy path).
         heartbeatMs: parseNumOrFailNonNegative("BAKE_HEARTBEAT_MS", process.env.BAKE_HEARTBEAT_MS || "30000"),
         idlePollMs: parseNumOrFailNonNegative("BAKE_IDLE_POLL_MS", process.env.BAKE_IDLE_POLL_MS || "5000"),
         minFreeGb: parseNumOrFailNonNegative("IMAGE_BAKE_MIN_FREE_GB", process.env.IMAGE_BAKE_MIN_FREE_GB || "20"),
     };
 }
-/** The real image-api HTTP client. Authenticates claim/heartbeat with the runner bearer; ingest additionally
- *  carries the per-bake ingest secret header (so image-api can reject a stale/rogue runner — §P2.4e). */
 function makeApiClient(env, log) {
     const auth = { authorization: `Bearer ${env.token}`, "content-type": "application/json" };
     return {
-        // Long-poll claim (§P2.12): the bare `POST …/bakes/claim` finds the oldest queued bake AND leases it in one
-        // call (the discovery + the single-flight CAS server-side). 204 ⇒ the queue is empty (the runner idle-polls).
         async claimNext() {
             const res = await fetch(`${env.imageApiBase}/v1/images/bakes/claim`, {
                 method: "POST",
@@ -66,23 +39,13 @@ function makeApiClient(env, log) {
                 signal: AbortSignal.timeout(BAKE_CLAIM_INGEST_FETCH_TIMEOUT_MS),
             });
             if (res.status === 204)
-                return null; // empty queue — the routine "nothing to do" case, no log line
-            // C6/C1 (2026-08-01): 401 (bad runner credential) / 409 (lost the single-flight CAS to another runner
-            // replica) / 5xx previously fell into this SAME silent-`null` branch as an empty queue — a misconfigured
-            // BAKE_RUNNER_TOKEN and a healthy idle runner were indistinguishable from the outside (both just idle-poll
-            // forever with zero log lines). `bake_claim_error` (loop()'s catch) only fires on a THROWN error — a non-ok
-            // HTTP response never throws — so this warn is the only trace a non-2xx claim response leaves anywhere.
+                return null;
             if (!res.ok) {
                 log.warn("bake_claim_rejected", { status: res.status });
                 return null;
             }
             const c = (await res.json());
             if (!c.bakeId || !Array.isArray(c.argv) || !c.ingestSecret) {
-                // A malformed 2xx body is worse than a rejection: image-api's claim call ATOMICALLY leases the bake
-                // server-side before returning it, so a shape we refuse to trust here is a bake already checked OUT
-                // from the queue that we are about to drop on the floor. We still can't safely act on an untrusted
-                // shape (no bakeId ⇒ no way to release/fail it), so this warn is the only surfacing point until
-                // image-api's stale-lease reaper reclaims it (§P2.7) — see runner.ts module doc for the reaper backstop.
                 log.warn("bake_claim_malformed", { status: res.status, bakeId: typeof c.bakeId === "string" ? c.bakeId : undefined });
                 return null;
             }
@@ -108,11 +71,10 @@ function makeApiClient(env, log) {
             return {
                 accepted: res.ok && body.accepted !== false,
                 cancelRequested: body.cancelRequested === true,
-                leaseValid: res.status !== 409, // a 409 on ingest = the lease/claim no longer ours
+                leaseValid: res.status !== 409,
             };
         },
         async heartbeat(bakeId, ingestSecret) {
-            // A heartbeat is a no-frame ingest: image-api advances the lease and echoes the cancel flag (§P2.7/§P2.11).
             const res = await fetch(`${env.imageApiBase}/v1/images/bakes/${encodeURIComponent(bakeId)}/ingest`, {
                 method: "POST",
                 headers: { ...auth, "x-bake-ingest-secret": ingestSecret },
@@ -128,13 +90,9 @@ function makeApiClient(env, log) {
         },
     };
 }
-/** The real child spawner: `setsid`-style detached process GROUP so a cancel/deadline kill signals the whole tree
- *  (channel-close / a plain kill of the immediate child does NOT stop a detached build — §P2.11). */
 function makeSpawner() {
     return {
         spawn(opts) {
-            // detached:true → the child becomes a process-group leader (its pgid == its pid); `process.kill(-pid, sig)`
-            // then signals the WHOLE group. We DON'T `unref()` — the runner waits on the exit promise.
             const child = spawn(opts.argv[0], opts.argv.slice(1), {
                 cwd: opts.cwd,
                 detached: true,
@@ -146,13 +104,12 @@ function makeSpawner() {
             bufferLines(child.stderr, opts.onStderrLine);
             const exited = new Promise((resolve) => {
                 child.on("exit", (code, signal) => resolve({ code, signal }));
-                child.on("error", () => resolve({ code: 127, signal: null })); // spawn failed (build.sh missing, etc.)
+                child.on("error", () => resolve({ code: 127, signal: null }));
             });
             const handle = {
                 pgid,
                 exited,
                 killGroup(signal) {
-                    // Negative pid → signal the process GROUP (the detached tree), not just the immediate child.
                     if (pgid > 0)
                         process.kill(-pgid, signal);
                 },
@@ -161,8 +118,6 @@ function makeSpawner() {
         },
     };
 }
-/** Split a readable stream into lines, invoking `onLine` per complete line (the runner parses ONLY stdout as JSON;
- *  stderr lines are the failure tail). Carries a partial trailing line across chunks; flushes it on stream end. */
 function bufferLines(stream, onLine) {
     if (!stream)
         return;
@@ -182,7 +137,6 @@ function bufferLines(stream, onLine) {
             onLine(buf);
     });
 }
-/** The real host ops: fs manifest read, df /data, recipe checkout, and the thin docker-push big-blob retry. */
 function makeHostOps(env) {
     return {
         async readManifest(path) {
@@ -193,14 +147,6 @@ function makeHostOps(env) {
             return stdout;
         },
         async checkoutRecipe(ref) {
-            // The recipe dir is a git checkout of the service repo pinned to the runner's deployed commit (NOT a frozen
-            // copy) so build.sh's `git rev-parse` gitsha is REAL and the manifest's recipeGitSha is replay-sufficient.
-            // A fixed ref (the deployed image's commit) → fetch + checkout is idempotent; a non-default ref is fetched.
-            // 🔴 A ref may be a branch/tag (fetchable by name) OR a BARE COMMIT SHA — and `git fetch origin <sha>` fails
-            // on most servers ("couldn't find remote ref <sha>"; only refs are fetchable). So try the cheap shallow
-            // ref-fetch, and on failure fall back to fetching the repo and checking the SHA out of the local history
-            // (the init-container clone usually already contains it). RECIPE_REF=HEAD skips this entirely (uses the
-            // checkout as-is — the prod path, the init-container pins the commit). [live-caught on center's prod deploy]
             if (ref && ref !== "HEAD") {
                 const dir = shellSafe(env.recipeDir);
                 try {
@@ -211,14 +157,9 @@ function makeHostOps(env) {
                     await exec(`git -C ${dir} fetch origin && git -C ${dir} checkout --quiet --detach ${shellSafe(ref)}`);
                 }
             }
-            // build.sh resolves itself relative to its own dir; the cwd for the spawn is the recipe checkout root so the
-            // path RECIPE_DIR + BUILD_SH_PATH is the script the runner invokes.
             return env.recipeDir;
         },
         async dockerPushRetry(tag, attempts) {
-            // Thin `docker push` wrapper (NOT build.sh --replay — that re-bakes + hits the dup-check, exit 10). Retries a
-            // flaky big-blob registry layer push with backoff (born on SWR — deprecated; pool now docker.io/claybobby);
-            // NO_PROXY (incl. the registry domain) lives in this process's env.
             for (let i = 0; i < attempts; i++) {
                 try {
                     await exec(`docker push ${shellSafe(tag)}`);
@@ -251,7 +192,7 @@ async function main() {
         recipeRef: env.recipeRef,
         heartbeatMs: env.heartbeatMs,
         minFreeGb: env.minFreeGb,
-    }); // NB: the token + per-bake ingest secret are NEVER logged (§P2.4e)
+    });
     const runner = new BakeRunner({
         api: makeApiClient(env, log),
         spawner: makeSpawner(),
@@ -272,11 +213,9 @@ async function main() {
     process.on("SIGINT", () => shutdown("SIGINT"));
     await runner.loop();
 }
-// Only run when invoked directly (not when imported by a test).
 const invokedDirectly = process.argv[1] !== undefined && /bake-runner[/\\]main\.(ts|js)$/.test(process.argv[1]);
 if (invokedDirectly) {
     main().catch((err) => {
-        // eslint-disable-next-line no-console
         console.error(JSON.stringify({ ts: new Date().toISOString(), level: "error", msg: "bake_runner_fatal", err: String(err) }));
         process.exit(1);
     });

package/dist/bake-runner/protocol.js

@@ -1,24 +1,7 @@
-/**
- * bake-runner PURE protocol layer (IMAGE-API-DESIGN.md §P2.12) — the line→frame mapping + the small policy
- * helpers, factored free of I/O so they are unit-testable WITHOUT the privileged build-host build host (the runner
- * itself can only be exercised live; this is the part a unit test pins).
- *
- * The runner spawns `build.sh <vetted argv> --json` and forwards each STDOUT line to image-api's ingest. build.sh
- * emits a small set of JSON object lines (`resolved | state | step | image | manifest | done`) on stdout and tees
- * the raw `docker build` output to `$BUILD_DIR/build.log` (NOT onto stdout). On failure it does `tail -40 build.log
- * >&2` — that is STDERR, the failure tail, NOT JSON; we parse JSON ONLY from stdout (a naive JSON.parse over both
- * crashes the parser — §P2.5). Each forwarded frame carries an incrementing `lineOrd` (at-least-once ingest dedupe;
- * image-api's `uq_line` ignores a re-sent ordinal — §P2.10).
- */
-/**
- * Parse ONE raw stdout line into a build.sh event, or null when it is not a JSON object line (a blank line, a
- * stray non-JSON print). build.sh's protocol is strictly one JSON OBJECT per stdout line (`jq -nc`), so anything
- * that is not a `{…}` object is treated as non-protocol noise the caller forwards as a `log` frame (NOT crashed on).
- */
 export function parseBuildShLine(raw) {
     const s = raw.trim();
     if (s.length === 0 || s[0] !== "{")
-        return null; // fast reject: protocol lines are JSON objects
+        return null;
     let parsed;
     try {
         parsed = JSON.parse(s);
@@ -30,49 +13,26 @@ export function parseBuildShLine(raw) {
         return null;
     const obj = parsed;
     if (typeof obj.event !== "string")
-        return null; // not a protocol line → caller forwards as a log frame
+        return null;
     return obj;
 }
-/**
- * Map ONE stdout line → the ingest frame the runner POSTs (the PURE core a unit test pins). A parseable protocol
- * line is forwarded under its own `event`; an unparseable stdout line becomes an `info` log frame (build.sh's
- * structured stdout is naturally quiet, so this is rare — usually a generator print). The raw `docker build` tail
- * never reaches here: it is on stderr (the runner only feeds stdout through this) — §P2.5.
- */
 export function lineToFrame(raw, lineOrd) {
     const ev = parseBuildShLine(raw);
     if (ev === null) {
-        // Non-protocol stdout noise → an info log frame (NOT crashed on, NOT a raw docker tail — that is stderr).
         return { event: "log", lineOrd, level: "info", line: raw.replace(/\s+$/, "") };
     }
     const { event, ...rest } = ev;
     return { event, lineOrd, ...rest };
 }
-/**
- * Synthesize the `docker-build status:running elapsedSec` heartbeat step (§P2.2) — emitted every ~30s during the
- * long, silent `docker build` (with logs off) so a resuming reader sees forward motion instead of a dead spinner.
- * It is a synthesized frame, so it still carries a `lineOrd` (image-api dedupes the same way).
- */
 export function dockerBuildTickFrame(lineOrd, elapsedSec) {
     return { event: "step", lineOrd, step: "docker-build", status: "running", elapsedSec };
 }
-/**
- * Synthesize the terminal `done` the runner sends when build.sh did NOT emit one (a hard cancel/timeout kill —
- * build.sh has no SIGTERM trap, so a killed process never prints `done:CANCELLED`/`done:FAILED`; the runner MUST
- * synthesize it — §P2.11). `cancelled` → `CANCELLED`; a timeout → `FAILED exitCode:124`.
- */
 export function synthDoneFrame(lineOrd, kind, detail) {
     if (kind === "cancelled") {
         return { event: "done", lineOrd, status: "CANCELLED", exitCode: null, error: detail?.error ?? "cancelled by operator" };
     }
     return { event: "done", lineOrd, status: "FAILED", exitCode: 124, error: detail?.error ?? "bake hard-deadline exceeded (killed)" };
 }
-/**
- * The runner-side terminal `done` for a build.sh CHILD that exited non-zero WITHOUT printing its own `done` (build.sh
- * normally dies via `die()` which DOES print a `done:FAILED`, but a SIGKILL or a crash before the trap can leave the
- * child exiting non-zero silently). The runner backstops with a FAILED done carrying the child exit code + the
- * captured stderr failure tail (the `tail -40 build.log` build.sh prints on failure), redacted by image-api on store.
- */
 export function exitDoneFrame(lineOrd, exitCode, stderrTail) {
     const tail = stderrTail.trim();
     return {
@@ -83,16 +43,10 @@ export function exitDoneFrame(lineOrd, exitCode, stderrTail) {
         error: tail.length > 0 ? `build.sh exited ${exitCode}: ${lastLines(tail, 12)}` : `build.sh exited ${exitCode}`,
     };
 }
-/** Keep only the last `n` lines of a (possibly long) stderr tail — bounds the error string we forward. */
 export function lastLines(text, n) {
     const lines = text.split(/\r?\n/).filter((l) => l.length > 0);
     return lines.slice(Math.max(0, lines.length - n)).join("\n");
 }
-/**
- * The profile-aware HARD DEADLINE (§P2.7/§P2.11) the runner enforces by killing the process group. flutter/full are
- * the heavy profiles (~60min); everything else ~45min. A bands build ("custom") is treated as heavy if it includes
- * a heavy band. The reaper backstops this; the runner is the primary enforcer (it owns the child).
- */
 export function deadlineMsForProfile(profile, bands) {
     const HEAVY_MS = 60 * 60 * 1000;
     const NORMAL_MS = 45 * 60 * 1000;
@@ -104,25 +58,19 @@ export function deadlineMsForProfile(profile, bands) {
         return HEAVY_MS;
     return NORMAL_MS;
 }
-/** Parse `df -P -BG /data` (POSIX, 1G blocks) → free GiB on the build-host data fs. Returns null if unparseable
- *  (the caller then fails OPEN — a df parse miss must not block a bake; the reaper still guards a mid-build fill). */
 export function parseDfFreeGb(dfOutput) {
-    // `df -P -BG <path>` prints a header line then one data line; the "Available" column is field index 3 (0-based),
-    // a value like "812G". POSIX `-P` guarantees one physical line per fs (no wrapping), so field positions are fixed.
     const lines = dfOutput.trim().split(/\r?\n/);
     if (lines.length < 2)
         return null;
     const data = lines[lines.length - 1].trim().split(/\s+/);
     if (data.length < 4)
         return null;
-    const avail = data[3]; // Filesystem 1G-blocks Used Available …
+    const avail = data[3];
     const m = /^(\d+)G?$/.exec(avail);
     if (!m)
         return null;
     return Number(m[1]);
 }
-/** The path build.sh's `done`/`manifest` line points at (a build-host FS path). The done carries `manifest:<path>`, the
- *  manifest event carries `path` — the runner reads whichever is present off disk for the auto-register body. */
 export function manifestPathFromLine(doneLine, lastManifestPath) {
     if (typeof doneLine.manifest === "string" && doneLine.manifest.length > 0)
         return doneLine.manifest;
@@ -130,9 +78,6 @@ export function manifestPathFromLine(doneLine, lastManifestPath) {
         return doneLine.path;
     return lastManifestPath;
 }
-/** Pull the post-push runtime digest the auto-register should key on. build.sh rewrites DIGEST from RepoDigests[0]
- *  AFTER a push, so the `done`/`image` line's `digest` is already the post-push registry RepoDigest on a push bake and the
- *  LOCAL_ID on a no-push bake — the runner forwards it verbatim; this just normalizes the field name (§P2.10). */
 export function digestFromDoneLine(doneLine, lastImageDigest) {
     if (typeof doneLine.digest === "string" && doneLine.digest.length > 0)
         return doneLine.digest;