@sema-agent/server 1.322.0 → 2.0.0

package/dist/http/routes/images.d.ts

@@ -1,13 +1,30 @@
+/**
+ * design/158 A9 域模块 —— sandbox-image-pool 控制面(IMAGE-API-DESIGN.md)。
+ *
+ * 路由:P2 bake 作业面 `/v1/images/bakes*`(提交/列表/详情/事件 SSE/取消/claim/ingest)与 P1 镜像索引
+ * `/v1/images*`(digests/profile/select)。**bakes 段必须排在 images 段之前**——P1 的单段 profile 正则会把
+ * `bakes` 当成 profile 吞掉(注释原文见路由体内),两段的先后由本文件内部顺序保住。
+ *
+ * 单域独占状态:`bakeSubmitLimiter`(per-principal 提交限速),按 server 实例存活于 `ctx.local.images`。
+ * 本域另收编了原先散在 `server.ts` 模块级的镜像面私产:路由正则、bake 视图投影、claim 应答、ingest 行摄取、
+ * bake SSE 包装、以及两个导出的状态/错误码映射(`server.ts` 保留 re-export,导出面不变)。
+ */
 import type { IncomingMessage, ServerResponse } from "node:http";
 import { RateLimiter } from "../../observability/rate-limit.js";
 import type { BakeState, BakeErrorCode } from "../../plugins/store-contracts.js";
 import type { FlatServiceDeps } from "../server.js";
 import type { RouteCtx } from "../route-ctx.js";
+/** 单域独占状态(lens1 §C2 的 12 条之一)。每个 server 实例一份——模块级会把限速状态跨实例串味
+ *  (一个进程里建几十个 server 的测试会互相污染)。 */
 export interface ImagesLocal {
     bakeSubmitLimiter: RateLimiter;
 }
 export declare function createImagesLocal(deps: FlatServiceDeps): ImagesLocal;
+/** build.sh's 8-value `state` → the COARSE 4-value lifecycle the SSE reader polls for terminality (§P2.3). Every
+ *  NON-terminal state maps to `running` (a PUSHING/VERIFYING state must NOT truncate the stream before `done`). */
 export declare function coarseStatusForState(state: BakeState): "running" | "done" | "failed";
+/** build.sh's structured exit code → the center band-composer UI's terminal `errorCode` (§P2.14 #2). null for an
+ *  uncategorized failure (then `error` free-text + `exitCode` drive the UI). 10=dup-tag, 124=timeout, 507=disk. */
 export declare function errorCodeForExit(exitCode: number | null | undefined, cancelled: boolean): BakeErrorCode;
 export declare const IMAGE_DIGEST_RE: RegExp;
 export declare const IMAGE_PROFILE_RE: RegExp;

package/dist/http/routes/images.js

@@ -8,8 +8,14 @@ import { sendJson, sendError } from "../send.js";
 import { headerStr, safeEqual, gatedPrincipal, explicitOperatorOk, explicitOperator } from "../principal-gate.js";
 import { scopedIdempotencyKey } from "../idempotency.js";
 export function createImagesLocal(deps) {
+    // Per-principal bake-submission rate guard (IMAGE-API-DESIGN.md §P2.4c — fills the register DoS gap the images
+    // block never guarded). Separate from the global rateLimiter (which may be off): an unbounded POST /bakes flood
+    // is real resource-exhaustion churn even though the single-flight lease caps concurrent BUILDS at 1. Off when
+    // submitRateMax<=0. Swept lazily by `check`'s window roll-over (no timer needed for a small operator set).
     return { bakeSubmitLimiter: new RateLimiter(deps.config.imageBakes?.submitRateMax ?? 0, (deps.config.imageBakes?.submitRateWindowSec ?? 60) * 1000) };
 }
