@sema-agent/server 7.133.0 → 7.135.0

package/dist/http/checkpoint-ctx.d.ts

@@ -39,6 +39,10 @@
  * `resolveSpec` 本身留作真正的拒点(提交腿 400;续跑腿在到它之前已被本判据答掉)。再开第六个问点必须调这两只,不许各判各的 —— 此前铸卡前只判了
  * allow 记号,工具名清单那一问漏在外面,卡铸出来了、`/wake` 恒 409([ref] 合并复审两腿同报)。
  *
+ * ## 凭据位密封(7.134.0;常设规则,不是迁移)
+ * 体里请求面凭据位上的值在 ctx 里只以封签存在 —— 写:{@link buildCheckpointCtx} / {@link sealCheckpointCtx} 一只封口;读:续跑上下文读口里一只开口
+ * {@link openCheckpointCtx};开不开 ⇒ `409 conflict.checkpoint_ctx_unsealable`。规则全文在本文件末段「凭据位密封」的头注。
+ *
  * ## 何时删(一次性迁移,不是长期双读)
  * 本判据、拒臂、记号写点与 `CheckpointCtx.permissionsAllowReading` 一起删,删除条件与窗登记在 `plugins/one-time-migrations.ts` 的
  * 一次性迁移登记表(本条那一行):所有旧读法下停驻的行都已结束或被收割(停驻行的终局 = 落盘起 `TERMINAL_BACKSTOP_MS`,见
@@ -73,14 +77,16 @@ export declare function bodyCarriesAllowList(body: TaskRequestBody): boolean;
  * 调用方是「本进程刚按当前读法读过这份体」的写点:fresh 提交(受理门按当前读法读过 `allow`),或已经过了续跑拒臂的重放腿
  * (`startFreshHostTurn` 把宿主的存量体交给 `POST /v1/runs` 同一条链 —— 它在那之前调过 `resolveResumeSpecOrBlocked`,没记号却带 `allow` 的体到不了这里)。
  * 续跑腿的**写回**不经本函数:**不改词**的写回传读进来的 ctx(记号随行,不重新判 —— 在写回口重新判会把一条没记号的旧行「洗」成新行);
- * **改词**的写回(只有 `plan_review` 的批准 / 编辑)经 {@link withPermissionModeRewritten}。
+ * **改词**的写回(只有 `plan_review` 的批准 / 编辑)经 {@link withPermissionModeRewritten}。两种写回落盘之前都过同一只封口 {@link sealCheckpointCtx}。
+ *
+ * `sealer` / `sessionId`:凭据位密封的两件(本文件末段)—— `sessionId` 是这一行的会话(绑进封签);`sealer` 必传,缺席也要说出来(`undefined`)。
  */
 export declare function buildCheckpointCtx(fields: {
     body: TaskRequestBody;
     memoryScope?: string | undefined;
     unattendedLeg?: true;
     writerVersion: string;
-}): CheckpointCtx;
+}, sealer: CheckpointCtxSealer | undefined, sessionId: string): SealedCheckpointCtx;
 /**
  * 模式词的**第二个写者** —— `plan_review` 的批准 / 编辑把这条 run 的体词从 `plan` 写成批准的档(`resume-legs.ts` `drivePlanReview`,调用点只有那一处;
  * `test/allow-list-reading-park-refusal.test.ts` 枚举调用点,多一处即红)。与 {@link buildCheckpointCtx} **同一条规则**:按当前读法写下的词,盖当前读法记号。
@@ -208,4 +214,179 @@ export declare function storedBodyReplayLogFields(refusal: StoredBodyReplayRefus
  * 没有默认值:每个调用点必须说出这件事实。
  */
 export declare function storedBodyReplayAnswer(refusal: StoredBodyReplayRefusal, readerVersion: string, cardPending: boolean): ResumeRefusalAnswer;
