@sema-agent/server 4.1.1 → 4.1.2

package/dist/http/routes/session-sync.js

@@ -2,7 +2,7 @@ import { once } from "node:events";
 import { randomBytes, createHash } from "node:crypto";
 import { sessionLogDigest, sessionLogDigestsComparable, StreamingImportValidator, SessionError, SessionPolicyError } from "@sema-agent/core";
 import { StringDecoder } from "node:string_decoder";
-import { exportSessionManifest, classifySyncRelationshipByIds, SyncConflictError } from "../../session-sync.js";
+import { exportSessionManifest, classifySyncRelationshipByIds, SyncConflictError, fileSnapshotImportFace } from "../../session-sync.js";
 import { isUuidShape } from "../../security.js";
 import { sendJson, sendError, msg } from "../send.js";
 import { gatedPrincipal, explicitOperatorOk } from "../principal-gate.js";
@@ -19,8 +19,8 @@ const SYNC_NDJSON_LINE_MAX_BYTES = 8 * 1024 * 1024;
 /** 2c session-sync P1d-β: the Phase-B entry batch size — entries are fed to `appendBatch` in chunks of this many, so
  *  in-flight memory is O(batch), not O(session). 500 mirrors the PULL stream's keyset page size (one bounded txn). */
 const SYNC_IMPORT_BATCH = 500;
