@sema-agent/server 7.133.0 → 7.134.0

package/dist/http/checkpoint-ctx.js

@@ -12,8 +12,8 @@ export function bodyCarriesAllowList(body) {
     const allow = permissions["allow"];
     return Array.isArray(allow) && allow.length > 0;
 }
-export function buildCheckpointCtx(fields) {
-    return {
+export function buildCheckpointCtx(fields, sealer, sessionId) {
+    const ctx = {
         body: fields.body,
         writerVersion: fields.writerVersion,
         ...(fields.memoryScope !== undefined ? { memoryScope: fields.memoryScope } : {}),
@@ -21,6 +21,7 @@ export function buildCheckpointCtx(fields) {
         ...(bodyCarriesAllowList(fields.body) ? { permissionsAllowReading: "allow_layer" } : {}),
         permissionModeReading: "entry_word",
     };
+    return sealCheckpointCtx(ctx, sealer, sessionId);
 }
 export function withPermissionModeRewritten(ctx, body) {
     return { ...ctx, body, permissionModeReading: "entry_word" };
@@ -122,4 +123,159 @@ function storedBodyReplayArmAnswer(refusal, readerVersion) {
         }
     }
 }
+export const CHECKPOINT_CTX_SEAL_ALG = "checkpoint-ctx-sealedbox-v1";
+export const CHECKPOINT_CTX_CREDENTIAL_SLOTS = [
+    { path: ["mcpServers", "*", "transport", "headers"], holds: "map" },
+    { path: ["mcpServers", "*", "transport", "env"], holds: "map" },
+    { path: ["a2aPeers", "*", "headers"], holds: "map" },
+    { path: ["settings", "env"], holds: "map" },
+    { path: ["settings", "webSearch", "apiKey"], holds: "value" },
+    { path: ["settings", "hooks", "*", "*", "hooks", "*", "headers"], holds: "map" },
+];
+export const CHECKPOINT_CTX_UNSEALABLE_REASONS = ["no_key_store", "key_not_held", "unopenable", "plaintext", "unrecognized_seal"];
+export class CheckpointCtxUnsealableError extends Error {
+    field;
+    reason;
+    constructor(field, reason) {
+        super(`checkpoint ctx credential at ${field} cannot be ${reason === "no_key_store" ? "sealed or opened without a sealed-key store" : `opened (${reason})`}`);
+        this.name = "CheckpointCtxUnsealableError";
+        this.field = field;
+        this.reason = reason;
+    }
+}
+function mintSealedCheckpointCtx(sealed) {
+    return sealed;
+}
+export const CHECKPOINT_CTX_SEALING_REQUIRED = "a durable checkpoint store is wired but checkpointCtxSealing is not: suspended tasks keep the request's credentials (MCP / A2A headers and env values, settings.env, settings.webSearch.apiKey, http hook headers) in their resume context, and they are stored sealed or not at all — give the service a sealed-key store for them (this service builds it under <data root>/sealed-key/checkpoint-ctx-keys/ at boot; a failure there is the earlier checkpoint_ctx_sealing_unavailable warning — make that directory creatable and chmod-able by the service, or repair or remove a key file there whose public and private halves do not belong together), or, when embedding, pass checkpointCtxSealing: await ensureCheckpointCtxSealing(sealedKeyDir); refusing to start rather than write credentials in plaintext";
+const isRecord = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+export function isSealedCheckpointValue(v) {
+    if (!isRecord(v))
+        return false;
+    const keys = Object.keys(v);
+    return keys.length === 3 && v["alg"] === CHECKPOINT_CTX_SEAL_ALG && typeof v["publicKeyId"] === "string" && typeof v["sealed"] === "string";
+}
+function defineOwn(target, key, value) {
+    Object.defineProperty(target, key, { value, enumerable: true, writable: true, configurable: true });
+}
+function mapCredentialSlots(body, visit) {
+    let out = body;
+    for (const slot of CHECKPOINT_CTX_CREDENTIAL_SLOTS)
+        out = mapAt(out, slot.path, 0, slot.holds, "", visit);
+    return out;
+}
+function mapAt(node, path, i, holds, field, visit) {
+    if (i === path.length) {
+        if (holds === "value")
+            return visit(node, field);
+        if (!isRecord(node) || isSealedCheckpointValue(node))
+            return visit(node, field);
+        let copy;
+        for (const [k, v] of Object.entries(node)) {
+            const next = visit(v, memberField(field, k));
+            if (next !== v)
+                defineOwn((copy ??= { ...node }), k, next);
+        }
+        return copy ?? node;
+    }
+    const seg = path[i];
+    if (seg === "*") {
+        if (Array.isArray(node)) {
+            let copy;
+            node.forEach((el, idx) => {
+                const next = mapAt(el, path, i + 1, holds, `${field}[${idx}]`, visit);
+                if (next !== el)
+                    (copy ??= [...node])[idx] = next;
+            });
+            return copy ?? node;
+        }
+        if (!isRecord(node))
+            return node;
+        let copy;
+        for (const [k, v] of Object.entries(node)) {
+            const next = mapAt(v, path, i + 1, holds, memberField(field, k), visit);
+            if (next !== v)
+                defineOwn((copy ??= { ...node }), k, next);
+        }
+        return copy ?? node;
+    }
+    if (!isRecord(node) || !Object.hasOwn(node, seg))
+        return node;
+    const child = node[seg];
+    const next = mapAt(child, path, i + 1, holds, memberField(field, seg), visit);
+    if (next === child)
+        return node;
+    const copy = { ...node };
+    defineOwn(copy, seg, next);
+    return copy;
+}
+function memberField(field, key) {
+    return field === "" ? key : `${field}.${key}`;
+}
+function sealBody(body, sealer, sessionId) {
+    let valuesSealed = 0;
+    const sealed = mapCredentialSlots(body, (value, field) => {
+        if (sealer === undefined)
+            throw new CheckpointCtxUnsealableError(field, "no_key_store");
+        valuesSealed += 1;
+        return sealer.seal(value, sessionId);
+    });
+    return { body: sealed, valuesSealed };
+}
+export function sealCheckpointCtx(ctx, sealer, sessionId) {
+    const { body } = sealBody(ctx.body, sealer, sessionId);
+    return mintSealedCheckpointCtx({ ...ctx, body: body, credentialSeal: CHECKPOINT_CTX_SEAL_ALG });
+}
+export function openCheckpointCtx(stored, opener, sessionId) {
+    const { credentialSeal, ...rest } = stored;
+    const stamp = credentialSeal;
+    try {
+        const body = mapCredentialSlots(stored.body, (value, field) => {
+            if (stamp === undefined)
+                throw new CheckpointCtxUnsealableError(field, "plaintext");
+            if (stamp !== CHECKPOINT_CTX_SEAL_ALG)
+                throw new CheckpointCtxUnsealableError(field, "unrecognized_seal");
+            if (isSealedCheckpointValue(value)) {
+                if (opener === undefined)
+                    throw new CheckpointCtxUnsealableError(field, "no_key_store");
+                if (!opener.holds(value.publicKeyId))
+                    throw new CheckpointCtxUnsealableError(field, "key_not_held");
+                try {
+                    return opener.open(value, sessionId);
+                }
+                catch {
+                    throw new CheckpointCtxUnsealableError(field, "unopenable");
+                }
+            }
+            if (isRecord(value) && Object.hasOwn(value, "sealed"))
+                throw new CheckpointCtxUnsealableError(field, "unrecognized_seal");
+            throw new CheckpointCtxUnsealableError(field, "plaintext");
+        });
+        return { kind: "ok", ctx: { ...rest, body: body } };
+    }
+    catch (e) {
+        if (e instanceof CheckpointCtxUnsealableError)
+            return { kind: "unsealable", field: e.field, reason: e.reason };
+        throw e;
+    }
+}
+export function sealedCredentialFieldOf(stored) {
+    if (!isRecord(stored))
+        return undefined;
+    let first;
+    mapCredentialSlots(stored["body"], (value, field) => {
+        if (first === undefined && isSealedCheckpointValue(value))
+            first = field;
+        return value;
+    });
+    return first;
+}
+export function sealStoredCheckpointCtxM28(stored, sealer, sessionId) {
+    if (stored.credentialSeal !== undefined)
+        return undefined;
+    const body = stored.body;
+    if (!isRecord(body))
+        return undefined;
+    const out = sealBody(body, sealer, sessionId);
+    return out.valuesSealed === 0 ? undefined : { ctx: mintSealedCheckpointCtx({ ...stored, body: out.body, credentialSeal: CHECKPOINT_CTX_SEAL_ALG }), valuesSealed: out.valuesSealed };
+}
 //# sourceMappingURL=checkpoint-ctx.js.map

package/dist/http/dispatch.js

@@ -8,14 +8,14 @@ import { sendJson, sendError, isSseResponse, endSseWithError } from "./send.js";
 import { admissionRefusalOf, readinessOf, healthReadinessKeys, sendReadyz, sendBillableRefusal, billableRefusalOf, billableRefusalFrame } from "./readiness.js";
 import { ENGINE_SIGNAL_KEY, buildEngineSignal, fleetMembershipKeys, healthConfigLedgerKeys, healthDrainingKeys, mintEngineSignal, restartActionable } from "../fleet/engine-signal.js";
 import { buildHealthSelfReport } from "./health-self-report.js";
-import { authorized, systemFor, gatedPrincipal, sendPrincipalRefusal, sendUnauthorized, verifiedIdentitySource, hasServiceAuth, devOpenDeployment } from "./principal-gate.js";
+import { actsForDeployment, authorized, systemFor, gatedPrincipal, sendPrincipalRefusal, sendUnauthorized, traceTokenPresented, verifiedIdentitySource, hasServiceAuth, devOpenDeployment } from "./principal-gate.js";
 const PROCESS_STARTED_AT_MS = Date.now() - Math.round(process.uptime() * 1000);
 export function readCredentialOk(req, config) {
     if (!hasServiceAuth(config))
         return true;
     if (verifiedIdentitySource(req, config) !== undefined)
         return true;
-    return config.traceToken !== undefined && config.traceToken !== "" && authorized(req, config.traceToken);
+    return traceTokenPresented(req, config);
 }
 function cors(res, req, origins, principalHeader) {
     if (!origins || origins.length === 0)
@@ -191,7 +191,7 @@ export function createDispatch(ctx) {
             }
             const mt = deps.config.metricsToken;
             const devOpen = devOpenDeployment(deps) && !mt;
-            const ok = devOpen || systemFor(req, deps.config) !== undefined || (!!mt && authorized(req, mt));
+            const ok = devOpen || (!!mt && authorized(req, mt)) || actsForDeployment(req, deps.config, () => gatedPrincipal(req, deps.config));
             if (!ok) {
                 sendUnauthorized(res, "operator");
                 return;

package/dist/http/durable-run-leg.js

@@ -3,7 +3,7 @@ import { heldWorkflowParkDecisions } from "../parked-decide.js";
 import { HEARTBEAT_MS, runInBackground } from "../runs.js";
 import { fleetRunPublisher, fleetRunLabels } from "../fleet/fleet-bus.js";
 import { cascadeConfig, runMeta } from "./run-meta.js";
-import { resolveStreamApprovalGate } from "../tool-approval.js";
+import { declaredApprovalFrameFamilies, resolveStreamApprovalGate } from "../tool-approval.js";
 import { buildActiveRunConflict } from "./active-run-conflict.js";
 import { commitPlacement, devicePlacementErrorBody } from "./device-placement.js";
 import { commitSessionInheritEnv } from "./session-inherit-env.js";
@@ -84,10 +84,11 @@ export async function mintAndDriveDurableRun(ctx, runStore, args) {
                 toolApprovalEnabled: true,
                 streamApprovalEnabled: deps.config.streamApproval?.enabled === true,
                 backend: deps.backend,
-                parkFacility: deps.checkpointStore !== undefined,
+                checkpointStore: deps.checkpointStore,
             }).active,
             windowMs: deps.config.streamApproval?.windowMs,
             windowMarginMs: deps.config.streamAskWindowMarginMs,
+            declaredFamilies: declaredApprovalFrameFamilies(args.prepared.body.settings),
         }
         : undefined, deps.checkpointStore, args.prepared.engineNotices, trustedInternals, deps.userInputLedger, args.prepared.acceptance);
     return { status: 202, body: { taskId, sessionId, status: "running", ...(args.prepared.warnings !== undefined ? { warnings: args.prepared.warnings } : {}) } };

package/dist/http/idempotency.d.ts

@@ -80,11 +80,11 @@ export declare function idemIdentityOf(caller: IdemCaller): string;
 export declare function idemKeyOf(raw: string, caller: IdemCaller, family: IdemFamily): string;
 /**
  * 一次提交的**请求体指纹** —— HTTP 三条提交腿(`POST /v1/tasks` · `/v1/tasks/stream` · `/v1/runs`)同一只规范化函数:
- * `sha256(canonicalJson(体 − taskId))` 的 hex(定宽 64)。
+ * `sha256(canonicalJsonStringify(体 − taskId))` 的 hex(定宽 64)。
  *
  * 幂等 = 同一调用方、同一键、**同一请求**:账本行记下绑定 `Idempotency-Key` 的那次请求的指纹(`task_run.idem_body_fingerprint`),
  * 同键再投而指纹不同 ⇒ 唯一回执函数答 409(`http/submit-replay.ts`)。规范化只有两步:
- *  · JSON 按键递归排序(唯一序列化器 `canonicalJson`;值为 `undefined` 的键与缺席同义)—— 键序不同的同一份体是同一请求;
+ *  · JSON 按键递归排序(唯一序列化器 core `canonicalJsonStringify`;值为 `undefined` 的键与缺席同义)—— 键序不同的同一份体是同一请求;
  *  · 去掉 `taskId` —— 它是同一条律的**另一把钥匙**(调用方自铸的主键),由回执函数的「钥匙指向别的行 ⇒ `conflict.run_exists`」判,
  *    不是请求内容(换腿重投:流式腿不带 → durable 腿带回 `x-task-id`,仍是同一请求)。
  * 头一概不进:身份已在键里(`idemKeyOf` 的身份位),其余头(`Idempotency-Key` 本身、`x-detach-on-disconnect` 一类连接语义)不是提交内容。

package/dist/http/idempotency.js

@@ -1,5 +1,5 @@
 import { createHash } from "node:crypto";
-import { canonicalJson } from "../canonical-json.js";
+import { canonicalJsonStringify } from "@sema-agent/core";
 import { gatedPrincipal } from "./principal-gate.js";
 export class IdempotencyCache {
     ttlMs;
@@ -80,7 +80,7 @@ export function idemKeyOf(raw, caller, family) {
 }
 export function submissionFingerprintOf(body) {
     const content = body !== null && typeof body === "object" && !Array.isArray(body) ? { ...body, taskId: undefined } : body;
-    return createHash("sha256").update(canonicalJson(content)).digest("hex");
+    return createHash("sha256").update(canonicalJsonStringify(content)).digest("hex");
 }
 export function submissionIdemOf(raw, caller, body) {
     return { key: idemKeyOf(raw, caller, "run"), bodyFingerprint: submissionFingerprintOf(body) };

package/dist/http/principal-gate.d.ts

@@ -12,6 +12,9 @@ export declare function systemFor(req: IncomingMessage, config: ServiceConfig):
 /** "presented credentials must verify":Authorization 带 Bearer/token scheme 且三路全验不过 → true。
  *  其他 scheme(Basic 等,非我方凭证空间)不管——由原有门语义处置,避免误伤未知代理注头。 */
 export declare function bearerPresentedButUnverified(req: IncomingMessage, config: ServiceConfig): boolean;
+/** 「这次请求出示了这台部署的只读 trace 凭据(`TRACE_TOKEN`)」—— 一句,三处读:凭据验不过判({@link bearerPresentedButUnverified})、门前读路谓词
+ *  (`dispatch.ts` 的 `readCredentialOk`)、fleet 读档的只读臂({@link fleetViewOf})。没配 ⇒ 恒 false。 */
+export declare function traceTokenPresented(req: IncomingMessage, config: ServiceConfig): boolean;
 /** loopback 三形(IPv4 / IPv6 / IPv4-mapped)—— 一处定义,diagnostics 门与任何「本机自用」判据同吃。缺席 ⇒ false(fail-closed)。 */
 export declare function isLoopbackAddress(addr: string | undefined): boolean;
 /**
@@ -62,8 +65,8 @@ export declare function sendPrincipalRefusal(res: ServerResponse, req: IncomingM
  * 每面一句模块级常量(冻结门按常量解引用逐字钉)。三句都**不含任何值**(令牌 / 头名 / 路径实参一概不回显),且**不区分**
  * 「没带」与「带错」—— 同一道门上两者逐字同体,区分就是探测面。
  *  · `credential` —— 全局凭据门(`dispatch.ts`):部署配了 service token,请求没带或带的不认(registry 登录令牌验不过同属此面);
- *  · `operator` —— 只给运维凭据开的口(`/metrics*` 与 `GET /v1/tasks/source-summary`):service token 开得了,指标口另认只读的
- *    `METRICS_TOKEN`(它在全局门之前判);
+ *  · `operator` —— 只给运维凭据开的口(`/metrics*` 与 `GET /v1/tasks/source-summary`):不带主体头的 service token 开得了(带主体头的是那位主体,
+ *    {@link actsForDeployment}),指标口另认只读的 `METRICS_TOKEN`、`source-summary` 另认只读的 `TRACE_TOKEN`(都在全局门之前判);
  *  · `identity` —— 过了凭据门(或这台部署没配 service token)、但这一口要一个**验过的调用方身份**:属主寻址的读 / 写面、规则面、
  *    记忆面。在配了 service token 的部署上,「带 service token 却没身份」只会落在只认身份的口(规则 / 记忆 / 会话策略)上 ——
  *    这时再叫调用方「去带 service token」是假出路,所以这一面的句子只讲身份。
@@ -71,7 +74,7 @@ export declare function sendPrincipalRefusal(res: ServerResponse, req: IncomingM
  */
 export type UnauthorizedFace = "credential" | "operator" | "identity";
 export declare const UNAUTHORIZED_CREDENTIAL = "unauthorized \u2014 the request carries no credential this deployment accepts: send the deployment's service token as a Bearer token in the Authorization header (its operator set it as SERVICE_AUTH_TOKEN or SERVICE_AUTH_TOKENS; a sema-up deployment keeps SERVICE_AUTH_TOKEN in ~/.sema-up/<project>/.env on the machine that ran sema-up)";
-export declare const UNAUTHORIZED_OPERATOR = "unauthorized \u2014 this endpoint is for the deployment's operators and the request carries no operator credential: send the deployment's service token as a Bearer token in the Authorization header (the metrics endpoints also accept the read-only METRICS_TOKEN)";
+export declare const UNAUTHORIZED_OPERATOR = "unauthorized \u2014 this endpoint is for the deployment's operators and the request carries no operator credential: send the deployment's service token as a Bearer token in the Authorization header without a principal header (a service-token request that names a principal acts for that principal, not for the deployment), or a read-only token this endpoint accepts (METRICS_TOKEN for the metrics endpoints, TRACE_TOKEN for the task source summary)";
 export declare const UNAUTHORIZED_IDENTITY = "unauthorized \u2014 this endpoint acts for a named caller and the request carries no caller identity this deployment verifies: identify the caller the way this deployment does (a registry sign-in token as the Bearer token, a signed principal token on a direct-door deployment, or the principal header set by a trusted front end)";
 export declare function sendUnauthorized(res: ServerResponse, face: UnauthorizedFace): void;
 /**
@@ -113,13 +116,36 @@ export declare function wiredIdentitySources(w: IdentityWiring): readonly Identi
  * 没配 service token、没装鉴权桥、没开直连门)、**也没声明**只读 trace token 或 `REQUIRE_PRINCIPAL`:请求里没有任何东西替主体头作保,头是谁都能自报的
  * **标签**(过滤 / 展示用),不是身份。装了鉴权桥的部署(SSO 单开)带登录令牌的调用方是验过的身份 ⇒ 不是 dev-open(修前只看 token / `REQUIRE_PRINCIPAL`,
  * 这一形被读成 dev-open,任何人 fleet-wide 读全部会话)。
- * 四处读它、不各写一份:会话列表的 fleet-wide 第一臂(`isFleetWide`)、会话写面的 fleet-wide 第一臂(`sessionOwnerScopeForWrite`)、
+ * 三处读它、不各写一份:fleet 调用方的第一臂({@link sessionCallerOf} —— fleet 面的 {@link fleetViewOf} 与会话行属主门都经它)、
  * 会话面的属主谓词({@link sessionOwnerReadable})、`/metrics` 族的免凭据臂(`dispatch.ts`)—— 于是「调用方是谁」在列表、单会话面与指标面上只有一只读法。
  */
 export declare function devOpenDeployment(w: IdentityWiring): boolean;
-/** 会话行属主门的调用方的唯一铸点({@link SessionCaller}):验过的主体 + 是不是 fleet 调用方 —— {@link devOpenDeployment} 上的任何调用方,
- *  或出示了这台部署的 service 凭据(`systemFor`)、不报主体的调用方(带主体头的是那位主体,不是 fleet;只读 trace token 不是 service 凭据)。 */
+/**
+ * service 凭据**代部署本身**说话:出示了这台部署的 service 凭据({@link systemFor}),且不代任何验过的主体。带主体头的 service 凭据请求是前端(BFF)
+ * 代那位主体发的 —— 它读那位主体,不读全舰队;部署姿态(单用户 / 多租)不改这一句(单用户形上的主体头同样是「这次请求为谁」)。
+ * 两处读它:fleet 调用方的凭据臂({@link sessionCallerOf})与 `/metrics` 族的 service 臂(`dispatch.ts`)。先判凭据、后取主体:`principal` 只在出示了
+ * service 凭据时才求值(调用点那一次 {@link gatedPrincipal}),没带凭据的请求不因主体头的形而改答。
+ */
+export declare function actsForDeployment(req: IncomingMessage, config: ServiceConfig, principal: () => Principal | undefined): boolean;
+/**
+ * 🔴 **「这个调用方是不是 fleet 调用方(看得到所有租户)」的唯一铸点**({@link SessionCaller}):验过的主体 + 是不是 fleet —— {@link devOpenDeployment} 上的任何
+ * 调用方,或 {@link actsForDeployment}(出示 service 凭据、不报主体)。带主体头的是那位主体,不是 fleet;只读 trace token 不是 service 凭据;operator 不在这里
+ * (运维口各自读 {@link explicitOperatorOk})。读者:会话行属主门(无主 placed 行的放行臂)与 fleet 面的 {@link fleetViewOf} —— 同一问一只读法。
+ */
 export declare function sessionCallerOf(req: IncomingMessage, w: IdentityWiring): SessionCaller;
+/** fleet 面的两档(闭集):`read` = 只读面,只读 trace 凭据在这一档也是 fleet;`write` = 写面,只认 {@link sessionCallerOf}(读凭据不能变成跨租户写权)。 */
+export type FleetFace = "read" | "write";
+/** 一次 fleet 面判定的读数:`fleetWide` = 看全舰队(不钉人);否则 `gateOwner` = 钉住的那位验过的主体,`null` = 没有可用身份(调用点答 401 identity)。 */
+export interface FleetView {
+    readonly fleetWide: boolean;
+    readonly gateOwner: Principal | null;
+}
+/**
+ * 🔴 **fleet 面「看全舰队,还是钉住一位主体」的唯一读法**。fleet 判据只有一个来源 —— {@link sessionCallerOf};本函数只把它投成 fleet 面要的两格,
+ * 并按档并上只读 trace 凭据(读档)。读者 —— 读档:舰队流、会话列表、发件链接列表、后台名册、trace 五口、用量三口、`/v1/tasks/source-summary`;
+ * 写档:删除、fork、同步族(拉取与推送同门)。
+ */
+export declare function fleetViewOf(req: IncomingMessage, w: IdentityWiring, face: FleetFace): FleetView;
 /**
  * **「这个调用方能不能动这只会话」的唯一谓词**(会话面:视图 / head / 事件流 / 记忆状态与自助抹除 / 改名置顶 / 后台任务 / MCP 重连 /
  * 面板的上一腿 MCP 投影)。没有身份边界的部署({@link devOpenDeployment})上不钉任何人(与会话列表同读,列表把这只会话列给谁,谁就读得到它);

package/dist/http/principal-gate.js

@@ -30,10 +30,13 @@ export function bearerPresentedButUnverified(req, config) {
         return false;
     if (systemFor(req, config) !== undefined)
         return false;
-    if (config.traceToken && authorized(req, config.traceToken))
+    if (traceTokenPresented(req, config))
         return false;
     return true;
 }
+export function traceTokenPresented(req, config) {
+    return !!config.traceToken && authorized(req, config.traceToken);
+}
 export function isLoopbackAddress(addr) {
     return addr === "127.0.0.1" || addr === "::1" || addr === "::ffff:127.0.0.1";
 }
@@ -68,7 +71,7 @@ export function sendPrincipalRefusal(res, req, config) {
     sendError(res, 401, "auth.principal_required", `missing principal header '${config.principalHeader}'`);
 }
 export const UNAUTHORIZED_CREDENTIAL = "unauthorized — the request carries no credential this deployment accepts: send the deployment's service token as a Bearer token in the Authorization header (its operator set it as SERVICE_AUTH_TOKEN or SERVICE_AUTH_TOKENS; a sema-up deployment keeps SERVICE_AUTH_TOKEN in ~/.sema-up/<project>/.env on the machine that ran sema-up)";
-export const UNAUTHORIZED_OPERATOR = "unauthorized — this endpoint is for the deployment's operators and the request carries no operator credential: send the deployment's service token as a Bearer token in the Authorization header (the metrics endpoints also accept the read-only METRICS_TOKEN)";
+export const UNAUTHORIZED_OPERATOR = "unauthorized — this endpoint is for the deployment's operators and the request carries no operator credential: send the deployment's service token as a Bearer token in the Authorization header without a principal header (a service-token request that names a principal acts for that principal, not for the deployment), or a read-only token this endpoint accepts (METRICS_TOKEN for the metrics endpoints, TRACE_TOKEN for the task source summary)";
 export const UNAUTHORIZED_IDENTITY = "unauthorized — this endpoint acts for a named caller and the request carries no caller identity this deployment verifies: identify the caller the way this deployment does (a registry sign-in token as the Bearer token, a signed principal token on a direct-door deployment, or the principal header set by a trusted front end)";
 export function sendUnauthorized(res, face) {
     switch (face) {
@@ -120,9 +123,29 @@ export function wiredIdentitySources(w) {
 export function devOpenDeployment(w) {
     return wiredIdentitySources(w).length === 0 && !w.config.traceToken && !w.config.requirePrincipal;
 }
+export function actsForDeployment(req, config, principal) {
+    return systemFor(req, config) !== undefined && principal() === undefined;
+}
 export function sessionCallerOf(req, w) {
     const principal = gatedPrincipal(req, w.config);
-    return { principal, fleet: devOpenDeployment(w) || (principal === undefined && systemFor(req, w.config) !== undefined) };
+    return { principal, fleet: devOpenDeployment(w) || actsForDeployment(req, w.config, () => principal) };
+}
+export function fleetViewOf(req, w, face) {
+    const caller = sessionCallerOf(req, w);
+    const fleetWide = caller.fleet || readOnlyFleetCredential(req, w.config, face);
+    return { fleetWide, gateOwner: fleetWide ? null : caller.principal || null };
+}
+function readOnlyFleetCredential(req, config, face) {
+    switch (face) {
+        case "read":
+            return traceTokenPresented(req, config);
+        case "write":
+            return false;
+        default: {
+            const unknownFace = face;
+            throw new Error(`fleetViewOf: unknown fleet face ${String(unknownFace)}`);
+        }
+    }
 }
 export function sessionOwnerReadable(caller, cell, w) {
     if (devOpenDeployment(w))
@@ -146,7 +169,7 @@ export function buildOperatorUndeclaredNotice(config, approvalFaceWired) {
         event: "operator_undeclared_single_user",
         fields: {
             detail: "this single-user deployment declares no operator: OPERATOR_PRINCIPALS is empty and OPERATOR_SINGLE_USER is not set, so no caller is an operator — " +
-                "GET /v1/approvals, its stream, /v1/assistant/inbox and /v1/assistant/tasks show each caller only its own pending approvals (a caller that sends no principal sees none) and ignore ?owner=. " +
+                "GET /v1/approvals, its stream, /v1/assistant/inbox and /v1/assistant/tasks show each caller only its own pending approvals (a caller that sends no principal sees only the anonymous ones - the cards and tasks that were submitted without a principal - never a named principal's) and ignore ?owner=. " +
                 "To act as this deployment's operator, add one line: OPERATOR_SINGLE_USER=true",
         },
     };

package/dist/http/refusal-body.d.ts

@@ -18,4 +18,16 @@ export type RefusalBody = {
 } & Record<string, unknown>;
 /** 拒体:`{ error, errorCode, ...facts }`。 */
 export declare function refusalBody(r: Refusal): RefusalBody;
+/**
+ * 引擎拒一次续跑时的**三个机读判别位** → 拒体的同名事实键(唯一读法;续跑家族的每一只拒答都读它):
+ * `detail.code` ⇒ `blockedBy`(挡住它的准入码)· `detail.field` ⇒ `field`(哪一侧 / 哪一格)· `detail.reason` ⇒ `reason`(同码多臂时哪一臂)。
+ * 一员在场 ⇔ 它是非空串;其余(缺席、非串、空串)一律不铸键 —— 引擎没说就是没说,本层不编值,也不把一个非串原样推上 wire。
+ * 载体有两种,读法同一只:同步腿的 `CheckpointError.detail`(`http/resume-legs.ts` `checkpointRefusalAnswer`),与后台停驻子代赎回回执的
+ * `details.detail`(`parked-decide.ts` 的 422 `parked_resume.startup_failed`;引擎 7.54.0 起它把认领前那只失败的同三位交到回执上)。
+ */
+export declare function resumeRefusalFacts(detail: unknown): {
+    blockedBy?: string;
+    field?: string;
+    reason?: string;
+};
 //# sourceMappingURL=refusal-body.d.ts.map

package/dist/http/refusal-body.js

@@ -1,4 +1,15 @@
 export function refusalBody(r) {
     return { error: r.message, errorCode: r.errorCode, ...r.facts };
 }
+export function resumeRefusalFacts(detail) {
+    if (typeof detail !== "object" || detail === null)
+        return {};
+    const d = detail;
+    const word = (v) => typeof v === "string" && v !== "";
+    return {
+        ...(word(d.code) ? { blockedBy: d.code } : {}),
+        ...(word(d.field) ? { field: d.field } : {}),
+        ...(word(d.reason) ? { reason: d.reason } : {}),
+    };
+}
 //# sourceMappingURL=refusal-body.js.map

package/dist/http/request-guards.d.ts

@@ -95,15 +95,6 @@ export declare function createRequestGuards(ctx: {
     usageWindowDenied: (req: IncomingMessage, res: ServerResponse) => Promise<boolean>;
     rateLimited: (req: IncomingMessage, res: ServerResponse) => boolean;
     safeDecode: (seg: string) => string | null;
-    isFleetWide: (req: IncomingMessage) => boolean;
-    sessionOwnerScope: (req: IncomingMessage) => {
-        fleetWide: boolean;
-        gateOwner: string | null;
-    };
-    sessionOwnerScopeForWrite: (req: IncomingMessage) => {
-        fleetWide: boolean;
-        gateOwner: string | null;
-    };
     runOwnerOk: (req: IncomingMessage, res: ServerResponse, owner: string | null) => boolean;
     sessionOwnerOk: (req: IncomingMessage, res: ServerResponse, cell: SessionOwnerCell) => boolean;
     runSessionAcceptOk: (req: IncomingMessage, res: ServerResponse, run: {

package/dist/http/request-guards.js

@@ -4,7 +4,7 @@ import { RUN_NOT_FOUND_MESSAGE, SESSION_NOT_FOUND_MESSAGE } from "./route-ctx.js
 import { invalidJsonError, sendError } from "./send.js";
 import { refusalBody } from "./refusal-body.js";
 import { limitFactsUnmeasured } from "../limit-refusal.js";
-import { authorized, systemFor, gatedPrincipal, explicitOperatorOk, sessionOwnerReadable, sessionCallerOf, devOpenDeployment, sendPrincipalRefusal } from "./principal-gate.js";
+import { gatedPrincipal, explicitOperatorOk, sessionOwnerReadable, sessionCallerOf, sendPrincipalRefusal } from "./principal-gate.js";
 import { runRowReadable } from "./owner-access.js";
 import { quotaWindowResetsAt } from "../observability/cost-quota.js";
 import { escapedStatementBytes, packetWallStatementBytes, rowWallPayloadBytes } from "../plugins/sql-driver.js";
@@ -184,20 +184,6 @@ export function createRequestGuards(ctx) {
             return null;
         }
     }
-    function isFleetWide(req) {
-        const tt = deps.config.traceToken;
-        return devOpenDeployment(deps) || systemFor(req, deps.config) !== undefined || (!!tt && authorized(req, tt));
-    }
-    function sessionOwnerScope(req) {
-        const fleetWide = isFleetWide(req);
-        const gateOwner = fleetWide ? null : (gatedPrincipal(req, deps.config) || null);
-        return { fleetWide, gateOwner };
-    }
-    function sessionOwnerScopeForWrite(req) {
-        const fleetWide = devOpenDeployment(deps) || systemFor(req, deps.config) !== undefined;
-        const gateOwner = fleetWide ? null : (gatedPrincipal(req, deps.config) || null);
-        return { fleetWide, gateOwner };
-    }
     function ownerGate(req, res, readable, notFound) {
         const principal = gatedPrincipal(req, deps.config);
         if (deps.config.requirePrincipal && !principal) {
@@ -265,6 +251,6 @@ export function createRequestGuards(ctx) {
         }
         return Buffer.concat(chunks);
     }
-    return { quotaExceeded, ownerCostQuotaDenied, ownerFleetLeaseDenied, ownerLeaseDenied, ownerQuotaDenied, leaseDenied, usageWindowDenialFor, usageWindowDenied, rateLimited, safeDecode, isFleetWide, sessionOwnerScope, sessionOwnerScopeForWrite, runOwnerOk, sessionOwnerOk, runSessionAcceptOk, readJson, readRawBody };
+    return { quotaExceeded, ownerCostQuotaDenied, ownerFleetLeaseDenied, ownerLeaseDenied, ownerQuotaDenied, leaseDenied, usageWindowDenialFor, usageWindowDenied, rateLimited, safeDecode, runOwnerOk, sessionOwnerOk, runSessionAcceptOk, readJson, readRawBody };
 }
 //# sourceMappingURL=request-guards.js.map

package/dist/http/resume-ctx-read.d.ts

@@ -21,8 +21,20 @@
  * 早把列错误**折**成了一只普通 `Error` ⇒ 折后的错落进下面那条「店抖动 ⇒ 当缺席」臂,坏体与缺席在
  * 用户面上仍然同答 409 —— 正是 S-577 第二半要修的那个病,只是它当时只在 local 车道上修成了(那一侧
  * 恰好没折码,把列错误漏了出来 = 巧合式正确)。两条车道现在同一份拒绝契约,本口只认它。
+ *
+ * 🔴 **第四态 `unsealable`(S-1907,7.134.0):读出来了,但凭据位上的封签开不开**。店交出的是**落盘形**(凭据位上是封签,`StoredCheckpointCtx`);
+ * 本口在任何消费者看到之前经**唯一**开口 `openCheckpointCtx` 开封(规则属主 = `checkpoint-ctx.ts` 末段「凭据位密封」)—— 所以 `ok` 交出的恒是开封形,
+ * 没有哪条腿拿着封签去重建 spec。开不开(没有保管店 / 钥匙不在本副本 / 密文坏或不是本行封的 / 明文 / 认不出的封签)⇒ `unsealable`(`field` + `reason`),
+ * 各续跑入口答 {@link resumeCtxUnsealableAnswer}(409 `conflict.checkpoint_ctx_unsealable`)。**不折成缺席**(出路不同:缺席 = 重提;开不开 = 看 `reason`
+ * —— `key_not_held` 多半是多副本没共享保管目录,运维修好之后同一个决定原样重发即可),**不明文回落、不丢键**。
+ * 开封要知道这一行的会话(封签绑会话)与开口(`ServiceDeps.checkpointCtxSealing`;缺席 = 本副本没有保管店):两件一起交({@link CheckpointCtxOpening})。
+ *
+ * **两种读法,一只读口**(第二个实参):① 开封形({@link CheckpointCtxOpening})—— 续跑重建 spec 的每一条腿;② {@link KEEP_SEALED}「信封原样留着」——
+ * 只读**非凭据字段**的读者(今天 = inbox 的展示位 `objective`):不开封、不判凭据位(活凭据不为展示进内存),交回落盘形 `StoredCheckpointCtx`,
+ * 结局里没有 `unsealable` 这一态(型面就没有;店边界的三态与开封形逐字同一段)。凭据位上的值在这种读法里仍是封签 —— 谁要用它们就必须走读法 ①。
  */
 import type { CheckpointCtx } from "./route-ctx.js";
+import { type CheckpointCtxOpener, type CheckpointCtxUnsealableReason, type StoredCheckpointCtx } from "./checkpoint-ctx.js";
 import { type RefusalBody } from "./refusal-body.js";
 export type ResumeCtxRead = {
     readonly kind: "ok";
@@ -32,8 +44,43 @@ export type ResumeCtxRead = {
 } | {
     readonly kind: "corrupt";
     readonly where: string;
+} | {
+    readonly kind: "unsealable";
+    readonly field: string;
+    readonly reason: CheckpointCtxUnsealableReason;
+};
+/** 读法 ② 的结局:店边界的三态,`ok` 交落盘形(凭据位上仍是封签)。 */
+export type SealedResumeCtxRead = {
+    readonly kind: "ok";
+    readonly ctx: StoredCheckpointCtx;
+} | {
+    readonly kind: "absent";
+} | {
+    readonly kind: "corrupt";
+    readonly where: string;
+};
+/** 开封的两件:这一行的会话(= 交给店 `getCtx` 的那一个)与开口(缺席 = 本副本没有保管店)。 */
+export interface CheckpointCtxOpening {
+    readonly sessionId: string;
+    readonly opener: CheckpointCtxOpener | undefined;
+}
+/** 读法 ② 的词:信封原样留着(只读非凭据字段)。 */
+export declare const KEEP_SEALED = "keep_sealed";
+export declare function readResumeCtx(load: Promise<StoredCheckpointCtx | null>, opening: CheckpointCtxOpening): Promise<ResumeCtxRead>;
+export declare function readResumeCtx(load: Promise<StoredCheckpointCtx | null>, opening: typeof KEEP_SEALED): Promise<SealedResumeCtxRead>;
+/**
+ * 开不开的对外答复(S-1907)—— 409 `conflict.checkpoint_ctx_unsealable`,机读 `field`(哪一个凭据位,提交体路径;键名不是秘密,值从不进来)+ `reason`
+ * (闭集 `CHECKPOINT_CTX_UNSEALABLE_REASONS`)。句子说「这条任务的续跑上下文里带的凭据本服务开不开」、五种成因与出路(按 `reason` 修好保管目录后原样重发,
+ * 或作为新任务重提、仍停驻的先取消)。拒在任何状态改动之前:卡仍待决、行字节不动、`plan_review` 的一次性 nonce 未烧。
+ * 🔴 形是给冻结门看的(与 {@link resumeCtxCorruptAnswer} 同一条):`status: <三位数>, body: refusalBody({ errorCode: "<码>", message: "<整句双引号字面>"`,中间只许有空白。
+ */
+export declare function resumeCtxUnsealableAnswer(read: {
+    readonly field: string;
+    readonly reason: CheckpointCtxUnsealableReason;
+}): {
+    status: number;
+    body: RefusalBody;
 };
-export declare function readResumeCtx(load: Promise<CheckpointCtx | null>): Promise<ResumeCtxRead>;
 /** 坏体的对外答复 —— 与会话策略面**同码**(`session-policy-wire.ts` 的 `corrupt` ⇒ 500),不铸新词。
  *  文案只说「哪一行读不出来 + 该找谁」,不把店层 detail 拼上 wire(内部机件不上 wire,S-376 同律)。 */
 export declare function resumeCtxCorruptAnswer(where: string): {

package/dist/http/resume-ctx-read.js

@@ -1,9 +1,18 @@
+import { openCheckpointCtx } from "./checkpoint-ctx.js";
 import { SqlJsonColumnError, StoreCorruptError } from "../plugins/sql-json-column.js";
 import { refusalBody } from "./refusal-body.js";
-export async function readResumeCtx(load) {
+export const KEEP_SEALED = "keep_sealed";
+export async function readResumeCtx(load, opening) {
+    const read = await readStoredCtx(load);
+    if (read.kind !== "ok" || opening === KEEP_SEALED)
+        return read;
+    const opened = openCheckpointCtx(read.ctx, opening.opener, opening.sessionId);
+    return opened.kind === "ok" ? { kind: "ok", ctx: opened.ctx } : { kind: "unsealable", field: opened.field, reason: opened.reason };
+}
+async function readStoredCtx(load) {
+    let stored;
     try {
-        const ctx = await load;
-        return ctx == null ? { kind: "absent" } : { kind: "ok", ctx };
+        stored = await load;
     }
     catch (e) {
         if (e instanceof StoreCorruptError)
@@ -12,6 +21,20 @@ export async function readResumeCtx(load) {
             throw e;
         return { kind: "absent" };
     }
+    return stored == null ? { kind: "absent" } : { kind: "ok", ctx: stored };
+}
+export function resumeCtxUnsealableAnswer(read) {
+    return {
+        status: 409,
+        body: refusalBody({
+            errorCode: "conflict.checkpoint_ctx_unsealable",
+            message: "this task's stored resume context holds credentials from its request (MCP / A2A headers or env values, settings.env, settings.webSearch.apiKey, or http hook headers) that this server cannot unseal — reason says why: no_key_store (this server has no sealed-key store), key_not_held (they were sealed with a key this server does not hold: another replica's, or a replaced sealed-key directory), unopenable (the sealed value is damaged or belongs to another session), plaintext (an older server version stored them unsealed), unrecognized_seal (a seal format this version does not know). Nothing was decided and nothing was resumed. If whoever operates this deployment restores the sealed-key directory that sealed them and restarts this server (it reads its keys only at startup), the same request can be sent again; otherwise submit the work again as a new task, and if this task is still suspended cancel it first (POST /v1/runs/:id/cancel).",
+            facts: {
+                field: read.field,
+                reason: read.reason,
+            },
+        }),
+    };
 }
 export function resumeCtxCorruptAnswer(where) {
     return {

package/dist/http/resume-legs.d.ts

@@ -35,7 +35,8 @@ export declare function resumeRefusalDisposition(e: CheckpointError): "cancelled
  * 规则(一条):**一次拒 = 一个答复形,与「谁发现的」无关**。引擎在认领前 / CAS 前拒的,与本服务在重放存量体之前自己拒的(`resume_blocked_by_policy`,
  * `checkpoint-ctx.ts` `resumeBlockedByPolicyAnswer`;续跑入口上卡仍 pending ⇒ 同样带 `retriable:true`)读同一组机读键;体经拒体组句器 `refusalBody` 铸,
  * `retriable` 经续跑家族的唯一写点 `resumeRefusalWithCard` 追加。
- * 一处如实例外:后台停驻子代的 parked 赎回不经本函数 —— 引擎的赎回回执只交成因词,`parked-decide.ts` 答 `422 parked_resume.startup_failed`,体只带 `cause`:
+ * 后台停驻子代的 parked 赎回不经本函数(引擎交的是赎回回执,不是 `CheckpointError`):`parked-decide.ts` 答 `422 parked_resume.startup_failed`,体带成因词 `cause`,
+ * 引擎 7.54.0 起回执的 `details.detail` 交出同三位判别位,经**同一只**读法 `resumeRefusalFacts` 落成同名三键(下面第二条)。键律:
  *  · `errorCode` —— 引擎码的原码镜像(`checkpoint.invalid_outcome` 按决断成因改铸,{@link decisionRefusalCauseOf});
  *  · 引擎 `detail` 的三个机读判别位原样过境,键名与 `resume_blocked_by_policy` 同义:`detail.code` ⇒ `blockedBy`(挡住它的准入码 = 同一份坏配置在新跑上报的 `errorCode`;
  *    今天只有 `checkpoint.config_refused` 带它)· `detail.field` ⇒ `field`(哪一侧 / 哪一格)· `detail.reason` ⇒ `reason`(同码多臂时哪一臂,闭集 `CheckpointErrorReason`)。