+/**
+ * 🔴 **停驻行里请求面凭据的落盘形 —— 一条规则**:提交体里**凭据位**({@link CHECKPOINT_CTX_CREDENTIAL_SLOTS},闭集)上的每一个值,在 `checkpoint_ctx`
+ * (local 店的 `<数据根>/checkpoint-ctx/<会话>.json` / SQL 店的 `checkpoint_ctx.ctx` 列)里只以**封签**({@link SealedCheckpointValue})存在。
+ *  · **写**:一只封口 {@link sealCheckpointCtx}。新的持久化写经 {@link buildCheckpointCtx}(它的唯一产物形就是封好的 {@link StoredCheckpointCtx}),
+ *    续跑腿的写回(`resume-legs.ts` 的 `commitResumeCtx`:读进来的 ctx 在内存里是开封形)经它本身;一次性迁移 M28 对存量行用同一只走法
+ *    ({@link sealStoredCheckpointCtxM28})。凭据位上的**每一个值都封,不分类型**(串、数字、`null`、对象 —— 包括调用方自己送来的封签形对象):
+ *    封签里装的是那个 JSON 值本身,开封逐字还原。字典位上的容器本身不是字典(串 / 数组 / `null` / 封签形对象)⇒ 整只容器当一个值封。
+ *    于是落盘形里凭据位上**只有本封口铸的封签**,没有哪个值能「原样存下、续跑时被开成别的东西」(调用方送一只封签形对象 ⇒ 存的是再封一层,
+ *    开出来还是那只对象 —— 与新提交腿看到的同一个值)。没有封签器而有值要封 ⇒ 抛 {@link CheckpointCtxUnsealableError}(`no_key_store`,调用方在写之前拒)。
+ *  · **读法记号**(与本文件另两只记号同一条「写的人盖章」):封口铸出的每一份落盘形都带 `credentialSeal: CHECKPOINT_CTX_SEAL_ALG` 与
+ *    `credentialSlotGeneration`(= 这一行里**带值的**凭据位最新的那一代,最小 1)—— 这一行的凭据位全部由本封口封过,且它用到的位不比这一代新。
+ *    代数取「用到的」而不取「本版的」:不带新位值的行与上一代的写者写下的同形,回滚到上一代照读;代数比读者新 ⇒ 这一行**一定**带着读者不认识的位 ⇒ 读者整行拒。没有记号的行是 7.134.0 之前的写者写下的:
+ *    那时没有任何写者封值,所以它凭据位上的封签形对象只可能是调用方原样送来的,不是封签。代数缺席的带记号行是 7.134.0 的写者写下的 —— 它封的是第 1 代
+ *    (闭集每行的 `since`);某一位的 `since` 大于这一行封过的代数 ⇒ 那一位上的值不论长什么样都没被封过(一只恰好长成封签形的明文字典也是明文)。
+ *    记号只在落盘形上(开口交出的开封形里没有它;写回再封时重新盖)。
+ *  · **读**:一只开口 {@link openCheckpointCtx},唯一调用方 = 续跑上下文唯一读口 `resume-ctx-read.ts` 的 `readResumeCtx`(读出的 ctx 在任何消费者
+ *    看到之前已开封)。逐值判词 = {@link credentialValueReading}(开口与 M28 同一只):行带当前记号、这一位在它封过的那一代里:凭据位上封签 ⇒ 开(开不开 ⇒ 拒);
+ *    带 `sealed` 键却不是本闭集的封签形(含将来的 `alg`)⇒ 拒 `unrecognized_seal`;其余任何值 ⇒ 拒 `plaintext`。这一位比行封过的代数新 ⇒ 任何值 ⇒ 拒 `plaintext`。
+ *    行没有记号 ⇒ 凭据位上**任何**值(含封签形对象)⇒ 拒 `plaintext`(更早版本写下、M28 还没扫到);记号认不得(将来的格式)⇒
+ *    凭据位上任何值 ⇒ 拒 `unrecognized_seal`,凭据位上没有值的行不论记号照常开;代数认不得(比本版新 / 不是正整数)⇒ **整行**拒 `unrecognized_seal`(`field` = 记号位名),不看已知位上有没有值。
+ *    **拒** = 读口第四态 `unsealable`(`field` = 哪一个凭据位,`reason` ∈ {@link CHECKPOINT_CTX_UNSEALABLE_REASONS}),各续跑入口答
+ *    `409 conflict.checkpoint_ctx_unsealable`(`resume-ctx-read.ts` 的 `resumeCtxUnsealableAnswer`)。**没有**明文回落臂、**没有**静默丢键臂。
+ *  · **装配**:`checkpointStore` 在场而封签器缺席 ⇒ 拒启({@link CHECKPOINT_CTX_SEALING_REQUIRED};`createHttpServer` 与起服第 6 段同一句)。
+ *
+ * **一个域一对钥匙**:停驻行封签用这一域自己的保管店(`<数据根>/sealed-key/checkpoint-ctx-keys/`,生产工厂 `sealed-key.ts` `ensureCheckpointCtxSealing`),
+ * 与模型钥匙(`ModelEntry.sealedApiKey`)的那对钥匙不共用 —— 模型钥匙的密文放进凭据位、停驻行的封签放进 `sealedApiKey`,两边都是「不持有那把钥匙」;
+ * 封签再把**会话 id 绑进密文**(信封 = `[alg, sessionId, value]`):别的会话那一行的封签搬过来开不开 —— 读口不是这台副本任何一把钥匙的解密预言机。
+ *
+ * 本模块的零值依赖纪律照旧:封签器 / 开封器是调用方递进来的接口(实现在 `sealed-key.ts`,它依赖 libsodium,不进本模块的闭包)。
+ */
+export declare const CHECKPOINT_CTX_SEAL_ALG = "checkpoint-ctx-sealedbox-v1";
+/** 停驻行里一只凭据值的**封签**(闭集形:恰这三键、三值皆串、`alg` 只有 {@link CHECKPOINT_CTX_SEAL_ALG} 一个词)。与明文不可混淆:明文是串,封签是对象。 */
+export interface SealedCheckpointValue {
+    readonly alg: typeof CHECKPOINT_CTX_SEAL_ALG;
+    /** 封它的那把公钥的 id(开封按它**精确**选私钥,不逐把试)。 */
+    readonly publicKeyId: string;
+    /** `crypto_box_seal` 密文的标准 base64。 */
+    readonly sealed: string;
+}
+/** 封口(只会封):把凭据位上的一个 JSON 值(任何类型)封进 `sessionId` 那一行。抛 = 封不了(调用方当写失败处置)。 */
+export interface CheckpointCtxSealer {
+    seal(value: unknown, sessionId: string): SealedCheckpointValue;
+}
+/** 开口:`holds` = 这台副本有没有 `publicKeyId` 那把私钥;`open` 抛 = 开不开(密文坏 / 不是 `sessionId` 那一行封的 / 不是停驻行信封);返回封进去的那个 JSON 值。
+ *  🔴 `open` 的返回值是活凭据:只进内存,不进日志、不落盘(再落盘必经 {@link sealCheckpointCtx})。 */
+export interface CheckpointCtxOpener {
+    holds(publicKeyId: string): boolean;
+    open(sealed: SealedCheckpointValue, sessionId: string): unknown;
+}
+/** 封签器 = 封口 + 开口(生产工厂 `sealed-key.ts` `ensureCheckpointCtxSealing`;`ServiceDeps.checkpointCtxSealing` 的型)。 */
+export interface CheckpointCtxSealing extends CheckpointCtxSealer, CheckpointCtxOpener {
+}
+/**
+ * **凭据位闭集**(提交体里值为凭据的位置)。路径段 `*` = 那一格容器的**每一个成员**:数组的每一项、字典的每一个值(一只走法,不分容器种类 —— 字典成员的点名形
+ * `field` 是 `.<键>`,数组是 `[<下标>]`)。`map` = 那一格是串值字典,**每一个值**都是凭据(不分哪一键);`value` = 那一格本身是凭据。
+ * 入表判据(一条):请求面上**为承载凭据而设**的字段 —— 静态请求头(MCP http 传输、A2A 对端〔引擎型注:「e.g. an auth bearer」〕、http hook 条目)、
+ * 交给子进程的 env(MCP stdio 传输、任务 shell 的 `settings.env`、command hook 条目的插件选项)、请求自带的搜索后端钥匙。http hook 的头与另两种静态头同判:契约包的条目形是
+ * `headers: Record<string, string>`、受理面(`parseHooksConfig`)只判条数与字数、`interpolateHookEnvVars` 只换 `$NAME` 引用而字面值原样上 wire ——
+ * 头值可以就是字面的 `Authorization: Bearer …`。插件选项与 `settings.env` 同判:`plugin.options` 的每一个值就是 hook 子进程环境里的 `CLAUDE_PLUGIN_OPTION_<KEY>`
+ * (`hooks/command-spawn.ts` 的 `hookPluginEnv`),参照实现也把 sensitive 选项照样交进这一族环境变量 —— 值是不是秘密不是本层能判的,所以整格封,不判值形。
+ * hooks 的形 = 事件名 → 匹配组数组 → 组的 `hooks` 数组 → 条目;只有 `type:"http"` 的条目有 `headers`、只有带 `plugin` 的 command 条目有 `plugin.options`,
+ * 别的条目在那一段缺席、走法照常不往下走。**不入表**:命令行 / URL / 工具实参之类自由文本(不是凭据字段;它们里有没有秘密不是本层能判的)。
+ * 加一位 = 加一行,读写两侧与一次性迁移 M28 共用 {@link mapCredentialSlots} 一只走法:写侧与读侧立即覆盖;已落盘的行由 M28 补封 ——
+ * 新行的 `since` 取下一代:封口铸的落盘形盖「这一行里带值的位最新的那一代」(`credentialSlotGeneration`),读者据它判那一行用到、封过哪几位 —— 代数更早的行上新位的值一律是明文(记号本身不证明它封过新位)。
+ * M28 封的是「读口会答 `plaintext` 的每一个值」({@link credentialValueReading}),所以新加的一位上的明文在带记号的行里也被补封(只在 M28 的窗内;窗外加位要另起迁移)。
+ */
+export declare const CHECKPOINT_CTX_CREDENTIAL_SLOTS: readonly [{
+    readonly path: readonly ["mcpServers", "*", "transport", "headers"];
+    readonly holds: "map";
+    readonly since: 1;
+}, {
+    readonly path: readonly ["mcpServers", "*", "transport", "env"];
+    readonly holds: "map";
+    readonly since: 1;
+}, {
+    readonly path: readonly ["a2aPeers", "*", "headers"];
+    readonly holds: "map";
+    readonly since: 1;
+}, {
+    readonly path: readonly ["settings", "env"];
+    readonly holds: "map";
+    readonly since: 1;
+}, {
+    readonly path: readonly ["settings", "webSearch", "apiKey"];
+    readonly holds: "value";
+    readonly since: 1;
+}, {
+    readonly path: readonly ["settings", "hooks", "*", "*", "hooks", "*", "headers"];
+    readonly holds: "map";
+    readonly since: 1;
+}, {
+    readonly path: readonly ["settings", "hooks", "*", "*", "hooks", "*", "plugin", "options"];
+    readonly holds: "map";
+    readonly since: 2;
+}];
+/** 本版闭集的代数 = 表里最大的 `since`(读者认得的最新一代)。落盘形的 `credentialSlotGeneration` 不大于它;大于它的行是更新的写者带着本版不认识的位写下的。 */
+export declare const CHECKPOINT_CTX_CREDENTIAL_GENERATION: number;
+/** 开不开 / 封不了的成因(闭集):`no_key_store` = 这台副本没有封签器(没有保管店);`key_not_held` = 封它的那把钥匙不在这台副本的保管店里
+ *  (多副本不共享 `<数据根>/sealed-key/`,或保管目录被换过);`unopenable` = 钥匙在、开不开(密文坏 / 不是这一行封的 / 不是停驻行信封);
+ *  `plaintext` = 凭据位上是明文(更早版本的写者);`unrecognized_seal` = 带 `sealed` 键却不是本闭集的封签形(含将来的 `alg`)。 */
+export declare const CHECKPOINT_CTX_UNSEALABLE_REASONS: readonly ["no_key_store", "key_not_held", "unopenable", "plaintext", "unrecognized_seal"];
+export type CheckpointCtxUnsealableReason = (typeof CHECKPOINT_CTX_UNSEALABLE_REASONS)[number];
+/** 封不了 / 开不开的那一格:`field` = 凭据位在提交体里的路径(如 `mcpServers[0].transport.headers.Authorization`、
+ *  `settings.hooks.PreToolUse[0].hooks[0].headers.Authorization`;键名不是秘密,值从不进来)。 */
+export declare class CheckpointCtxUnsealableError extends Error {
+    readonly field: string;
+    readonly reason: CheckpointCtxUnsealableReason;
+    constructor(field: string, reason: CheckpointCtxUnsealableReason);
+}
+/**
+ * 停驻行的**落盘形**:凭据位上是封签,不是 {@link TaskRequestBody} 型面说的串 —— 所以体在型面上只是「一只对象」,读它的唯一合法方式是 {@link openCheckpointCtx}
+ * (经续跑上下文读口)。产物只有两只铸点:{@link buildCheckpointCtx} 与 {@link sealCheckpointCtx}。
+ */
+export type StoredCheckpointCtx = Omit<CheckpointCtx, "body"> & {
+    readonly body: {
+        readonly [key: string]: unknown;
+    };
+    readonly credentialSeal?: typeof CHECKPOINT_CTX_SEAL_ALG;
+    /** 这一行的写者封过的闭集代数(读法记号的另一半;缺席 + 带 `credentialSeal` = 7.134.0 的写者 = 第 1 代)。 */
+    readonly credentialSlotGeneration?: number;
+};
+declare const sealedCheckpointCtxBrand: unique symbol;
+/**
+ * **封口铸出的**落盘形(品牌型):店的写口(`putCtx`)与一次性迁移 M28 的行改写只收它 ⇒ 「写 ctx 只有封口一个写入面」由型面守,
+ * 不再靠逐个数调用点(把开封形 / 裸对象直接交给写口 = 当场 tsc 红)。铸点闭集(都在本模块,都经 {@link mintSealedCheckpointCtx}):
+ * {@link sealCheckpointCtx}(新的持久化写经 {@link buildCheckpointCtx} 到它;续跑腿的写回)与 {@link sealStoredCheckpointCtxM28}。零运行期变化。
+ */
+export type SealedCheckpointCtx = StoredCheckpointCtx & {
+    readonly [sealedCheckpointCtxBrand]: true;
+};
+/** 装配期拒启的那一句(`createHttpServer` 与起服第 6 段同调;一句、一个出口)。 */
+export declare 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, command hook plugin options) in their resume context, and they are stored sealed or not at all \u2014 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 \u2014 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";
+/** 封签形的判官(恰三键、三值皆串、`alg` 是本闭集那一个词)。 */
+export declare function isSealedCheckpointValue(v: unknown): v is SealedCheckpointValue;
+/**
+ * **封口**(写的一侧唯一的一只):内存里的开封形 ctx ⇒ 落盘形。`sealer` 必传(缺席也要说出来:`undefined` = 这台副本没有保管店 ⇒ 体里有凭据就抛
+ * {@link CheckpointCtxUnsealableError} `no_key_store`,调用方在写之前拒;体里没有凭据 ⇒ 没有要封的东西,照常)。`sessionId` = 这一行的会话(绑进封签)。
+ * 调用方:{@link buildCheckpointCtx}(新的持久化写)与续跑腿的写回(`resume-legs.ts` `commitResumeCtx`)。
+ */
+export declare function sealCheckpointCtx(ctx: CheckpointCtx, sealer: CheckpointCtxSealer | undefined, sessionId: string): SealedCheckpointCtx;
+/** {@link openCheckpointCtx} 的结局:开封形 ctx,或第一处开不开的凭据位。 */
+export type OpenedCheckpointCtx = {
+    readonly kind: "ok";
+    readonly ctx: CheckpointCtx;
+} | {
+    readonly kind: "unsealable";
+    readonly field: string;
+    readonly reason: CheckpointCtxUnsealableReason;
+};
+/**
+ * **开口**(读的一侧唯一的一只;唯一调用方 = 续跑上下文读口 `readResumeCtx`):落盘形 ⇒ 开封形。`opener` 缺席 = 这台副本没有保管店(体里有封签就
+ * `no_key_store`;没有凭据的行照常开)。判词见本段头注与 {@link credentialValueReading}。
+ */
+export declare function openCheckpointCtx(stored: StoredCheckpointCtx, opener: CheckpointCtxOpener | undefined, sessionId: string): OpenedCheckpointCtx;
+/**
+ * 一份落盘 ctx(持久化 JSON,不信型面)的凭据位上**第一只封签**的点名(`field`,形同拒句里的那一位;键名不是秘密,值从不出来)—— 没有 ⇒ `undefined`。
+ * 走法 = 封口 / 开口 / M28 共用的那一只 {@link mapCredentialSlots},判形 = {@link isSealedCheckpointValue};不开封、不看记号(只问「凭据位上有没有封签」)。
+ * 唯一读者:随包排空检查脚本的 `sealed-credentials-rollback` 判据(经编译产物取):7.133.x 读不懂封签、续跑时把这些凭据位当没有 ⇒ 回滚之前先把这样的停驻行决掉或取消。
+ */
+export declare function sealedCredentialFieldOf(stored: unknown): string | undefined;
+/**
+ * 🔴 **一次性迁移 M28 的行改写**(窗与删法见 `plugins/one-time-migrations.ts` 登记表 M28;编排 = `checkpoint-ctx-seal-m28.ts`):一行存量 ctx
+ * (持久化 JSON,不信型面)凭据位上**读口会答 `plaintext` 的每一个值**({@link credentialValueReading},与开口同一只判词)用同一只封口封好、盖记号 ——
+ * 与写侧 {@link sealCheckpointCtx} 同一条规则。两种存量行落在这一条里:
+ *  · 没有读法记号的行(7.134.0 之前的写者)—— 每一个值都是 `plaintext`(含调用方原样送来的封签形对象)⇒ 全封;
+ *  · 带当前记号、而某一位比行封过的代数新的行(7.134.0 的写者封第 1 代,没封第 2 代的 `plugin.options`)—— 那一位上的值不论长什么样都是明文 ⇒ 封
+ *    (恰好长成封签形的选项字典按字典容器整只封,开出来还是那只字典);行封过的那一代里的封签不动。改写后的行盖「带值的位最新的那一代」(与封口同一条)。
+ * 读口会答 `seal` / `unrecognized_seal` 的值不动(认不得的留给读口拒);一个值都没封 ⇒ `undefined`(不写:第二跑零命中;记号认不得的行因此一个字节不动);
+ * 体不是对象 ⇒ `undefined`(读口自己的形判接住)。其余位(另两只记号、写者版本、非凭据字段)原样。
+ */
+export declare function sealStoredCheckpointCtxM28(stored: object, sealer: CheckpointCtxSealer, sessionId: string): {
+    readonly ctx: SealedCheckpointCtx;
+    readonly valuesSealed: number;
+} | undefined;
+export {};
 //# sourceMappingURL=checkpoint-ctx.d.ts.map

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,198 @@ 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", since: 1 },
+    { path: ["mcpServers", "*", "transport", "env"], holds: "map", since: 1 },
+    { path: ["a2aPeers", "*", "headers"], holds: "map", since: 1 },
+    { path: ["settings", "env"], holds: "map", since: 1 },
+    { path: ["settings", "webSearch", "apiKey"], holds: "value", since: 1 },
+    { path: ["settings", "hooks", "*", "*", "hooks", "*", "headers"], holds: "map", since: 1 },
+    { path: ["settings", "hooks", "*", "*", "hooks", "*", "plugin", "options"], holds: "map", since: 2 },
+];
+export const CHECKPOINT_CTX_CREDENTIAL_GENERATION = Math.max(...CHECKPOINT_CTX_CREDENTIAL_SLOTS.map((slot) => slot.since));
+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, command hook plugin options) 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, "", (value, field) => visit(value, field, slot));
+    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;
+    let generation = 1;
+    const sealed = mapCredentialSlots(body, (value, field, slot) => {
+        if (sealer === undefined)
+            throw new CheckpointCtxUnsealableError(field, "no_key_store");
+        valuesSealed += 1;
+        generation = Math.max(generation, slot.since);
+        return sealer.seal(value, sessionId);
+    });
+    return { body: sealed, valuesSealed, generation };
+}
+export function sealCheckpointCtx(ctx, sealer, sessionId) {
+    const { body, generation } = sealBody(ctx.body, sealer, sessionId);
+    return mintSealedCheckpointCtx({ ...ctx, body: body, credentialSeal: CHECKPOINT_CTX_SEAL_ALG, credentialSlotGeneration: generation });
+}
+const CREDENTIAL_GENERATION_FIELD = "credentialSlotGeneration";
+function credentialStampOf(stored) {
+    const stamp = stored.credentialSeal;
+    const raw = stored.credentialSlotGeneration;
+    const generation = raw === undefined ? 1 : Number.isInteger(raw) && raw >= 1 && raw <= CHECKPOINT_CTX_CREDENTIAL_GENERATION ? raw : undefined;
+    return { stamp, generation };
+}
+function credentialValueReading(row, slot, value) {
+    if (row.stamp === undefined)
+        return "plaintext";
+    if (row.stamp !== CHECKPOINT_CTX_SEAL_ALG || row.generation === undefined)
+        return "unrecognized_seal";
+    if (slot.since > row.generation)
+        return "plaintext";
+    if (isSealedCheckpointValue(value))
+        return "seal";
+    if (isRecord(value) && Object.hasOwn(value, "sealed"))
+        return "unrecognized_seal";
+    return "plaintext";
+}
+export function openCheckpointCtx(stored, opener, sessionId) {
+    const { credentialSeal: _stamp, credentialSlotGeneration: _generation, ...rest } = stored;
+    const row = credentialStampOf(stored);
+    if (row.stamp === CHECKPOINT_CTX_SEAL_ALG && row.generation === undefined)
+        return { kind: "unsealable", field: CREDENTIAL_GENERATION_FIELD, reason: "unrecognized_seal" };
+    try {
+        const body = mapCredentialSlots(stored.body, (value, field, slot) => {
+            const reading = credentialValueReading(row, slot, value);
+            switch (reading) {
+                case "plaintext":
+                case "unrecognized_seal":
+                    throw new CheckpointCtxUnsealableError(field, reading);
+                case "seal": {
+                    const sealed = value;
+                    if (opener === undefined)
+                        throw new CheckpointCtxUnsealableError(field, "no_key_store");
+                    if (!opener.holds(sealed.publicKeyId))
+                        throw new CheckpointCtxUnsealableError(field, "key_not_held");
+                    try {
+                        return opener.open(sealed, sessionId);
+                    }
+                    catch {
+                        throw new CheckpointCtxUnsealableError(field, "unopenable");
+                    }
+                }
+                default: {
+                    const unreachable = reading;
+                    return unreachable;
+                }
+            }
+        });
+        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) {
+    const row = credentialStampOf(stored);
+    const body = stored.body;
+    if (!isRecord(body))
+        return undefined;
+    let valuesSealed = 0;
+    let generation = 1;
+    const sealed = mapCredentialSlots(body, (value, _field, slot) => {
+        generation = Math.max(generation, slot.since);
+        if (credentialValueReading(row, slot, value) !== "plaintext")
+            return value;
+        valuesSealed += 1;
+        return sealer.seal(value, sessionId);
+    });
+    return valuesSealed === 0
+        ? undefined
+        : { ctx: mintSealedCheckpointCtx({ ...stored, body: sealed, credentialSeal: CHECKPOINT_CTX_SEAL_ALG, credentialSlotGeneration: generation }), valuesSealed };
+}
 //# sourceMappingURL=checkpoint-ctx.js.map

package/dist/http/dispatch.d.ts

@@ -1,12 +1,12 @@
 /**
- * 请求流水线(S-147 切片:`http/server.ts` 的 `handle()` 与它的模块级词表搬家;S-146 再把「这是什么路由」
+ * 请求流水线([ref] 切片:`http/server.ts` 的 `handle()` 与它的模块级词表搬家;[ref] 再把「这是什么路由」
  * 整件事交给 `./route-table.ts`)。
  *
  * 住在这里的是**一条请求从进门到落地**的全过程,一件事一遍:admission 计数 / 附着登记 / CORS / /health /
  * /metrics / 鉴权桥 / 全局服务凭据门 / 无凭据写门 / drain 与 roster-pending 两道 503 / 破坏性会话写门 /
  * 两段分派 / 全局 404。
  *
- * 🔴 S-146 之后本文件**不再持有任何一份路由名单**:分派序、门侧、标签、三只门的判据全部读
+ * 🔴 [ref] 之后本文件**不再持有任何一份路由名单**:分派序、门侧、标签、三只门的判据全部读
  * `ROUTES` / `ROUTE_DECLARATIONS`(见 route-table.ts 头注)。三道门也不再「按行号插在 37 只 if 中间」——
  * 它们在门前段与门后段之间**恒定一处**执行,三段代码逐字未动,只是不再被域调用夹着。
  *
@@ -19,7 +19,7 @@ import type { ServiceConfig } from "../config-types.js";
 import type { RouteCtxBase, RunRegistry } from "./route-ctx.js";
 import type { FlatServiceDeps } from "./server.js";
 /**
- * 🔴 S-672(test T-72 [ref];主会话裁 ①,分诊 [ref])—— 全局服务凭据门**之前**那几族只读路
+ * 🔴 [ref](test T-72 [ref];主会话裁 ①,分诊 [ref])—— 全局服务凭据门**之前**那几族只读路
  * (`route-table.ts` 里 `position: "read-credential"` 的行)的**唯一**鉴权谓词:「服务凭据 ∨ 已验 principal」。
  *
  * 病:这几族(trace-usage / workflows / fleet)排在全局门之前,理由只有一条 —— 只读 `TRACE_TOKEN` 单凭据的调用方

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";
@@ -12,6 +12,7 @@ import { recordResourceWindow } from "../resource-window.js";
 import { persistSubmitCtx } from "./submit-ctx.js";
 import { releaseClaimedRun } from "./claimed-run.js";
 import { serviceVersion } from "../service-version.js";
+import { headReadOf } from "../session-incarnation.js";
 export async function mintAndDriveDurableRun(ctx, runStore, args) {
     const { deps } = ctx;
     const { inflightRuns, preemptableRuns, steerableRuns } = ctx.registry;
@@ -59,10 +60,10 @@ export async function mintAndDriveDurableRun(ctx, runStore, args) {
     }
     commitSessionInheritEnv(deps, args.prepared.spec.sessionId, args.prepared.body);
     const anchorOwner = args.prepared.auth?.principal ?? null;
-    const getLeafId = deps.sessionStorage?.getLeafId?.bind(deps.sessionStorage);
-    const captureTurnAnchor = deps.resumeAnchorStore && getLeafId
+    const headOf = headReadOf(deps.sessionStorage);
+    const captureTurnAnchor = deps.resumeAnchorStore && headOf
         ? async (eventId) => {
-            const leaf = await getLeafId(sessionId);
+            const leaf = (await headOf(sessionId))?.leafId;
             if (leaf)
                 await deps.resumeAnchorStore.put(sessionId, eventId, leaf, anchorOwner);
         }
@@ -84,10 +85,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` 一类连接语义)不是提交内容。
@@ -109,7 +109,7 @@ export declare function submissionIdemOf(raw: string, caller: IdemCaller, body:
  */
 export declare function inflightKeyOf(idem: RunIdemBinding, face: SubmitReplayFace, clientTaskId?: string): string;
 /**
- * 提交腿的**运行结局**(在飞合流共享的那一只)—— `status` + `body` 是它一直以来的两位;S-528 起多一位
+ * 提交腿的**运行结局**(在飞合流共享的那一只)—— `status` + `body` 是它一直以来的两位;[ref] 起多一位
  * `wiringManifest`。
  *
  * 🔴 **为什么回执挂在 outcome 上、不铸进 `body`**(codex 对抗复审 [medium],红先复现后修):在飞合流按资源族
@@ -132,7 +132,7 @@ export declare function inflightKeyOf(idem: RunIdemBinding, face: SubmitReplayFa
 export interface SubmitOutcome {
     status: number;
     body: unknown;
-    /** S-528:本条 run 的起手接线回执(present-iff 引擎真产了 `wiring_manifest` 帧)。 */
+    /** [ref]:本条 run 的起手接线回执(present-iff 引擎真产了 `wiring_manifest` 帧)。 */
     wiringManifest?: WiringManifestReceipt;
 }
 //# sourceMappingURL=idempotency.d.ts.map

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/mcp-dial-deadline.d.ts

