@sema-agent/server 1.323.0 → 2.0.0

package/dist/auth-bridge.js

@@ -1,10 +1,26 @@
+/**
+ * 鉴权桥 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";
 export { looksLikeJwt } 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))
@@ -18,6 +34,10 @@ 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}`;
@@ -27,12 +47,14 @@ 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;
+    let inflight; // 并发 verify 合并成一次拉取(大量未知 kid 时不重复拉取)
     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 };
     };
@@ -45,16 +67,19 @@ 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")));
+                const doc = RegistryJwks.parse(JSON.parse(buf.toString("utf8"))); // zod:形状不对=拉取失败(R8 路),绝不采用半坏文档
                 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 {
@@ -67,6 +92,7 @@ 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 {
@@ -76,6 +102,8 @@ 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);
@@ -88,43 +116,57 @@ 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();
+                void refreshJwks(); // 后台刷新,当前请求继续用现有 key
             }
         }
         else {
             if (inflight)
-                await inflight;
+                await inflight; // 有在途拉取:等它完成再查(可能正好带来这个 kid)
             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"));
@@ -134,6 +176,7 @@ 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.d.ts

@@ -1,14 +1,33 @@
+/**
+ * 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 security.ts, which re-exports these four names for compat.
+ */
+/** One key in the rotating HMAC key-set. `kid` lets the verifier pick the signing key (or fall back to trying the
+ *  whole set); `status` lets sema-registry rotate without breaking in-flight approvals: `active` = sign + verify,
+ *  `retiring` = verify-only (kept for the overlap window so a MAC signed with the old key still verifies). */
 export interface ApprovalHmacKey {
     kid: string;
     key: string;
     status?: "active" | "retiring";
 }
+/** 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). */
 export declare function parseApprovalHmacKeys(raw: string | undefined): ApprovalHmacKey[];
+/** One issuer public key in the rotating principal JWKS (mirror of the HMAC key-set rotation discipline). The
+ *  `alg` is PINNED per key — the JWT header's alg MUST match it, killing alg-confusion (`none`, HS-with-the-pubkey).
+ *  `key` is a PEM (SPKI) public key. PUBLIC, non-secret. */
 export interface PrincipalJwtKey {
     kid: string;
     alg: "EdDSA" | "RS256" | "ES256";
     key: string;
     status?: "active" | "retiring";
 }
+/** 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. */
 export declare function parsePrincipalJwks(raw: string | undefined): PrincipalJwtKey[];
 //# sourceMappingURL=auth-keys.d.ts.map

package/dist/auth-keys.js

@@ -1,3 +1,14 @@
+/**
+ * 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 security.ts, which re-exports these four names for compat.
+ */
+/** 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). */
 export function parseApprovalHmacKeys(raw) {
     if (!raw)
         return [];
@@ -11,6 +22,8 @@ export function parseApprovalHmacKeys(raw) {
         return [];
     }
 }
+/** 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. */
 export function parsePrincipalJwks(raw) {
     if (!raw)
         return [];

package/dist/bake-runner/main.d.ts

@@ -12,8 +12,13 @@ interface RunnerEnv {
     minFreeGb: number;
 }
 declare function loadEnv(): RunnerEnv;
+/** 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). */
 declare function makeApiClient(env: RunnerEnv): ImageApiClient;
+/** 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). */
 declare function makeSpawner(): ChildSpawner;
+/** The real host ops: fs manifest read, df /data, recipe checkout, and the thin docker-push big-blob retry. */
 declare function makeHostOps(env: RunnerEnv): HostOps;
 declare function main(): Promise<void>;
 export { main, loadEnv, makeApiClient, makeSpawner, makeHostOps };

package/dist/bake-runner/main.js

@@ -1,3 +1,12 @@
+/**
+ * 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";
@@ -24,9 +33,13 @@ function loadEnv() {
         minFreeGb: Number(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) {
     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",
@@ -34,7 +47,7 @@ function makeApiClient(env) {
                 body: JSON.stringify({ runnerId: env.runnerId }),
             });
             if (res.status === 204 || res.status === 409)
-                return null;
+                return null; // empty queue, or lost the single-flight CAS
             if (!res.ok)
                 return null;
             const c = (await res.json());
@@ -61,10 +74,11 @@ function makeApiClient(env) {
             return {
                 accepted: res.ok && body.accepted !== false,
                 cancelRequested: body.cancelRequested === true,
-                leaseValid: res.status !== 409,
+                leaseValid: res.status !== 409, // a 409 on ingest = the lease/claim no longer ours
             };
         },
         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 },
@@ -79,9 +93,13 @@ function makeApiClient(env) {
         },
     };
 }
+/** 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,
@@ -93,12 +111,13 @@ 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 }));
+                child.on("error", () => resolve({ code: 127, signal: null })); // spawn failed (build.sh missing, etc.)
             });
             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);
                 },
@@ -107,6 +126,8 @@ 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;
@@ -126,6 +147,7 @@ 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) {
@@ -136,6 +158,14 @@ 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 {
@@ -146,9 +176,14 @@ 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)}`);
@@ -166,6 +201,8 @@ function makeHostOps(env) {
         },
     };
 }
+/** Shell-quote a single argument for the `exec` string forms above (df/git/docker take server-fixed paths/refs, but
+ *  a defensive quote keeps a surprising RECIPE_DIR/ref from breaking the command — argv to build.sh is a vector). */
 function shellSafe(s) {
     return `'${s.replace(/'/g, "'\\''")}'`;
 }
@@ -184,7 +221,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),
         spawner: makeSpawner(),