-/** 64 lowercase-hex chars = a sha256 content-address (the blob hash + the GET :hash param shape). */
-const SHA256_HEX_RE = /^[0-9a-f]{64}$/;
+// SHA256_HEX_RE = 64 lowercase-hex chars, a sha256 content-address (the blob hash + the GET :hash param shape).
+import { SHA256_HEX_RE } from "../../digest-form.js";
 export function createSessionSyncLocal() {
     const pendingStagings = new Map();
     const importLeases = new Map();
@@ -379,11 +379,11 @@ async function handleSessionSyncBody(req, res, url, ctx, miss) {
                     // 焊死成永久分裂(Phase B 的重放永远不再运行)。identical 时把附随物幂等重放(snapshot=
                     // content-addressed importManifest,已存在=no-op;policy/anchor put=幂等),失败=同款 422,
                     // 客户端 re-PUT blob 再重试——自愈闭环。
-                    const fss = deps.fileSnapshotStore;
-                    if (fss?.importManifest && fss.getBlob && snapshots.length > 0) {
-                        const getBlobA = (h) => fss.getBlob(h);
+                    const importFaceIdentical = fileSnapshotImportFace(deps.fileSnapshotStore);
+                    if (importFaceIdentical && deps.fileSnapshotStore?.getBlob && snapshots.length > 0) {
+                        const getBlobA = (h) => deps.fileSnapshotStore.getBlob(h);
                         for (const snap of snapshots) {
-                            const r = await fss.importManifest(sessionId, snap.key, new Map(snap.manifest), getBlobA);
+                            const r = await importFaceIdentical.importManifest(sessionId, snap.key, new Map(snap.manifest), getBlobA);
                             if (!r.ok) {
                                 sendError(res, 422, r.error.code === "restore_failed" ? "restore_failed" : "missing_blob", `snapshot import failed (${r.error.code})`);
                                 return;
@@ -451,7 +451,7 @@ async function handleSessionSyncBody(req, res, url, ctx, miss) {
                 // a full getBlob GET-per-hash (under MinIO that would download + re-hash every ≤64 MiB object just to test
                 // presence). Feature-detect hasBlobs; if a store lacks it, fall back to getBlob (parity for older stores).
                 const fss = deps.fileSnapshotStore;
-                const canImportSnapshots = typeof fss?.importManifest === "function";
+                const canImportSnapshots = fileSnapshotImportFace(fss) !== undefined;
                 if (canImportSnapshots) {
                     const distinct = new Set();
                     for (const snap of snapshots)
@@ -518,7 +518,7 @@ async function handleSessionSyncBody(req, res, url, ctx, miss) {
                     return;
                 }
                 const getBlob = (h) => deps.fileSnapshotStore.getBlob(h); // cloud's OWN store
-                const canImportSnapshots = typeof deps.fileSnapshotStore?.importManifest === "function";
+                const importFaceB = fileSnapshotImportFace(deps.fileSnapshotStore);
                 // ── Stream the NDJSON request body → core's StreamingImportValidator per line → batched appendBatch (bounded
                 //    memory: line buffer + batch). The streaming validator IS the single invariant gate (unique ids /
                 //    parent-before-child / structural refs / one-root / leaf-resolvable) — core 1.143.0 — so the service
@@ -650,8 +650,8 @@ async function handleSessionSyncBody(req, res, url, ctx, miss) {
                     //    fail-closed 422 (a blob the Phase-A presence check couldn't catch — corrupted in transit). Note: the
                     //    ENTRIES are already committed (the swap), so a snapshot failure here means the conversation synced but a
                     //    file tree did not — we surface 422 so the client re-PUTs the blob and re-POSTs (idempotent).
-                    if (canImportSnapshots) {
-                        const importManifest = deps.fileSnapshotStore.importManifest.bind(deps.fileSnapshotStore);
+                    if (importFaceB) {
+                        const importManifest = importFaceB.importManifest;
                         for (const snap of pending.snapshots) {
                             const r = await importManifest(sessionId, snap.key, new Map(snap.manifest), getBlob);
                             if (!r.ok) {

package/dist/http/server.d.ts

@@ -25,6 +25,8 @@ import type { QuotaTracker } from "../observability/cost-quota.js";
 import type { ModelUsageTracker, PromptManifestTracker } from "../budget.js";
 import { scopedIdempotencyKey } from "./idempotency.js";
 export { scopedIdempotencyKey };
+import { clampVerifyRounds } from "./verify-rounds.js";
+export { clampVerifyRounds };
 import { streamApprovals, isQuestionAnswer } from "./routes/approvals-assistant.js";
 export { streamApprovals, isQuestionAnswer };
 import { cascadeConfig } from "./run-meta.js";
@@ -451,8 +453,6 @@ export declare const MAX_SYSTEM_PROMPT_CHARS = 16384;
 export declare const MAX_OUTPUT_SCHEMA_CHARS = 32768;
 /** Validate `body.skills` (caps + shape). Returns an error string (→ 400) or null when acceptable. */
 export declare function validateUserSkills(skills: unknown): string | null;
-/** Verification rounds requested by a caller, clamped to a safe [1,5] (default 2). */
-export declare function clampVerifyRounds(v: unknown): number;
 /**
  * Managed-Agents-style HTTP/SSE service surface.
  *   GET  /health

package/dist/http/server.js

@@ -5,7 +5,7 @@ import { uuidv7, isThinkingLevel, expandTiers, resumeWithVerification, Checkpoin
 import { decideParkedAgent, findParkedAgentForCheckpoint } from "../parked-decide.js";
 import { matchCatalogModel } from "../model-select.js";
 import {} from "../config-center/facade.js";
-import { HttpError, principalFrom, verifiedPrincipal, setSsoPrincipal, ssoVerifiedPrincipal, setSsoScope, isUuidV7, verifyDirectDoorProof, isDestructiveSessionWrite } from "../security.js";
+import { HttpError, principalFrom, verifiedPrincipal, setSsoPrincipal, ssoVerifiedPrincipal, setSsoScope, isUuidV7, verifyDirectDoorProof, isDestructiveSessionWrite, decodeCheckpointScope, CHECKPOINT_PUBLIC_SCOPE } from "../security.js";
 import {} from "../memory-sync.js";
 import { MAX_SETTINGS_OUTPUT_STYLE_CHARS, MAX_SETTINGS_PERMISSION_RULES, MAX_SETTINGS_ENV_VARS, MAX_SETTINGS_ENV_KEY_CHARS, MAX_SETTINGS_ENV_VALUE_CHARS } from "../task-settings.js";
 import { parseHooksConfig } from "../hooks/hook-runner.js";
@@ -24,6 +24,8 @@ import { redactSecrets } from "../trace/redact.js";
 import { IdempotencyCache, scopedIdempotencyKey } from "./idempotency.js";
 export { scopedIdempotencyKey };
 import { streamSseLog } from "./sse-log.js";
+import { clampVerifyRounds, verifyRoundsFromBody } from "./verify-rounds.js"; // design/97 R9: the shape's neutral leaf (route-ctx.ts type-imports VerifyRoundsSpec from here, not from this file)
+export { clampVerifyRounds }; // deep-path test imports of http/server.js's clampVerifyRounds keep working unchanged
 import { handleCapabilities } from "./routes/capabilities.js";
 import { handleObservability } from "./routes/observability.js";
 import { handleMemoryPolicy } from "./routes/memory-policy.js";
@@ -88,11 +90,6 @@ export function validateUserSkills(skills) {
     }
     return null;
 }
-/** Verification rounds requested by a caller, clamped to a safe [1,5] (default 2). */
-export function clampVerifyRounds(v) {
-    const n = typeof v === "number" && Number.isFinite(v) ? Math.floor(v) : 2;
-    return Math.min(5, Math.max(1, n));
-}
 const MAX_BODY = 8 * 1024 * 1024;
 /** Caps on `body.images`: inline base64 `data` is otherwise passed RAW to the
  *  spec (URL images are SSRF+size-gated by core, inline aren't). The whole JSON body is already ≤ MAX_BODY, but with NO
@@ -1067,12 +1064,7 @@ export function createHttpServer(rawDeps) {
         }
         // 历史复审轴A #3(1.254):verify 环补 cost 顶——cascade 腿一直映 costCeilingMicroUsd,verify 腿漏了
         // (每轮独立 runTask,总花费此前仅受 maxRounds 约束);同源 body.maxCostUsd,同换算。
-        const verify = body.verify === true
-            ? {
-                maxRounds: clampVerifyRounds(body.verifyRounds),
-                ...(typeof body.maxCostUsd === "number" && body.maxCostUsd > 0 ? { costCeilingMicroUsd: Math.round(body.maxCostUsd * 1e6) } : {}),
-            }
-            : undefined;
+        const verify = verifyRoundsFromBody(body);
         const cascade = body.cascade === true;
         if (cascade && verify) {
             sendError(res, 400, "request.field_conflict", "verify and cascade are mutually exclusive (verify = adversarial gate; cascade = cheap→strong ladder)");
@@ -1251,7 +1243,7 @@ export function createHttpServer(rawDeps) {
         if (!ctx)
             return { status: 409, body: { error: "resume context missing — cannot rebuild task config", errorCode: "conflict.resume_context_unavailable" } };
         // Rebuild taskConfig via resolveSpec with auth reconstructed from the checkpoint (sessionId + scope).
-        const auth = { sessionId: cp.sessionId, principal: cp.scope === "_" ? undefined : cp.scope, memoryScope: ctx.memoryScope };
+        const auth = { sessionId: cp.sessionId, principal: decodeCheckpointScope(cp.scope), memoryScope: ctx.memoryScope };
         // E18: STRIP resumeAt before re-resolving on a durable resume — the leaf is already set by the checkpoint, and
         // resumeAt + a durable resume is rejected by core (resume_at.conflicts_resume); also avoids re-resolving a stale
         // anchor (which could 404 if the session was purged). A resume-at run that suspended stored its body with resumeAt.
@@ -1354,13 +1346,7 @@ export function createHttpServer(rawDeps) {
         // completion — a plain resumeStream would silently drop the gate. The flag rides in the persisted ctx.body
         // (same source the spec was rebuilt from). Like first-run verify it's multi-attempt (not a live stream), so
         // we await the result + write a single terminal event rather than streaming post-resume deltas.
-        const verifyRounds = ctx.body.verify === true
-            ? {
-                maxRounds: clampVerifyRounds(ctx.body.verifyRounds),
-                // 快审 F1:resume 腿同样带 cost 顶(persisted body 的 maxCostUsd 同源;cascade 腿同换算)
-                ...(typeof ctx.body.maxCostUsd === "number" && ctx.body.maxCostUsd > 0 ? { costCeilingMicroUsd: Math.round(ctx.body.maxCostUsd * 1e6) } : {}),
-            }
-            : undefined;
+        const verifyRounds = verifyRoundsFromBody(ctx.body);
         // taskId up-front: the resumed leg streams its post-resume events into the SAME durable run log, CONTINUING
         // the seq past the suspend (core 1.70 `resumeStream`) — so GET /v1/runs/:id/events covers post-resume too,
         // observability parity with runInBackground (closed by core 1.70).
@@ -2029,7 +2015,7 @@ export function createHttpServer(rawDeps) {
         if (!ctx)
             return { status: 409, body: { error: "resume context missing — cannot rebuild task config", errorCode: "conflict.resume_context_unavailable" } };
         // Rebuild taskConfig via resolveSpec with auth reconstructed from the checkpoint scope (mirrors resumeCheckpoint).
-        const auth = { sessionId: cp.sessionId, principal: cp.scope === "_" ? undefined : cp.scope, memoryScope: ctx.memoryScope };
+        const auth = { sessionId: cp.sessionId, principal: decodeCheckpointScope(cp.scope), memoryScope: ctx.memoryScope };
         // E18: STRIP resumeAt before re-resolving on a durable resume — the leaf is already set by the checkpoint, and
         // resumeAt + a durable resume is rejected by core (resume_at.conflicts_resume); also avoids re-resolving a stale
         // anchor (which could 404 if the session was purged). A resume-at run that suspended stored its body with resumeAt.
@@ -2037,13 +2023,7 @@ export function createHttpServer(rawDeps) {
         const { objective: resumeObjective, sessionId: _sessionId, ...taskConfig } = spec;
         // A resource-suspended task that was submitted with verify:true is re-gated on completion (parity with the
         // HITL path — the flag rides the persisted ctx.body).
-        const verifyRounds = ctx.body.verify === true
-            ? {
-                maxRounds: clampVerifyRounds(ctx.body.verifyRounds),
-                // 快审 F1:resume 腿同样带 cost 顶(persisted body 的 maxCostUsd 同源;cascade 腿同换算)
-                ...(typeof ctx.body.maxCostUsd === "number" && ctx.body.maxCostUsd > 0 ? { costCeilingMicroUsd: Math.round(ctx.body.maxCostUsd * 1e6) } : {}),
-            }
-            : undefined;
+        const verifyRounds = verifyRoundsFromBody(ctx.body);
         return driveResumeIntoRunLog({ token, sessionId: cp.sessionId, principal: auth.principal, fleetScope: resumeFleetScope(req, auth), taskConfig, resumeObjective, outcome: { gate: "resource_limit", decision: "continue" }, verifyRounds });
     }
     /** design/144 §3:wake 一个 task_done 纯 park——非门决策,解除 park 消费消息续跑。owner 门:非 operator
@@ -2058,7 +2038,8 @@ export function createHttpServer(rawDeps) {
         const operator = explicitOperatorOk(caller, deps.config.operatorPrincipals);
         if (!operator) {
             const scope = await cs.peekPendingScope(sessionId).catch(() => undefined);
-            if (scope !== null && scope !== undefined && scope !== "_" && scope !== caller) {
+            const decodedScope = scope != null ? decodeCheckpointScope(scope) : undefined;
+            if (decodedScope !== undefined && decodedScope !== caller) {
                 return { status: 404, body: { error: "no parked checkpoint for this session (nothing to wake)", errorCode: "not_found.parked_checkpoint" } }; // 无 oracle
             }
         }
@@ -2071,8 +2052,11 @@ export function createHttpServer(rawDeps) {
         }
         if (!cp)
             return { status: 404, body: { error: "checkpoint not found", errorCode: "not_found.checkpoint" } };
-        if (!operator && cp.scope !== "_" && cp.scope !== caller) {
-            return { status: 404, body: { error: "no parked checkpoint for this session (nothing to wake)", errorCode: "not_found.parked_checkpoint" } }; // 纵深(peek 缺席面兜底)
+        // 纵深(peek 缺席面兜底)。比较留在 scope 空间(常量比较,不 decode):行体可能来自不做形状校验的
+        // JSON 读取,scope 越契约为 nullish 时 decode 形会把「畸形行」折成「公开」= 放行;旧码对该支是拒绝
+        // 方向,常量形逐字节保持它(codex 码审 finding,#97 α 车)。
+        if (!operator && cp.scope !== CHECKPOINT_PUBLIC_SCOPE && cp.scope !== caller) {
+            return { status: 404, body: { error: "no parked checkpoint for this session (nothing to wake)", errorCode: "not_found.parked_checkpoint" } };
         }
         // 预检(core 兜底同码):非纯 park = 有未决门,wake 永不绕审批。
         const gateKind = cp.gate?.kind;
@@ -2094,7 +2078,7 @@ export function createHttpServer(rawDeps) {
         const ctx = await cs.getCtx(sessionId).catch(() => null);
         if (!ctx)
             return { status: 409, body: { error: "resume context missing — cannot rebuild task config", errorCode: "conflict.resume_context_unavailable" } };
-        const auth = { sessionId: cp.sessionId, principal: cp.scope === "_" ? undefined : cp.scope, memoryScope: ctx.memoryScope };
+        const auth = { sessionId: cp.sessionId, principal: decodeCheckpointScope(cp.scope), memoryScope: ctx.memoryScope };
         const spec = await deps.resolveSpec({ ...ctx.body, resumeAt: undefined }, req, auth);
         const { objective: resumeObjective, sessionId: _sessionId, ...taskConfig } = spec;
         return driveResumeIntoRunLog({
@@ -2148,7 +2132,7 @@ export function createHttpServer(rawDeps) {
         if (!ctx)
             return { status: 409, body: { error: "resume context missing — cannot rebuild task config", errorCode: "conflict.resume_context_unavailable" } };
         // Rebuild taskConfig via resolveSpec with auth reconstructed from the checkpoint scope (mirrors resumeCheckpoint).
-        const auth = { sessionId: cp.sessionId, principal: cp.scope === "_" ? undefined : cp.scope, memoryScope: ctx.memoryScope };
+        const auth = { sessionId: cp.sessionId, principal: decodeCheckpointScope(cp.scope), memoryScope: ctx.memoryScope };
         // E18: STRIP resumeAt before re-resolving on a durable resume — the leaf is already set by the checkpoint, and
         // resumeAt + a durable resume is rejected by core (resume_at.conflicts_resume); also avoids re-resolving a stale
         // anchor (which could 404 if the session was purged). A resume-at run that suspended stored its body with resumeAt.
@@ -2156,13 +2140,7 @@ export function createHttpServer(rawDeps) {
         const { objective: resumeObjective, sessionId: _sessionId, ...taskConfig } = spec;
         // A plan_review-suspended task submitted with verify:true is re-gated on completion (parity with the other
         // resume paths — the flag rides the persisted ctx.body).
-        const verifyRounds = ctx.body.verify === true
-            ? {
-                maxRounds: clampVerifyRounds(ctx.body.verifyRounds),
-                // 快审 F1:resume 腿同样带 cost 顶(persisted body 的 maxCostUsd 同源;cascade 腿同换算)
-                ...(typeof ctx.body.maxCostUsd === "number" && ctx.body.maxCostUsd > 0 ? { costCeilingMicroUsd: Math.round(ctx.body.maxCostUsd * 1e6) } : {}),
-            }
-            : undefined;
+        const verifyRounds = verifyRoundsFromBody(ctx.body);
         const outcome = {
             gate: "plan_review",
             decision,

package/dist/http/verify-rounds.d.ts

@@ -0,0 +1,24 @@
+/**
+ * design/97 R9 — the verify-rounds shape (used by the developer-mode adversarial-verification gate, 1.44) pulled
+ * out to a NEUTRAL LEAF: it was three copies of the same anonymous `{ maxRounds: number; costCeilingMicroUsd?:
+ * number }` object type (route-ctx.ts ×2, runs.ts `runInBackground`'s public signature) plus four call sites in
+ * http/server.ts that each re-derived the same "verify:true → clamp rounds + fold cost ceiling" expression from a
+ * request body. A leaf (not server.ts itself) so route-ctx.ts — which must never value-import server.ts (that
+ * closes the runtime module-load cycle test/module-cycle-gate.test.ts guards) — can `import type` the shape from
+ * one place. server.ts imports {@link clampVerifyRounds} from here and RE-EXPORTS it (deep-path test imports of
+ * `http/server.js`'s `clampVerifyRounds` keep working unchanged).
+ */
+import type { TaskRequestBody } from "./wire-types.js";
+/** Verification-rounds config threaded onto a task's `verify`/resume paths (see {@link verifyRoundsFromBody}). */
+export interface VerifyRoundsSpec {
+    maxRounds: number;
+    costCeilingMicroUsd?: number;
+}
+/** Verification rounds requested by a caller, clamped to a safe [1,5] (default 2). */
+export declare function clampVerifyRounds(v: unknown): number;
+/** `undefined` when `body.verify` is not `true` (the caller didn't opt into the gate); otherwise the clamped
+ *  rounds + (if `maxCostUsd` is a positive number) the same USD→micro-USD cost ceiling the cascade lane uses.
+ *  Same expression that lived inline at all four verify/resume call sites in http/server.ts (fresh-submit,
+ *  resumeCheckpoint, resumePreempted, resumePlanReview) — collected here VERBATIM (design/97 R9). */
+export declare function verifyRoundsFromBody(body: Pick<TaskRequestBody, "verify" | "verifyRounds" | "maxCostUsd">): VerifyRoundsSpec | undefined;
+//# sourceMappingURL=verify-rounds.d.ts.map

package/dist/http/verify-rounds.js

@@ -0,0 +1,18 @@
+/** Verification rounds requested by a caller, clamped to a safe [1,5] (default 2). */
+export function clampVerifyRounds(v) {
+    const n = typeof v === "number" && Number.isFinite(v) ? Math.floor(v) : 2;
+    return Math.min(5, Math.max(1, n));
+}
+/** `undefined` when `body.verify` is not `true` (the caller didn't opt into the gate); otherwise the clamped
+ *  rounds + (if `maxCostUsd` is a positive number) the same USD→micro-USD cost ceiling the cascade lane uses.
+ *  Same expression that lived inline at all four verify/resume call sites in http/server.ts (fresh-submit,
+ *  resumeCheckpoint, resumePreempted, resumePlanReview) — collected here VERBATIM (design/97 R9). */
+export function verifyRoundsFromBody(body) {
+    return body.verify === true
+        ? {
+            maxRounds: clampVerifyRounds(body.verifyRounds),
+            ...(typeof body.maxCostUsd === "number" && body.maxCostUsd > 0 ? { costCeilingMicroUsd: Math.round(body.maxCostUsd * 1e6) } : {}),
+        }
+        : undefined;
+}
+//# sourceMappingURL=verify-rounds.js.map

package/dist/images/bake-validate.d.ts

@@ -15,6 +15,7 @@
  * `bands/` dir). A DRIFT test (test/image-bake-validate.test.ts) asserts they still match — a silently-drifted
  * list would either reject a valid profile or admit a removed band. Keep them in lockstep with the recipes.
  */
+import { SHA256_DIGEST_RE as DIGEST_RE } from "../digest-form.js";
 /**
  * FROZEN profile catalog — mirrored from `e2b-template/dev-sandbox/gen-dockerfile.sh` `profile_bands()`.
  * (db / browser-nodriver are opt-in overlays, NOT in `code-full` — `code-full-db` adds db; per design §4.)
@@ -32,8 +33,10 @@ export declare const FROZEN_BUMP_TOOLS: readonly string[];
 export declare const VER_RE: RegExp;
 /** Belt-only band shape (set-membership is the real gate); a defense-in-depth reject of structurally weird ids. */
 export declare const BAND_SHAPE_RE: RegExp;
-/** A digest must be an immutable sha256 ref (the allow-list check against the index is the real gate, P2.4c). */
-export declare const DIGEST_RE: RegExp;
+/** A digest must be an immutable sha256 ref (the allow-list check against the index is the real gate, P2.4c).
+ *  design/158 R12: the shape itself is collected in `digest-form.ts`'s `SHA256_DIGEST_RE`; `DIGEST_RE` stays a
+ *  re-exported alias (compat — export surface unchanged). */
+export { DIGEST_RE };
 /** The raw, untrusted submit body fields this module validates (operator free-text). */
 export interface BakeSubmit {
     profile?: unknown;

package/dist/images/bake-validate.js

@@ -15,6 +15,7 @@
  * `bands/` dir). A DRIFT test (test/image-bake-validate.test.ts) asserts they still match — a silently-drifted
  * list would either reject a valid profile or admit a removed band. Keep them in lockstep with the recipes.
  */
+import { SHA256_DIGEST_RE as DIGEST_RE } from "../digest-form.js";
 /**
  * FROZEN profile catalog — mirrored from `e2b-template/dev-sandbox/gen-dockerfile.sh` `profile_bands()`.
  * (db / browser-nodriver are opt-in overlays, NOT in `code-full` — `code-full-db` adds db; per design §4.)
@@ -89,8 +90,10 @@ const BUMP_TOOL_SET = new Set(FROZEN_BUMP_TOOLS);
 export const VER_RE = /^[A-Za-z0-9._-]{1,40}$/;
 /** Belt-only band shape (set-membership is the real gate); a defense-in-depth reject of structurally weird ids. */
 export const BAND_SHAPE_RE = /^[a-z0-9-]+$/;
-/** A digest must be an immutable sha256 ref (the allow-list check against the index is the real gate, P2.4c). */
-export const DIGEST_RE = /^sha256:[a-f0-9]{64}$/;
+/** A digest must be an immutable sha256 ref (the allow-list check against the index is the real gate, P2.4c).
+ *  design/158 R12: the shape itself is collected in `digest-form.ts`'s `SHA256_DIGEST_RE`; `DIGEST_RE` stays a
+ *  re-exported alias (compat — export surface unchanged). */
+export { DIGEST_RE };
 function reject(status, error, conflictBands) {
     return conflictBands ? { ok: false, status, error, conflictBands } : { ok: false, status, error };
 }

package/dist/index.d.ts

@@ -5,6 +5,7 @@ export { createStoreBackend, type StoreBackend } from "./plugins/store-backend.j
 export { CachingSessionStore, type CachingOptions } from "./plugins/caching-session-store.js";
 export type { RunRecord, RunEvent } from "./plugins/store-contracts.js";
 export { runInBackground } from "./runs.js";
+export type { VerifyRoundsSpec } from "./http/verify-rounds.js";
 export { type ApprovalRow, type ApprovalStatus } from "./plugins/approval-store-sql.js";
 export { createOaApprovalPolicy, type OaApprovalOptions } from "./approval.js";
 export { createHardenedVmRunner, runInHardenedVm, type HardenedVmLimits, type HardenedMembrane } from "./orchestration/hardened-vm-runner.js";

package/dist/leader/grader-env-factory.js

@@ -24,8 +24,7 @@
  * `LEADER_REPAIR_LOOP` / `LEADER_MEASURE_GATES` / `LEADER_GRADER_FACTORY`.
  */
 import { runExecGate } from "@sema-agent/core";
-/** Single-quote a string for safe interpolation into a shell command (mirrors `repair-oracle.ts` / `merge.ts`). */
-const sq = (s) => `'${s.replace(/'/g, "'\\''")}'`;
+import { shellQuote as sq } from "../plugins/remote-shell.js";
 /**
  * §10.1/§10.4 — HERMETIC apply-and-grade. Reset the grader to its clean `integBase` (`git reset --hard` +
  * `git clean -fdx`), apply the FULL `base→latest` `patch` (never cumulative onto an already-applied tree), then

package/dist/leader/merge.js

@@ -1,6 +1,6 @@
 import { delimitUntrusted } from "@sema-agent/core";
 import { applyAndGrade, changedFilesOutOfAllowlist } from "./grader-env-factory.js";
-const Q = (s) => `'${s.replace(/'/g, "'\\''")}'`; // single-quote for shell safety
+import { shellQuote as Q } from "../plugins/remote-shell.js";
 /** Integrate completed workers' branches. Never throws — failures are typed MergeResult. */
 export async function mergeBranches(reports, baseSha, deps) {
     const repo = deps.repoDir ?? "/repo";

package/dist/leader/repair-oracle.js

@@ -28,8 +28,7 @@
  */
 import { runExecGate, } from "@sema-agent/core";
 import { createHash } from "node:crypto";
-/** Single-quote a string for safe interpolation into a shell command. */
-const sq = (s) => `'${s.replace(/'/g, "'\\''")}'`;
+import { shellQuote as sq } from "../plugins/remote-shell.js";
 /** A short, stable content hash for the stale-diff guard (fork2.1) + the graded-bytes binding (fork2.2). */
 const sha = (s) => createHash("sha256").update(s).digest("hex").slice(0, 16);
 /** Parse the changed file paths from a unified diff — the `diff --git a/X b/X` headers (both old + new path). */

package/dist/per-task-image.d.ts

@@ -1,17 +1,3 @@
-/**
- * §7 P0.5 — per-task sandbox image binding (門B "用户按需选像"). IMAGE-API-DESIGN §7.
- *
- * The caller sends a PROFILE (intent) on the run body — NEVER a digest. The trusted control plane (this service,
- * with the caller's principal) resolves the profile → a pullable `repo@digest`, FAIL-CLOSED, re-admitting by the
- * SAME per-principal visibility the `/v1/images/select` admission uses. Why profile-not-digest: a digest is a
- * stable, enumerable sha256 with no caller-binding — trusting a caller-supplied digest is fail-OPEN (a user could
- * pass another tenant's digest to pull an image they can't see). Resolving inside the trust boundary closes that.
- *
- * The resolved ref reaches the worker-global {@link import("@sema-agent/core").ExecutionEnvFactory} (which
- * only receives core's deliberately-minimal `{sessionId}` context) via {@link PerTaskImageRegistry} — core's own
- * doctrine: "richer routing is captured in the factory closure by the trusted control plane". This module is that
- * capture, kept narrow + unit-testable.
- */
 import type { ImageViewer, ImageIndexEntry } from "./plugins/store-contracts.js";
 /** Minimal slice of the image index the per-task resolver needs (a testable seam — the real `imageIndex`'s
  *  `latestPublished` returns the full {@link ImageIndexEntry}, which is assignable to this Pick). */
@@ -67,8 +53,7 @@ export declare function resolveSandboxImageRef(opts: {
  * tracked as a follow-up. cascade/verify + a profile are rejected up front (they strip/replace the session).
  */
 export declare class PerTaskImageRegistry {
-    private readonly maxEntries;
-    private readonly map;
+    private readonly bounded;
     constructor(maxEntries?: number);
     /** Register the resolved `repo@digest` for a session. A re-set (resume / a later same-session task) overwrites;
      *  on overflow the oldest insertion is evicted so an orphaned entry (a resolveSpec not followed by a factory

package/dist/per-task-image.js

@@ -1,3 +1,18 @@
+/**
+ * §7 P0.5 — per-task sandbox image binding (門B "用户按需选像"). IMAGE-API-DESIGN §7.
+ *
+ * The caller sends a PROFILE (intent) on the run body — NEVER a digest. The trusted control plane (this service,
+ * with the caller's principal) resolves the profile → a pullable `repo@digest`, FAIL-CLOSED, re-admitting by the
+ * SAME per-principal visibility the `/v1/images/select` admission uses. Why profile-not-digest: a digest is a
+ * stable, enumerable sha256 with no caller-binding — trusting a caller-supplied digest is fail-OPEN (a user could
+ * pass another tenant's digest to pull an image they can't see). Resolving inside the trust boundary closes that.
+ *
+ * The resolved ref reaches the worker-global {@link import("@sema-agent/core").ExecutionEnvFactory} (which
+ * only receives core's deliberately-minimal `{sessionId}` context) via {@link PerTaskImageRegistry} — core's own
+ * doctrine: "richer routing is captured in the factory closure by the trusted control plane". This module is that
+ * capture, kept narrow + unit-testable.
+ */
+import { BoundedSessionMap } from "./bounded-session-map.js";
 /** Boolean capability keys a caller may require. `nestedBuildMode` is a posture string, not a boolean gate, so it
  *  is intentionally NOT requestable here (capability admission is allow-on-true only). */
 const REQUESTABLE_CAPS = new Set(["browser", "db", "nestedBuild"]);
@@ -52,27 +67,22 @@ export async function resolveSandboxImageRef(opts) {
  * tracked as a follow-up. cascade/verify + a profile are rejected up front (they strip/replace the session).
  */
 export class PerTaskImageRegistry {
-    maxEntries;
-    map = new Map();
+    // #97 R11: the sessionId-keyed bounded-eviction map is the shared BoundedSessionMap basis (this class was
+    // its original verbatim form); the composition below keeps THIS class's own ctor/method surface unchanged.
+    bounded;
     constructor(maxEntries = 4096) {
-        this.maxEntries = maxEntries;
+        this.bounded = new BoundedSessionMap(maxEntries);
     }
     /** Register the resolved `repo@digest` for a session. A re-set (resume / a later same-session task) overwrites;
      *  on overflow the oldest insertion is evicted so an orphaned entry (a resolveSpec not followed by a factory
      *  call, e.g. a rejected/pre-exec-failed request) stays bounded. */
     set(sessionId, ref) {
-        this.map.delete(sessionId);
-        this.map.set(sessionId, ref);
-        if (this.map.size > this.maxEntries) {
-            const oldest = this.map.keys().next().value;
-            if (oldest !== undefined)
-                this.map.delete(oldest);
-        }
+        this.bounded.set(sessionId, ref);
     }
     /** Read the ref for a session (NON-removing — the factory may be invoked more than once per logical task).
      *  `undefined` ⇒ no per-task image for this session ⇒ the factory uses its worker-global default image. */
     get(sessionId) {
-        return sessionId === undefined ? undefined : this.map.get(sessionId);
+        return this.bounded.get(sessionId);
     }
 }
 //# sourceMappingURL=per-task-image.js.map

package/dist/plugins/approval-store-sql.js

@@ -1,6 +1,5 @@
 import { parseJsonStrict as parseJson, toIsoOrNull as iso } from "./sql-row-helpers.js";
-import { pgProtocolJsonStringify } from "./pg-safe-json.js";
-import { mysqlDriver, pgDriver } from "./sql-driver.js";
+import { mysqlDriver, pgDriver, dialectProtocolJsonEncoder } from "./sql-driver.js";
 /** PG translation of the `approval` DDL in tidb-pool.ts SCHEMA_STATEMENTS (JSON→JSONB, DATETIME(3)→TIMESTAMPTZ(3),
  *  inline KEY→separate CREATE INDEX).
  *
@@ -48,7 +47,7 @@ export class SqlApprovalStore {
      *  (codex R4-H2 — the approval `args` is the operator's review surface and must agree with the
      *  policy-executed args at the NUL position). */
     json(value, label) {
-        return this.db.dialect === "tidb" ? JSON.stringify(value) : pgProtocolJsonStringify(value, label);
+        return dialectProtocolJsonEncoder(this.db.dialect)(value, label);
     }
     async createPending(id, scope, ctx) {
         await this.db.query(this.q("INSERT INTO approval (id, task_id, session_id, owner, scope, tool_name, args, status, created_at) " +

package/dist/plugins/checkpoint-store-sql.js

@@ -29,9 +29,8 @@
 import { createHash } from "node:crypto";
 import { CheckpointError, validatePendingSteer, checkpointVersionOf, winnerFromOutcome, summarizeCheckpoint, MAX_SUPPORTED_CHECKPOINT_VERSION, } from "@sema-agent/core";
 import { redactDeep } from "../trace/redact.js";
-import { pgProtocolJsonStringify } from "./pg-safe-json.js";
 import { parseJsonStrict as parseJson } from "./sql-row-helpers.js";
-import { mysqlDriver, pgDriver } from "./sql-driver.js";
+import { mysqlDriver, pgDriver, dialectProtocolJsonEncoder } from "./sql-driver.js";
 /** Cap the persisted/served pending-approval args so a pathological tool payload can't bloat the checkpoint row
  *  or the operator-queue response (the BFF renders this in an approval card; a few KB is plenty). */
 const MAX_TOOL_INPUT_CHARS = 8192;
@@ -94,7 +93,7 @@ export class SqlCheckpointStore {
     /** JSON column binding: TiDB stores the string verbatim; PG goes through the LOSSLESS protocol envelope
      *  (R4-H1 — the operator's review surface must agree with the executed args at the NUL position). */
     json(value, label) {
-        return this.db.dialect === "tidb" ? JSON.stringify(value) : pgProtocolJsonStringify(value, label);
+        return dialectProtocolJsonEncoder(this.db.dialect)(value, label);
     }
     isDupKey(e) {
         return this.db.dialect === "tidb"

package/dist/plugins/image-bake-store-sql.js

@@ -37,9 +37,9 @@
  */
 import { uuidv7 } from "@sema-agent/core";
 import { randomBytes } from "node:crypto";
-import { pgSanitizeText, pgSafeJsonStringify, pgHasUnstorable } from "./pg-safe-json.js";
+import { pgSanitizeText, pgHasUnstorable } from "./pg-safe-json.js";
 import { parseJsonOr as parseJson, toIso as iso } from "./sql-row-helpers.js";
-import { mysqlDriver, pgDriver } from "./sql-driver.js";
+import { mysqlDriver, pgDriver, dialectJsonEncoder } from "./sql-driver.js";
 import { mapBakeRow as mapRow, BAKE_SELECT_COLS as SELECT_COLS, } from "./store-contracts.js";
 /** PG translation of the image_bake / image_bake_event / image_bake_lease DDL in tidb-pool.ts SCHEMA_STATEMENTS
  *  (JSON→JSONB, TINYINT→SMALLINT, DATETIME(3)→TIMESTAMPTZ(3), inline UNIQUE/KEY→named CONSTRAINT + CREATE INDEX).
@@ -440,7 +440,7 @@ export class SqlImageBake {
             return null; // fast dedupe pre-check
         // PG-only: codex R14 — a `done` frame carrying a NUL in its error text would raise 22P05 and be LOST FOREVER
         // (the terminal flip already cleared the ingest secret, so it cannot be retried). TiDB stores JSON verbatim.
-        const payload = data == null ? null : this.db.dialect === "tidb" ? JSON.stringify(data) : pgSafeJsonStringify(data);
+        const payload = data == null ? null : dialectJsonEncoder(this.db.dialect)(data);
         // The PK race is a thundering-herd: K concurrent writers all read the same maxSeq, ONE wins the (bake_id,seq)
         // INSERT, the rest re-read and retry — so the unluckiest writer can lose up to ~K races in a row. A small fixed
         // cap (6) under-serves a realistic ingest burst and would THROW a frame that is merely contended, not lost.

package/dist/plugins/outcome-ledger-sql.js

@@ -30,8 +30,7 @@
  * (test/pg-outcome-ledger-integration.test.ts, both engines run the SAME scenarios in parallel).
  */
 import { randomUUID, createHash } from "node:crypto";
-import { pgSafeJsonStringify } from "./pg-safe-json.js";
-import { mysqlDriver, pgDriver } from "./sql-driver.js";
+import { mysqlDriver, pgDriver, dialectJsonEncoder } from "./sql-driver.js";
 /**
  * v1 task-signature (council Q11, recommended candidate (a)): a deterministic structural hash — zero
  * embedder, coarse on purpose (routing is a coarse decision). An explicit `tag` short-circuits to the
@@ -163,7 +162,7 @@ export class SqlOutcomeLedger {
      *  store's blobs are observability/dashboard data, so the lossy (U+FFFD) sanitize is the right tier
      *  (not the lossless envelope checkpoint-store-sql.ts uses for the approval trust boundary). */
     json(value) {
-        return this.db.dialect === "tidb" ? JSON.stringify(value) : pgSafeJsonStringify(value);
+        return dialectJsonEncoder(this.db.dialect)(value);
     }
     /** Record one graded task run. Idempotent only by row id; callers pass distinct runs. */
     async record(o) {

package/dist/plugins/remote-env-e2b.js

@@ -23,7 +23,7 @@ import path from "node:path";
 import { Sandbox, CommandExitError, FileType } from "e2b";
 import { FileError, ExecutionError, RemoteExecutionError, RollingTailBuffer, markTruncated, } from "@sema-agent/core";
 import { fileErrorFromExec } from "./remote-env-file-error.js";
-import { numEnvOr } from "./remote-shell.js";
+import { numEnvOr, shellQuote } from "./remote-shell.js";
 import { BackgroundShellManager } from "./background-shell-support.js";
 const PROVIDER = "e2b";
 /** E2B default sandbox user home — the workspace root unless overridden. */
@@ -1264,10 +1264,6 @@ function anySignal(signals) {
     }
     return { signal: ctrl.signal, dispose: () => cleanups.forEach((c) => c()) };
 }
-/** POSIX single-quote a string for safe shell interpolation. */
-function shellQuote(s) {
-    return `'${s.replace(/'/g, `'\\''`)}'`;
-}
 /** Copy a Uint8Array's exact bytes into a standalone ArrayBuffer (E2B write accepts ArrayBuffer). */
 function toArrayBuffer(u) {
     return u.buffer.slice(u.byteOffset, u.byteOffset + u.byteLength);

package/dist/plugins/remote-shell.d.ts

@@ -22,7 +22,8 @@ export declare const EXEC_FORCE_SETTLE_GRACE_MS = 3000;
  * any promise (the buffered exec already settled synchronously on abort/timeout — that path is unchanged).
  */
 export declare function armPipeDestroyGrace(child: ChildProcess): ReturnType<typeof setTimeout>;
-/** POSIX single-quote a string for safe interpolation into a remote shell command. */
+/** POSIX single-quote a string for safe interpolation into a remote shell command (the only metacharacter
+ *  inside '' is ' itself, closed/escaped/reopened). */
 export declare function shellQuote(s: string): string;
 /** Derive FileInfo kind from POSIX st_mode bits (raw stat/readdir attrs carry no isDirectory() helper). */
 export declare function kindFromMode(mode?: number): FileInfo["kind"];

package/dist/plugins/remote-shell.js

@@ -28,7 +28,8 @@ export function armPipeDestroyGrace(child) {
     t.unref?.();
     return t;
 }
-/** POSIX single-quote a string for safe interpolation into a remote shell command. */
+/** POSIX single-quote a string for safe interpolation into a remote shell command (the only metacharacter
+ *  inside '' is ' itself, closed/escaped/reopened). */
 export function shellQuote(s) {
     return `'${s.replace(/'/g, `'\\''`)}'`;
 }

package/dist/plugins/run-store-sql.js

@@ -1,8 +1,8 @@
 import { projectUsageStats, USAGE_SCAN_LIMIT } from "../usage-analytics.js";
 import { escapeLike } from "./sql-escape.js";
-import { pgSafeJsonStringify, pgSanitizeText } from "./pg-safe-json.js";
+import { pgSanitizeText } from "./pg-safe-json.js";
 import { parseJsonLenient as parseJson, toIso as iso } from "./sql-row-helpers.js";
-import { mysqlDriver, pgDriver } from "./sql-driver.js";
+import { mysqlDriver, pgDriver, dialectJsonEncoder } from "./sql-driver.js";
 /** Dual-dialect async run registry + event log. See the file header for the dialect-delta ledger. */
 export class SqlRunStore {
     db;
@@ -21,7 +21,7 @@ export class SqlRunStore {
     /** JSON column binding: TiDB stores the string verbatim; PG goes through the protocol-safe envelope
      *  (a raw NUL byte in an event payload would otherwise throw 22P05 mid-write). */
     json(value) {
-        return this.db.dialect === "tidb" ? JSON.stringify(value) : pgSafeJsonStringify(value);
+        return dialectJsonEncoder(this.db.dialect)(value);
     }
     /** Run statements atomically; rolls back on failure. */
     async tx(fn) {