@sema-agent/server 7.43.0 → 7.44.0

package/dist/http/routes/images.js

@@ -8,14 +8,8 @@ import { sendJson, sendError } from "../send.js";
 import { headerStr, safeEqual, gatedPrincipal, explicitOperatorOk } 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";
@@ -23,46 +17,29 @@ export function coarseStatusForState(state) {
         return "failed";
     return "running";
 }
-/** [2373]C-7:202 受理体的**唯一铸点**——此前四份逐字构造散在 attach/竞态重读/新建/dryRun 四臂,
- *  下一个字段必然只加到其中两处(:213/:217 与 :193/:206 已有分叉风险)。status/state 双发保留
- *  (status=state 的粗化像,省客户端抄映射表)。 */
 function bakeAcceptedBody(b) {
     return { bakeId: b.bakeId, eventsUrl: `/v1/images/bakes/${b.bakeId}/events`, status: b.status, state: b.state };
 }
-/** 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"; // build.sh's generate-time inter-band collision (gen-dockerfile exit 6/7/8 → 9).
+            return "band-conflict";
         case 10:
             return "duplicate";
         case 124:
             return "timeout";
         case 507:
-            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).
+            return "disk";
         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$/;
@@ -73,40 +50,24 @@ 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; // 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 idx = deps.imageIndex;
+        const principal = gatedPrincipal(req, deps.config);
         const operators = deps.config.operatorPrincipals;
         const isExplicitOperator = 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 (!isExplicitOperator) {
                 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));
@@ -114,22 +75,11 @@ 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;
@@ -140,25 +90,15 @@ 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,
@@ -171,18 +111,11 @@ 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, bakeAcceptedBody(sameArgv));
                     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);
@@ -201,7 +134,6 @@ async function handleImagesBody(req, res, url, ctx, miss) {
             sendJson(res, 202, bakeAcceptedBody(bake));
             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 (!isExplicitOperator) {
@@ -217,7 +149,6 @@ 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 (!isExplicitOperator) {
@@ -230,39 +161,31 @@ async function handleImagesBody(req, res, url, ctx, miss) {
                 sendError(res, 404, "not_found.bake", "bake not found");
                 return;
             }
-            const flagged = await bakes.requestCancel(bakeId); // only flags a non-terminal row
+            const flagged = await bakes.requestCancel(bakeId);
             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; // queue empty
+                    break;
                 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) {
@@ -274,16 +197,12 @@ 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) {
@@ -296,16 +215,12 @@ 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") {
@@ -320,17 +235,11 @@ 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);
             }
@@ -339,8 +248,6 @@ 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 (!isExplicitOperator) {
@@ -356,25 +263,15 @@ 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); // direct-door safe — identity-only proof; single source of truth (see gatedPrincipal)
-        // explicitOperatorOk (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 principal = gatedPrincipal(req, deps.config);
         const operator = explicitOperatorOk(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({
@@ -389,9 +286,6 @@ 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 : "";
@@ -424,12 +318,7 @@ 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;
@@ -439,11 +328,6 @@ 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 : [],
@@ -467,7 +351,6 @@ 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]));
@@ -478,7 +361,6 @@ 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);
@@ -491,28 +373,11 @@ async function handleImagesBody(req, res, url, ctx, miss) {
         }
     }
     else if (url === "/v1/images" || url.startsWith("/v1/images/")) {
-        // 🔴 #F1([3397]-5 同族缺口):索引缺席时**整个域不挂载**,请求此前一路落到全局路由表尾的
-        // `404 not_found.route` —— 与「路由拼错了」同一个码,消费端结构上分不出「这个部署没接这个面」
-        // 与「我 URL 写错了」(trial-by-404 的最坏形:两种成因的处置完全相反)。改成诚实的能力拒。
-        //
-        // 谓词与上面那条挂载合取式**同一个符号**(`deps.imageIndex`),所以 `/v1/capabilities` 的 `images`
-        // 位(同一谓词)说 yes ⟺ 这条臂不触发 ⟺ 目录读面真能用。
-        //
-        // ⚠️ 判据是**按段**的(`=== "/v1/images"` 或 `"/v1/images/"` 前缀),不是上面挂载式那个裸前缀:
-        // `/v1/imagesfoo` 是**拼错的路由**,不是本域的路径,它该继续拿 404(索引在场的部署上它本来就落 404
-        // —— 两种部署形对同一个手滑给出不同的码,那正是本臂要消灭的那种含糊)。
-        //
-        // ⚠️ bake 子面**不误伤**:`deps.imageBakes` 在场时 `/v1/images/bakes*` 已在本函数最上面的域里应答
-        // 并 `return`,走不到这里;两者都缺席时(local 后端的真实形态——两个工厂它都不实现)本臂如实
-        // 回答「这个部署没有 sandbox-image-pool」,那对 bakes 路径也是真话。
         sendError(res, 501, "capability.image_index_required", "the sandbox-image-pool requires a SQL store backend (DB_BACKEND=mysql|pg) — the local backend wires no image index");
         return;
     }
     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) => {
@@ -521,8 +386,6 @@ 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,
@@ -531,9 +394,6 @@ 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,
@@ -559,9 +419,6 @@ 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,
@@ -575,143 +432,76 @@ 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); // denormalize only — NEVER the coarse terminality (§P2.3)
+                await bakes.setState(bakeId, state);
             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 } };
     }
-    // ── 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 doneStatus = typeof line.status === "string" ? line.status : "FAILED";
     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:R22 身份折叠可置空
+    let digest = typeof line.digest === "string" && line.digest.length > 0 ? line.digest : null;
     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; // 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.
+                    registerDowngraded = true;
+                    finalExit = exitCode ?? 0;
                     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;
@@ -720,14 +510,9 @@ 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)) ||
@@ -738,17 +523,11 @@ async function ingestBakeLine(bakes, idx, bake, line, registry) {
         repo = null;
         ref = null;
         manifestSha = null;
-        indexId = null; // codex R23:null 身份终态不得声称 index 绑定(register 门已跳过全部 index 写)
+        indexId = null;
         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",
@@ -775,13 +554,9 @@ 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", {