@@ -205,9 +242,11 @@ 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.d.ts

@@ -1,3 +1,16 @@
+/**
+ * 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).
+ */
+/** One build.sh stdout line, already JSON-parsed into an object (or a marker for an unparseable line). */
 export type BuildShEvent = {
     event: "resolved";
     [k: string]: unknown;
@@ -29,21 +42,65 @@ export type BuildShEvent = {
     event: string;
     [k: string]: unknown;
 };
+/** The frame the runner POSTs to `…/ingest` (image-api maps it to an event-log row). `lineOrd` is the dedupe key. */
 export interface IngestFrame {
+    /** build.sh's `event` (or "log" for an unparseable/raw line). */
     event: string;
+    /** Monotonic per-bake ordinal — image-api dedupes on (bakeId, lineOrd) so an at-least-once re-send is a no-op. */
     lineOrd: number;
+    /** The remaining build.sh fields (event already lifted out), passed through verbatim. */
     [k: string]: unknown;
 }
+/**
+ * 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 declare function parseBuildShLine(raw: string): BuildShEvent | null;
+/**
+ * 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 declare function lineToFrame(raw: string, lineOrd: number): IngestFrame;
+/**
+ * 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 declare function dockerBuildTickFrame(lineOrd: number, elapsedSec: number): IngestFrame;
+/**
+ * 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 declare function synthDoneFrame(lineOrd: number, kind: "cancelled" | "timeout", detail?: {
     error?: string;
 }): IngestFrame;
+/**
+ * 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 declare function exitDoneFrame(lineOrd: number, exitCode: number, stderrTail: string): IngestFrame;
+/** Keep only the last `n` lines of a (possibly long) stderr tail — bounds the error string we forward. */
 export declare function lastLines(text: string, n: number): string;
+/**
+ * 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 declare function deadlineMsForProfile(profile: string, bands: string[] | null | undefined): number;
+/** 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 declare function parseDfFreeGb(dfOutput: string): number | null;
+/** 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 declare function manifestPathFromLine(doneLine: Record<string, unknown>, lastManifestPath: string | null): string | null;
+/** 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 declare function digestFromDoneLine(doneLine: Record<string, unknown>, lastImageDigest: string | null): string | null;
 //# sourceMappingURL=protocol.d.ts.map

package/dist/bake-runner/protocol.js

@@ -1,7 +1,24 @@
+/**
+ * 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;
+        return null; // fast reject: protocol lines are JSON objects
     let parsed;
     try {
         parsed = JSON.parse(s);
@@ -13,26 +30,49 @@ export function parseBuildShLine(raw) {
         return null;
     const obj = parsed;
     if (typeof obj.event !== "string")
-        return null;
+        return null; // not a protocol line → caller forwards as a log frame
     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 {
@@ -43,10 +83,16 @@ 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;
@@ -58,19 +104,25 @@ 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];
+    const avail = data[3]; // Filesystem 1G-blocks Used Available …
     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;
@@ -78,6 +130,9 @@ 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;