+/** build.sh's 8-value `state` → the COARSE 4-value lifecycle the SSE reader polls for terminality (§P2.3). Every
+ *  NON-terminal state maps to `running` (a PUSHING/VERIFYING state must NOT truncate the stream before `done`). */
 export function coarseStatusForState(state) {
     if (state === "COMPLETE")
         return "done";
@@ -17,26 +23,40 @@ export function coarseStatusForState(state) {
         return "failed";
     return "running";
 }
+/** build.sh's structured exit code → the center band-composer UI's terminal `errorCode` (§P2.14 #2). null for an
+ *  uncategorized failure (then `error` free-text + `exitCode` drive the UI). 10=dup-tag, 124=timeout, 507=disk. */
 export function errorCodeForExit(exitCode, cancelled) {
     if (cancelled)
         return "cancelled";
     switch (exitCode) {
         case 9:
-            return "band-conflict";
+            return "band-conflict"; // build.sh's generate-time inter-band collision (gen-dockerfile exit 6/7/8 → 9).
         case 10:
             return "duplicate";
         case 124:
             return "timeout";
         case 507:
-            return "disk";
+            return "disk"; // belt: the runner's pre-flight disk guard (runner.ts) exits 507 — categorize it even if the
+        // structured line.errorCode were ever absent (M1: line.errorCode is the primary source).
         default:
             return null;
     }
 }
+/** The closed set of structured terminal `errorCode`s a runner/build.sh frame may carry (§P2.14 #2). A
+ *  runner-supplied code is a UI hint only, but it CANNOT reconstruct from the exit code alone (e.g. the disk
+ *  guard's 507, or a future band-conflict 6/7/8), so ingestBakeLine PREFERS a validated `line.errorCode` over
+ *  the exit-code recompute. Set-membership keeps it inside the BakeErrorCode union (never trust a free-text). */
 const RUNNER_ERROR_CODES = new Set(["band-conflict", "duplicate", "disk", "timeout", "cancelled"]);
+/** The index `profile` under which the FROM base (`sandbox-base`) is published — the ONLY profile a bake's
+ *  `--base-ref` may resolve to (a published code-* profile digest is a built layer, never a valid FROM base).
+ *  Both the caller-supplied-baseRef allow-list AND the default-base fallback resolve against this profile. */
 const SANDBOX_BASE_PROFILE = "sandbox-base";
+// sandbox-image-pool query routes (IMAGE-API-DESIGN.md §2). `/digests/:digest` is checked BEFORE `/:profile`
+// (the single-segment profile RE would otherwise swallow "digests"); both are GET-only + visibility-scoped.
 export const IMAGE_DIGEST_RE = /^\/v1\/images\/digests\/([^/]+)$/;
 export const IMAGE_PROFILE_RE = /^\/v1\/images\/([^/]+)$/;
+// sandbox-image-pool BAKE routes (IMAGE-API-DESIGN.md §P2.1). No trailing-slash variant (`/v1/images/bakes/` →
+// 404, matching the live `/v1/images/` behavior). The `:bakeId` group + sub-action are both-or-neither.
 export const BAKE_ID_RE = /^\/v1\/images\/bakes\/([^/]+)$/;
 export const BAKE_EVENTS_RE = /^\/v1\/images\/bakes\/([^/]+)\/events$/;
 export const BAKE_CANCEL_RE = /^\/v1\/images\/bakes\/([^/]+)\/cancel$/;
@@ -47,24 +67,40 @@ export async function handleImages(req, res, url, ctx) {
     await handleImagesBody(req, res, url, ctx, miss);
     return !miss.fell;
 }
+/** 路由体 = 从 `server.ts` 的 `handle()` 里**整段剪切**过来的原文(唯一改动:统一去缩进两格)。裸 `return;`
+ *  的语义原样 =「本域已应答」;走到函数尾才是「没匹配上」,置 `miss.fell` 交回装配器继续下一个域。
+ *  跨域的东西(deps / 助手 / 单域状态 / 每请求量)一律在首行解构出来,于是下面每一行都逐字不变。 */
 async function handleImagesBody(req, res, url, ctx, miss) {
     const { deps } = ctx;
     const { readJson } = ctx.helpers;
     const { source } = ctx.req;
     const { bakeSubmitLimiter } = ctx.local.images;
+    // ── sandbox-image-pool BAKE control plane (IMAGE-API-DESIGN.md §P2). MUST precede the P1 images block: the P1
+    // profile RE `/^\/v1\/images\/([^/]+)$/` would otherwise swallow `/v1/images/bakes` as profile="bakes" (404),
+    // and a two-segment `/v1/images/bakes/:id` would fall through P1 with NO response (hung socket). image-api is
+    // the UNPRIVILEGED controller: it never bakes — it owns the durable job row/event log/lease, the operator gate,
+    // and the input whitelist; the privileged build runs on the bake-runner (build-host) over the internal claim/ingest.
     if (deps.imageBakes && url.startsWith("/v1/images/bakes")) {
         const bakes = deps.imageBakes;
-        const idx = deps.imageIndex;
-        const principal = gatedPrincipal(req, deps.config);
+        const idx = deps.imageIndex; // the auto-register target (wired together with imageBakes in main.ts)
+        // Identity resolved EXACTLY as P1 (direct-door JWT-without-cnf.bnd, else principalFrom).
+        const principal = gatedPrincipal(req, deps.config); // direct-door safe — identity-only proof; single source of truth (see gatedPrincipal)
         const operators = deps.config.operatorPrincipals;
         const explicitOperator = explicitOperatorOk(principal, operators);
         const cfg = deps.config.imageBakes;
+        // 🔴 H1: the bake-runner identity is DERIVED from its bearer CREDENTIAL (the token-derived `source`,
+        // resolved above from SERVICE_AUTH_TOKENS), NOT a self-asserted x-agent-principal/JWT the runner never
+        // sends. `source` is independent of the directDoorActive principal ternary, so this works identically in
+        // direct-door AND plain mode. The config boot invariant guarantees a runner-credential→runnerPrincipal
+        // mapping exists when bakes are enabled.
         const isRunner = source !== undefined && source !== null && source === cfg.runnerPrincipal;
+        // POST /v1/images/bakes — operator-only submit. EXPLICIT operator gate (NOT the bare isOperator; §P2.4a).
         if (req.method === "POST" && url === "/v1/images/bakes") {
             if (!explicitOperator) {
                 sendError(res, 403, "auth.operator_only", "operator only");
                 return;
             }
+            // Per-principal submission rate guard (§P2.4c) — caps queue-churn even though the lease caps live builds at 1.
             const rl = bakeSubmitLimiter.check(`bake:${principal}`);
             if (!rl.allowed) {
                 res.setHeader("retry-after", String(rl.retryAfterSec));
@@ -72,11 +108,22 @@ async function handleImagesBody(req, res, url, ctx, miss) {
                 return;
             }
             const body = (await readJson(req));
+            // Input WHITELIST — set-membership BEFORE any argv is built (§P2.4d). Off-list → 400/501, never coerced.
             const v = validateBake(body);
+            // B7:errorCode 恒在——band 冲突保留既有 `band-conflict` 机器码(1.x 契约,勿改);其余 400=字段白名单
+            // 拒收、501=该形 bake 尚未开面(custom/tenant P4)。`error` 文案与键序逐字不变。
             if (!v.ok) {
                 sendError(res, v.status, v.conflictBands ? "band-conflict" : v.status === 501 ? "capability.unavailable" : "request.field_invalid", v.error, { ...(v.conflictBands ? { conflictBands: v.conflictBands } : {}) });
                 return;
             }
+            // baseRef allow-list (§P2.4c): a caller CANNOT pass an arbitrary FROM. A present baseRef must be a KNOWN
+            // PUBLISHED `sandbox-base` digest the index has seen (a syntactically-valid attacker digest is still
+            // arbitrary; a published code-* PROFILE digest is also not a valid FROM base — the profile must be
+            // sandbox-base). Absent ⇒ the pinned default base = `SANDBOX_BASE_REF` OR the index's latest published
+            // sandbox-base (design §P2.4c "SANDBOX_BASE_REF / the index's latest published base"). The shape was
+            // already checked in validateBake. The digest the server resolves is the SAME for push:true and
+            // push:false — a node-local (no-push) build's host docker resolves a sandbox-base@sha256 FROM against
+            // the locally-present base image by its config digest (verified live), so one digest serves both paths.
             let effectiveBaseRef;
             if (v.baseRef) {
                 const baseEntry = idx ? await idx.getByDigest(v.baseRef) : null;
@@ -87,15 +134,25 @@ async function handleImagesBody(req, res, url, ctx, miss) {
                 effectiveBaseRef = v.baseRef;
             }
             else {
+                // SANDBOX_BASE_REF pin first; else the index's latest published sandbox-base (operator viewer — the base
+                // pool is server-internal, never tenant-scoped). The server still WHOLLY chooses the base (the caller
+                // never influences it), so the anti-RCE property holds.
                 effectiveBaseRef = cfg.defaultBaseRef ?? (idx ? (await idx.latestPublished(SANDBOX_BASE_PROFILE, { operator: true }))?.digest ?? null : null);
             }
+            // A real (non-dryRun) build MUST FROM a concrete base — build.sh dies (exit 3) on a missing --base-ref.
+            // Fail CLOSED here with an honest config error rather than queue an argv that can never build (a dryRun is
+            // resolve-only and legitimately previews with build.sh's floating base, so it's exempt).
             if (!v.dryRun && !effectiveBaseRef) {
                 sendError(res, 503, "state.no_sandbox_base", "no sandbox-base available to build from (set SANDBOX_BASE_REF or publish a sandbox-base image)");
                 return;
             }
             const argv = buildBakeArgv(v, { baseRef: effectiveBaseRef, cacheBase: cfg.cacheBase });
             const rawIdem = headerStr(req.headers["idempotency-key"]) ?? (typeof body.idempotencyKey === "string" ? body.idempotencyKey : undefined);
+            // Durable submit-idempotency: scope the key to the submitting principal (BL-3 parity) so a replay is the
+            // SAME caller only; the store's `idem_key` UNIQUE is the durable dedupe.
             const idemKey = rawIdem ? scopedIdempotencyKey(rawIdem, source, principal) ?? null : null;
+            // §P2.1/§P2.7 single-flight at SUBMIT (concurrency 1; no auto-queue). A `dryRun` is resolve-only — it never
+            // takes the lease, so it bypasses the busy guard entirely (parallel-safe) and uses the plain createBake.
             const createInput = {
                 profile: v.profile,
                 bands: v.bands,
@@ -108,11 +165,18 @@ async function handleImagesBody(req, res, url, ctx, miss) {
                 requestedBy: principal ?? null,
             };
             if (!v.dryRun) {
+                // (a) an IDENTICAL-argv in-flight bake ⇒ attach (idempotent re-submit, 202) — no second build.
                 const sameArgv = await bakes.findActiveByArgv(argv);
                 if (sameArgv) {
                     sendJson(res, 202, { bakeId: sameArgv.bakeId, eventsUrl: `/v1/images/bakes/${sameArgv.bakeId}/events`, status: sameArgv.status, state: sameArgv.state });
                     return;
                 }
+                // (b) M4: ATOMIC admission — the busy-check and the create are ONE DB statement (`INSERT … SELECT …
+                // WHERE NOT EXISTS (a non-dryRun in-flight bake)`), so two concurrent keyless POSTs can never both queue
+                // (the old findActiveAny()→createBake() check-then-act interleaved). On `created:false` a DIFFERENT bake
+                // holds (or will hold) the single-flight lease ⇒ re-read the active bake. Do NOT silently queue a 45-min
+                // build; surface the active bake + its events URL so the UI attaches to the live one (or attach if a
+                // concurrent identical-argv submit won the race in the gap).
                 const r = await bakes.createBakeIfIdle(createInput);
                 if (!r.created) {
                     const sameNow = await bakes.findActiveByArgv(argv);
@@ -131,6 +195,7 @@ async function handleImagesBody(req, res, url, ctx, miss) {
             sendJson(res, 202, { bakeId: bake.bakeId, eventsUrl: `/v1/images/bakes/${bake.bakeId}/events`, status: bake.status, state: bake.state });
             return;
         }
+        // GET /v1/images/bakes/:bakeId/events — resumable SSE (the live "baking…" view), run-trace-SSE-shaped (§P2.2).
         const evMatch = req.method === "GET" ? BAKE_EVENTS_RE.exec(url) : null;
         if (evMatch) {
             if (!explicitOperator) {
@@ -146,6 +211,7 @@ async function handleImagesBody(req, res, url, ctx, miss) {
             await streamBakeEvents(req, res, bakes, bakeId, cfg.staleMs);
             return;
         }
+        // POST /v1/images/bakes/:bakeId/cancel — cooperative cancel (durable flag; the runner kills the pgid, §P2.11).
         const cancelMatch = req.method === "POST" ? BAKE_CANCEL_RE.exec(url) : null;
         if (cancelMatch) {
             if (!explicitOperator) {
@@ -158,31 +224,39 @@ async function handleImagesBody(req, res, url, ctx, miss) {
                 sendError(res, 404, "not_found.bake", "bake not found");
                 return;
             }
-            const flagged = await bakes.requestCancel(bakeId);
+            const flagged = await bakes.requestCancel(bakeId); // only flags a non-terminal row
             sendJson(res, 202, { bakeId, cancelRequested: true, note: flagged ? "cancel requested — the runner kills the build at the next heartbeat" : "bake already terminal — cancel is a no-op" });
             return;
         }
+        // POST /v1/images/bakes/claim — RUNNER-ONLY: long-poll claim (§P2.12). Find the oldest queued bake and claim
+        // it in one call (the discovery + the single-flight CAS). Checked BEFORE the per-bake `…/:id/claim` so the
+        // bare `claim` is not swallowed as `:bakeId="claim"`. 204 when the queue is empty (the runner idle-polls).
         if (req.method === "POST" && url === "/v1/images/bakes/claim") {
             if (!isRunner) {
                 sendError(res, 403, "auth.bake_runner_only", "bake-runner only");
                 return;
             }
             const body = (await readJson(req));
+            // H1: the runner is credential-authed (no x-agent-principal), so `principal` may be undefined — fall back
+            // to the credential-derived `source` (== runnerPrincipal, isRunner guaranteed it) as the runner identity.
             const runnerId = typeof body.runnerId === "string" && body.runnerId.length > 0 ? body.runnerId : (principal ?? source ?? cfg.runnerPrincipal);
+            // Bounded find-then-CAS: another runner racing us may win the id we just read, so retry the next queued id
+            // a few times before giving up (the queue is normally short + replicas=1, so 1 pass is the common case).
             let claimed = null;
             for (let attempt = 0; attempt < 4 && !claimed; attempt++) {
                 const nextId = await bakes.findNextQueuedId();
                 if (!nextId)
-                    break;
+                    break; // queue empty
                 claimed = await bakes.claimBake(nextId, runnerId, cfg.leaseMs);
             }
             if (!claimed) {
                 res.writeHead(204).end();
                 return;
-            }
+            } // nothing claimable right now (the runner idle-polls)
             sendJson(res, 200, claimResponse(claimed));
             return;
         }
+        // POST /v1/images/bakes/:bakeId/claim — RUNNER-ONLY: single-flight lease of THIS queued bake (§P2.7).
         const claimMatch = req.method === "POST" ? BAKE_CLAIM_RE.exec(url) : null;
         if (claimMatch) {
             if (!isRunner) {
@@ -194,12 +268,16 @@ async function handleImagesBody(req, res, url, ctx, miss) {
             const runnerId = typeof body.runnerId === "string" && body.runnerId.length > 0 ? body.runnerId : (principal ?? source ?? cfg.runnerPrincipal);
             const claimed = await bakes.claimBake(bakeId, runnerId, cfg.leaseMs);
             if (!claimed) {
+                // Lost the single-flight (already claimed, or the pool lease is held by a live build) → 409.
                 sendError(res, 409, "conflict.bake_not_claimable", "bake not claimable (already claimed or the build lease is held)");
                 return;
             }
+            // Return the VETTED argv + the per-bake ingest secret (minted at claim) the runner echoes on ingest.
             sendJson(res, 200, claimResponse(claimed));
             return;
         }
+        // POST /v1/images/bakes/:bakeId/ingest — RUNNER-ONLY: append one build.sh line + heartbeat the lease.
+        // Maps build.sh `{event}` → an SSE kind + the coarse status; on a COMPLETE `done` triggers auto-register.
         const ingestMatch = req.method === "POST" ? BAKE_INGEST_RE.exec(url) : null;
         if (ingestMatch) {
             if (!isRunner) {
@@ -212,12 +290,16 @@ async function handleImagesBody(req, res, url, ctx, miss) {
                 sendError(res, 404, "not_found.bake", "bake not found");
                 return;
             }
+            // Per-bake ingest secret (minted at claim) — so a stale/rogue runner can't inject frames into another bake.
             const presented = headerStr(req.headers["x-bake-ingest-secret"]);
             if (!bake.ingestSecret || !presented || !safeEqual(presented, bake.ingestSecret)) {
                 sendError(res, 403, "auth.ingest_secret_invalid", "invalid ingest secret");
                 return;
             }
             const line = (await readJson(req));
+            // A `heartbeat` frame (§P2.7/§P2.11): advance the lease, append NO event, and echo the durable cancel flag +
+            // lease validity so the runner kills the build.sh process group at the next tick. A lost lease (the reaper
+            // stole it as stale, or a terminal flip released it) → 409 so the runner aborts (it no longer owns the build).
             if (line.event === "heartbeat") {
                 const fresh = await bakes.getBake(bakeId);
                 if (!fresh || fresh.status !== "running") {
@@ -232,11 +314,17 @@ async function handleImagesBody(req, res, url, ctx, miss) {
                 sendJson(res, 200, { accepted: true, leaseValid: true, cancelRequested: fresh.cancelRequested });
                 return;
             }
+            // 🔴 H3 (zombie/reaped runner) — PRIMARY guard: a terminal/reaped bake accepts NO frames. Re-read the row
+            // (the `bake` fetched above may be stale) and reject 409 for ALL non-heartbeat frames when it is no longer
+            // running, mirroring the heartbeat branch. Otherwise a zombie/duplicate runner that still holds a valid
+            // ingest_secret could inject `building` index rows + out-of-band SSE frames into a dead bake's stream.
             const fresh = await bakes.getBake(bakeId);
             if (!fresh || fresh.status !== "running") {
                 sendJson(res, 409, { accepted: false, leaseValid: false, cancelRequested: fresh?.cancelRequested ?? false, errorCode: "conflict.bake_not_running" });
                 return;
             }
+            // A real build.sh frame: also advance the lease (the runner heartbeats via its frame cadence too) and echo
+            // the cancel flag so a cancel observed between heartbeats still reaches the runner promptly.
             if (fresh.runnerId) {
                 await bakes.heartbeatLease(bakeId, fresh.runnerId, cfg.leaseMs).catch(() => undefined);
             }
@@ -245,6 +333,8 @@ async function handleImagesBody(req, res, url, ctx, miss) {
             sendJson(res, result.status, { ...result.body, cancelRequested: after?.cancelRequested ?? false, leaseValid: true });
             return;
         }
+        // GET /v1/images/bakes/:bakeId — poll fallback, `{bake:}` envelope, null-not-omitted (§P2.1). Checked LAST so
+        // the `/events|/cancel|/claim|/ingest` sub-actions (two-segment) win first.
         const idMatch = req.method === "GET" ? BAKE_ID_RE.exec(url) : null;
         if (idMatch) {
             if (!explicitOperator) {
@@ -260,15 +350,25 @@ async function handleImagesBody(req, res, url, ctx, miss) {
             sendJson(res, 200, { bake: bakeView(bake) });
             return;
         }
+        // No trailing-slash variant, no other bake route → 404 (parity with `/v1/images/` live behavior).
         sendError(res, 404, "not_found.route", "not found");
         return;
     }
+    // ── sandbox-image-pool control API (IMAGE-API-DESIGN.md §2, pool design §8) — P1: query + select. The image
+    // INDEX is queried/selected here (bake/publish = P2/P3, later). Visibility is viewer-scoped (Codex A1): a
+    // tenant principal sees `public` + its OWN tenant images; an operator sees all. Identity is resolved the same
+    // way as the approval reads (direct-door JWT-without-cnf.bnd, else principalFrom); an absent principal still
+    // sees the public catalog (anonymous public-pull parity — pool = docker.io/claybobby; SWR deprecated) but no tenant rows.
     if (deps.imageIndex && url.startsWith("/v1/images")) {
         const idx = deps.imageIndex;
-        const principal = gatedPrincipal(req, deps.config);
+        const principal = gatedPrincipal(req, deps.config); // direct-door safe — identity-only proof; single source of truth (see gatedPrincipal)
+        // explicitOperator (NOT isOperator): for image VISIBILITY, an empty OPERATOR_PRINCIPALS must NOT make every
+        // caller an operator (that would leak tenant-scoped images). Adversarial-review HIGH — same fix as the P0.5
+        // per-task resolve in main.ts. (Approval operator gates below keep isOperator's legacy empty=all boundary.)
         const operator = explicitOperator(principal, deps.config.operatorPrincipals);
         const viewer = { operator, tenantId: principal ?? null };
         const q = new URL(req.url ?? "", "http://x").searchParams;
+        // GET /v1/images — the paginated catalog. ?profile=&status=&capability=&latest=true&limit=&cursor=
         if (req.method === "GET" && url === "/v1/images") {
             const limRaw = q.get("limit");
             const { entries, nextCursor } = await idx.list({
@@ -283,6 +383,9 @@ async function handleImagesBody(req, res, url, ctx, miss) {
             sendJson(res, 200, { images: entries, nextCursor });
             return;
         }
+        // POST /v1/images/select — the §7 per-sandbox resolution: profile → newest published visible digest +
+        // podContract, with capability admission (Codex B3). Pure resolution (no build); the caller threads the
+        // returned `ref` (repo@digest) into the kata adapter's per-sandbox image (today a worker-global env).
         if (req.method === "POST" && url === "/v1/images/select") {
             const body = (await readJson(req));
             const profile = typeof body.profile === "string" ? body.profile : "";
@@ -315,7 +418,12 @@ async function handleImagesBody(req, res, url, ctx, miss) {
             });
             return;
         }
+        // POST /v1/images/register — operator-only ingest (P1: seed from the live bake manifests; P3 atomic-publish
+        // drives it for real). Minimal validation here; the publish pipeline supplies a full manifest projection.
         if (req.method === "POST" && url === "/v1/images/register") {
+            // EXPLICIT operator gate (§P2.4a MUST-FIX, the P1 follow-up): NOT the bare `operator`/isOperator, whose
+            // empty-OPERATOR_PRINCIPALS "true-for-all" makes this index-mutating door world-writable. (The block-level
+            // `operator` stays for read visibility; the MUTATION must require a concrete configured operator.)
             if (!explicitOperatorOk(principal, deps.config.operatorPrincipals)) {
                 sendError(res, 403, "auth.operator_only", "operator only");
                 return;
@@ -325,6 +433,11 @@ async function handleImagesBody(req, res, url, ctx, miss) {
                 sendError(res, 400, "request.field_invalid", "profile, repo, digest are required");
                 return;
             }
+            // 🔴 STATUS-MONOTONIC register (adversarial-review HIGH finding): the unconditional `upsert` let an
+            // operator POST status:'building' for an already-`published` digest and SILENTLY DE-PUBLISH a live image
+            // (latestPublished then 404s → sandbox-create fails — the P2.10 bug class, LIVE on this door). registerBuilding
+            // never downgrades a published row (building→published still works; published→building is a no-op on the
+            // lifecycle). A deliberate take-down is the explicit deprecate path (P3), never a side effect of register.
             const id = await idx.registerBuilding({
                 profile: b.profile,
                 bands: Array.isArray(b.bands) ? b.bands : [],
@@ -348,6 +461,7 @@ async function handleImagesBody(req, res, url, ctx, miss) {
             sendJson(res, 200, { id });
             return;
         }
+        // GET /v1/images/digests/:digest — one entry by immutable digest (what a running sandbox was built from).
         const digMatch = req.method === "GET" ? IMAGE_DIGEST_RE.exec(url) : null;
         if (digMatch) {
             const entry = await idx.getByDigest(decodeURIComponent(digMatch[1]));
@@ -358,6 +472,7 @@ async function handleImagesBody(req, res, url, ctx, miss) {
             sendJson(res, 200, { image: entry });
             return;
         }
+        // GET /v1/images/:profile — the newest published visible entry for a profile (latest tag + versions).
         const profMatch = req.method === "GET" ? IMAGE_PROFILE_RE.exec(url) : null;
         if (profMatch) {
             const entry = await idx.latestPublished(decodeURIComponent(profMatch[1]), viewer);
@@ -371,6 +486,9 @@ async function handleImagesBody(req, res, url, ctx, miss) {
     }
     miss.fell = true;
 }
+/** The image_bake SSE (P2.2/P2.8) — the SAME pump, with the run-trace-SSE-shaped bake frame
+ *  (`data: {kind, seq, ts, ...kindFields}`) + a synthetic `done{failed}` stale frame so a reader settles
+ *  (never hangs) when the runner is lost before the reaper's terminal event lands. */
 async function streamBakeEvents(req, res, bakes, bakeId, staleMs) {
     await streamSseLog(req, res, {
         statusOf: async (id) => {
@@ -379,6 +497,8 @@ async function streamBakeEvents(req, res, bakes, bakeId, staleMs) {
         },
         getEvents: (id, after) => bakes.getEvents(id, after),
         retainedFrom: (id) => bakes.retainedFrom(id),
+        // The bake frame carries kind+seq+ts INSIDE data (center locks its relay to this), distinct from the
+        // task_run `{type, ...data}` shape. `level` rides along so an opt-in `raw` log frame is distinguishable.
         formatEvent: (ev) => ({
             id: ev.seq,
             event: ev.kind,
@@ -387,6 +507,9 @@ async function streamBakeEvents(req, res, bakes, bakeId, staleMs) {
         staleFrame: () => ({ event: "done", data: { kind: "done", status: "FAILED", error: "bake-runner lost (no heartbeat)", digest: null, indexId: null, repo: null, ref: null } }),
     }, bakeId, staleMs);
 }
+/** The operator poll view of a bake (§P2.1 `{bake:}` envelope, null-not-omitted). Projects the durable row MINUS
+ *  the runner-internal secret/lease fields (`ingestSecret`/`runnerId`/`leaseUntil`/`cancelRequested`/`argv`) — an
+ *  ops surface, but the per-bake ingest secret is a credential and the argv is build-host detail. */
 function bakeView(b) {
     return {
         bakeId: b.bakeId,
@@ -412,6 +535,9 @@ function bakeView(b) {
         updatedAt: b.updatedAt,
     };
 }
+/** The RUNNER claim response (§P2.7/§P2.12): the VETTED argv + the per-bake ingest secret (minted at claim, echoed
+ *  on every ingest) + the profile/bands the runner needs for its profile-aware hard deadline. This is the ONLY
+ *  place the ingest secret leaves image-api — to the runner that just won the lease, over the internal claim. */
 function claimResponse(claimed) {
     return {
         bakeId: claimed.bakeId,
@@ -425,76 +551,143 @@ function claimResponse(claimed) {
         leaseUntil: claimed.leaseUntil,
     };
 }
+/** Map ONE build.sh JSON line (runner-forwarded, with `lineOrd`) → the durable bake event log + the coarse status
+ *  transition, and on a `done:COMPLETE` trigger the status-monotonic auto-register (§P2.3/§P2.10).
+ *
+ * build.sh emits `resolved | state | step | image | manifest | done` (read, not guessed). The runner forwards each
+ * verbatim plus a per-line `lineOrd` (at-least-once dedupe, uq_line). `done`/`manifest` carry a build-host FS path, not
+ * the body, so the runner reads the manifest body off the host and forwards it as `manifestBody` on the `done`.
+ *
+ * The COARSE status (the reader's terminality column) is driven ONLY by `state`/`done` (§P2.3 MUST-FIX): every
+ * non-terminal state → `running`; COMPLETE→done, FAILED/CANCELLED→failed. A `state` line that is non-terminal only
+ * denormalizes the UI progress bar (never the coarse status). The terminal `done` is appended BEFORE the coarse
+ * row flips (event-before-row latch) so the SSE reader always observes it.
+ */
 async function ingestBakeLine(bakes, idx, bake, line, registry) {
     const bakeId = bake.bakeId;
     const event = typeof line.event === "string" ? line.event : "";
     const lineOrd = typeof line.lineOrd === "number" ? line.lineOrd : typeof line.line_ord === "number" ? line.line_ord : null;
+    // A non-`done` build.sh line: append it as the matching kind + denormalize `state` for the UI progress bar.
+    // (`resolved | state | step | image | manifest | log` — `manifest` is folded; the body rides the `done`.)
     if (event !== "done") {
         if (event === "state") {
             const state = typeof line.state === "string" ? line.state : null;
             if (state)
-                await bakes.setState(bakeId, state);
+                await bakes.setState(bakeId, state); // denormalize only — NEVER the coarse terminality (§P2.3)
             const seq = await bakes.appendEvent(bakeId, "state", { state }, { lineOrd });
             return { status: 200, body: { accepted: true, seq } };
         }
+        // resolved | step | image | log | manifest → store under the build.sh event name as the SSE kind (the runner
+        // already shapes the data fields; manifest is kept as a `step`-adjacent frame for the trace, body on `done`).
         const kind = event === "manifest" ? "manifest" : event;
         const level = event === "log" && line.level === "raw" ? "raw" : null;
         const { event: _e, lineOrd: _lo, line_ord: _li, ...data } = line;
+        // L3 (defense-in-depth): redactDeep the ingested non-terminal frame data before it's stored/streamed, mirroring
+        // streamTaskTrace's tool-arg redaction. build.sh keeps raw cred output off stdout (only resolved.mergedEnv —
+        // frozen server recipes — is unredacted today), but this closes the resolved.mergedEnv tail + any future
+        // `?logs=1` raw-tail before it's wired. (redactSecrets is non-exhaustive — hardening, not a guarantee.)
         const seq = await bakes.appendEvent(bakeId, kind, redactDeep(data), { lineOrd, level });
         return { status: 200, body: { accepted: true, seq } };
     }
-    const doneStatus = typeof line.status === "string" ? line.status : "FAILED";
+    // ── terminal `done` — drive the auto-register + the coarse terminal flip (§P2.10).
+    const doneStatus = typeof line.status === "string" ? line.status : "FAILED"; // COMPLETE | FAILED | CANCELLED
     const exitCode = typeof line.exitCode === "number" ? line.exitCode : doneStatus === "COMPLETE" ? 0 : null;
     const cancelled = doneStatus === "CANCELLED";
     const errorText = typeof line.error === "string" ? redactSecrets(line.error) : null;
     const tag = typeof line.tag === "string" ? line.tag : bake.tag;
-    let digest = typeof line.digest === "string" && line.digest.length > 0 ? line.digest : null;
+    let digest = typeof line.digest === "string" && line.digest.length > 0 ? line.digest : null; // let:R22 身份折叠可置空
     let indexId = bake.indexId;
     let repo = bake.repo;
     let ref = bake.ref;
     let manifestSha = bake.manifestSha;
+    // The done STATUS/error can be DOWNGRADED to FAILED on a register-after-build failure (the partial-publish
+    // contract below) — start from build.sh's reported status and mutate iff the register throws.
     let finalStatus = doneStatus;
     let finalError = errorText;
     let finalExit = exitCode;
+    // M1: a register-after-build downgrade (COMPLETE→FAILED) must OWN the terminal errorCode — a stale COMPLETE-time
+    // runner code (e.g. none) must not mask the partial-publish failure. Tracked here, consulted at the errorCode pick.
     let registerDowngraded = false;
+    // Auto-register (only a COMPLETE with a manifest body + a digest is registerable). EVENT-BEFORE-ROW: we register
+    // (idx write) and append the `done` SSE event BEFORE the coarse terminal flip, so a `done` is always observable
+    // even if the terminal write retries.
+    //
+    // PARTIAL-PUBLISH CONTRACT (§P2.2/§P2.10): a register-after-build failure (a TiDB blip AFTER build.sh COMPLETE)
+    // is surfaced as `digest` present + `indexId` null + `status:"FAILED"` — a built-but-unregistered partial, NOT a
+    // successful COMPLETE and NOT a re-bake trigger (a P3 reconciliation tick re-registers it). So the done status is
+    // downgraded COMPLETE→FAILED on the catch, with the digest/repo/ref still carried so the artifact is findable.
+    // M3: the `register` step frames are EVENT-LOG writes that must follow the SAME terminality gate as the done
+    // event — buffer them here and replay only when THIS call wins the setTerminal CAS (affectedRows>=1). The idx
+    // writes (registerBuilding/setIndexId) are status-monotonic and idempotent, so they may run before the CAS.
     const registerSteps = [];
     if (doneStatus === "COMPLETE" && digest && idx) {
         const manifestBody = (line.manifestBody ?? line.manifest);
+        // 🔴 H3 (zombie/reaped runner): re-read the bake row HERE (the passed `bake` may be stale) and ONLY register
+        // when it is still non-terminal. A reaped/terminal row must never inject a fresh `building` index row.
         const fresh = await bakes.getBake(bakeId);
         const nonTerminal = !!fresh && (fresh.status === "queued" || fresh.status === "running");
         if (manifestBody && typeof manifestBody === "object" && nonTerminal) {
+            // 🔴 H3/H5: derive repo/profile from the VETTED control-plane bake row (+ the manifest's profile only as a
+            // fallback for a --bands "custom" bake) — NEVER trust the runner-supplied manifestBody for the server-fixed
+            // repo identity. H5: prefix the configured registry host (BAKE_IMAGE_REGISTRY — historically SWR, now
+            // docker.io/claybobby; SWR deprecated) so the bake row's repo/ref/index-id match the P1 seed
+            // convention (`${registry}/${profile}`); null registry ⇒ the host-less node-local name (documented
+            // non-pullable). For a no-push bake the digest is the build.sh LOCAL_ID (node-local, NOT selectable —
+            // registerBuilding writes status:'building', and latestPublished filters status='published').
             const profile = bake.profile && bake.profile !== "custom" ? bake.profile : (manifestBody.profile && manifestBody.profile !== "custom" ? manifestBody.profile : "custom");
             repo = registry ? `${registry}/${profile}` : `sema-images/${profile}`;
             manifestSha = typeof line.manifestSha === "string" ? line.manifestSha : (typeof line.manifest?.sha256 === "string" ? String(line.manifest.sha256) : bake.manifestSha);
+            // codex R23:身份候选(digest/repo/manifestSha)先验**后写**——node-postgres 的 UTF-8 编码会把
+            // lone surrogate 折成 U+FFFD,registerBuilding 可能**成功**落一条身份已变形的 index 行,随后
+            // 帧级 identityInvalid 折叠才拒帧 → index 已被污染且与拒帧后的 null 身份终态互相矛盾。脏身份
+            // ⇒ 零 index 写(indexId 强制 null),repo/manifestSha 已按本帧生效值赋出,下方折叠必然命中
+            // 并独占 FAILED/null 身份终态(该臂不是 register 失败,不走 partial-publish 契约/P3 补注册)。
             if (pgHasUnstorable(digest) || pgHasUnstorable(repo) || pgHasUnstorable(manifestSha)) {
                 indexId = null;
                 registerSteps.push({ step: "register", status: "skipped", reason: "identity fields contained unstorable bytes" });
             }
             else {
+                // Synthesize a `step:"register"` start around the auto-register so a resuming reader sees the register phase
+                // (§P2.2: the `register` step is image-api-synthesized — build.sh stops at COMPLETE + the manifest line).
                 registerSteps.push({ step: "register", status: "running" });
                 try {
                     const entry = manifestToIndexEntry(manifestBody, { repo, digest, status: "building", manifestSha, sizeBytes: manifestBody.sizeBytes ?? null, signed: false });
+                    // 🔴 H3: FORCE visibility/tenantId from the control plane — a P2 standard-pool bake is ALWAYS a public,
+                    // tenant-less row. NEVER let the runner-supplied manifestBody (owner/visibility) decide the index row's
+                    // tenancy (a zombie runner could otherwise write a `tenant`-visibility row with an attacker-chosen tenant).
                     entry.visibility = "public";
                     entry.tenantId = null;
+                    // STATUS-MONOTONIC register (§P2.10 MUST-FIX): registerBuilding NEVER downgrades a `published` row — a
+                    // late/duplicate `done` for an already-promoted digest is a no-op on the lifecycle, never a regression.
                     indexId = await idx.registerBuilding(entry);
                     ref = `${repo}@${digest}`;
+                    // codex R24:setIndexId 是 non-terminal 门写(见 store 注释)——本请求悬在 registerBuilding 期间
+                    // 另一 done(如 R23 的 dirty 折叠帧)可能已赢 setTerminal;未绑定⇒indexId 不进本帧 terminal 对象
+                    // (本请求随后必输 CAS,不落行不落事件,index 里的孤 building 行不 publish 不可选、由生命周期兜底)。
                     const bound = await bakes.setIndexId(bakeId, indexId);
                     if (!bound)
                         indexId = null;
                     registerSteps.push({ step: "register", status: "ok" });
                 }
                 catch (err) {
+                    // built-but-unregistered partial (a TiDB blip post-build): downgrade the done to FAILED, keep digest+repo
+                    // (+ ref so the artifact is findable), leave indexId null. The P3 reconciliation tick re-registers it.
                     indexId = null;
                     ref = `${repo}@${digest}`;
                     finalStatus = "FAILED";
-                    registerDowngraded = true;
-                    finalExit = exitCode ?? 0;
+                    registerDowngraded = true; // M1: this FAILED is owned by the register failure, not the runner's code.
+                    finalExit = exitCode ?? 0; // build.sh itself succeeded (exit 0); the register is the post-build failure.
                     finalError = redactSecrets(`index register failed after a COMPLETE build (built-but-unregistered partial): ${String(err?.message ?? err)}`);
                     registerSteps.push({ step: "register", status: "fail", reason: "index register failed (TiDB?)" });
                 }
             }
         }
     }
+    // errorCode + coarse status are computed from the FINAL (possibly-downgraded) status, not build.sh's raw one.
+    // M1 (§P2.14 #2): PREFER a validated runner-supplied `line.errorCode` (the disk-guard's "disk", a future
+    // build-time "band-conflict" — codes the exit-code mapper cannot reconstruct) over the recompute. A `cancelled`
+    // terminal always wins (the kill is authoritative); a register-downgraded FAILED owns its own code (the runner's
+    // COMPLETE-time code is stale), so it falls back to the exit mapper.
     const suppliedCode = typeof line.errorCode === "string" && RUNNER_ERROR_CODES.has(line.errorCode)
         ? line.errorCode
         : undefined;
@@ -503,9 +696,14 @@ async function ingestBakeLine(bakes, idx, bake, line, registry) {
         : suppliedCode !== undefined && !registerDowngraded
             ? suppliedCode
             : errorCodeForExit(finalExit, cancelled);
+    // M1: a band-conflict terminal carries the offending band ids so the composer UI can red-highlight the chips
+    // (§P2.14 #2). Only honored when the FINAL code is band-conflict (a downgraded/other terminal carries none).
     const conflictBands = errorCode === "band-conflict" && Array.isArray(line.conflictBands)
         ? line.conflictBands.filter((b) => typeof b === "string")
         : null;
+    // codex R22:身份位(digest/repo/ref/manifestSha)带不可存字节=帧无效——在**构造前**统一折叠
+    // (row/SSE done/HTTP 三面同源一份 effective 对象;store 内折叠留作双保险,值恒等)。COMPLETE 折
+    // FAILED(null 身份的成功=谎),错误面补一句归因。
     const identityInvalid = (typeof digest === "string" && pgHasUnstorable(digest)) ||
         (typeof repo === "string" && pgHasUnstorable(repo)) ||
         (typeof ref === "string" && pgHasUnstorable(ref)) ||
@@ -516,11 +714,17 @@ async function ingestBakeLine(bakes, idx, bake, line, registry) {
         repo = null;
         ref = null;
         manifestSha = null;
-        indexId = null;
+        indexId = null; // codex R23:null 身份终态不得声称 index 绑定(register 门已跳过全部 index 写)
         finalError = finalError ? `${finalError}; identity fields contained unstorable bytes` : "terminal frame identity fields contained unstorable bytes";
     }
     const finalState = (finalStatus === "COMPLETE" ? "COMPLETE" : finalStatus === "CANCELLED" ? "CANCELLED" : "FAILED");
     const coarse = coarseStatusForState(finalState);
+    // M3: flip the coarse terminal row FIRST and gate the terminal `done` EVENT (+ the register `step` frames) on
+    // WINNING that queued/running→terminal CAS. A late/contradictory terminal (cancel-vs-complete, reaper-vs-recovery)
+    // sees affectedRows===0 and writes NO event, so the SSE log never replays a second, conflicting terminal `done`.
+    // Invariant: at most one terminal `done` event per bake, always matching the coarse row outcome (§P2.14).
+    // L2: the flip is idempotent (`WHERE status IN ('queued','running')`), so a transient throw is safe to retry
+    // rather than leaving the row `running` with a `done` event the reaper would later contradict.
     let affectedRows = 0;
     const terminal = {
         status: coarse === "done" ? "done" : "failed",
@@ -547,9 +751,13 @@ async function ingestBakeLine(bakes, idx, bake, line, registry) {
         }
     }
     if (lastErr !== undefined) {
+        // L2: exhausted the bounded retry — DON'T 500 (safeIngest swallows it and the row would stay `running` with no
+        // terminal event the reaper later contradicts). Return a non-terminal ack so the runner re-POSTs the
+        // (lineOrd-idempotent) done to re-drive the flip.
         return { status: 200, body: { accepted: true, terminal: false, needsFlip: true } };
     }
     if (affectedRows >= 1) {
+        // We won the transition: replay the buffered register `step` frames, then append the single terminal `done`.
         for (const s of registerSteps)
             await bakes.appendEvent(bakeId, "step", s);
         await bakes.appendEvent(bakeId, "done", {