@@ -1,10 +1,10 @@
 /**
- * S-431 —— 一条 HTTP 请求愿意等**一次远端 MCP 拨号**多久:**一只数、一只 helper**,两口共读。
+ * [ref] —— 一条 HTTP 请求愿意等**一次远端 MCP 拨号**多久:**一只数、一只 helper**,两口共读。
  *
  * 同一类动作(连一台远端 MCP 服务器 + 列它的工具)在本仓有两张 HTTP 面:
  *  · `GET /v1/sessions/:id/mcp` 面板(`routes/sessions.ts`)—— 物化部署缺省场景的申报,到点答 200 `degraded:true`;
  *  · `POST /v1/sessions/:id/mcp/reconnect`(`routes/mcp-reconnect.ts`)—— 在飞 run 上重拨一台,到点答 503。
- * 修前面板有期限、reconnect 是裸 `await`(S-431):同一件事两个读法,一台拨不通 / 半开的远端能把后者挂很久。
+ * 修前面板有期限、reconnect 是裸 `await`([ref]):同一件事两个读法,一台拨不通 / 半开的远端能把后者挂很久。
  * 两口各自**到点答什么**不同(面板是只读的部署面,有一个诚实的空形;reconnect 是一次交易,没有结果就没有
  * 一个能当 `outcome` 的词)—— 但**等多久**是一个事实,所以只有一个数。
  *
@@ -26,9 +26,11 @@ export declare class DeadlineExceeded extends Error {
  * 让**应答**不再等 `work`:`work` 先落定就原样交出(resolve / reject 都不变形),期限先到就 reject
  * {@link DeadlineExceeded}。
  *
- * 🔴 **只界应答,不取消 `work`**:本函数不持有任何取消把手 —— core 的 `TaskStream.reconnectMcpServer` 与
- * `materializeMcpTools` 都不收 `AbortSignal`(d.ts 逐字),所以期限到点后底层拨号**继续跑**,落定时
- * 才释放它占的连接 / 子进程。调用点必须把这句话交代给调用方(reconnect 的 503 文案、契约 §G.7c)。
+ * 🔴 **只界应答,本身不取消 `work`**:本函数不持有任何取消把手 —— 取消是调用点的事,两口各自读 core 动词的形:
+ *  · 面板的 `materializeMcpTools` 自 core 7.55.0([ref])起收末位 `signal`:面板在期限到点时触发它,在飞的拨号就停、半开连接被关
+ *    (`routes/sessions.ts`);
+ *  · reconnect 的 `TaskStream.reconnectMcpServer(server)` 仍不收 `AbortSignal`(d.ts 逐字)⇒ 期限到点后底层重拨**继续跑**,落定时
+ *    才释放它占的连接 / 子进程。这一口必须把这句话交代给调用方(reconnect 的 503 文案、契约 §G.7c)。
  * 迟到的落定(尤其迟到的 reject)挂一条吞掉,免得没人 await 它时变成未处理拒绝。
  */
 export declare function raceDeadline<T>(work: Promise<T>, deadlineMs: number): Promise<T>;