@sema-agent/sdk 26.1.0 → 27.0.0

package/README.md

@@ -31,6 +31,8 @@ for await (const ev of client.runs.events(task.taskId)) {
 }
 ```
 
+`maxRetries` (default `2`) is how many *more* times a retryable request (a GET read, a keyed submit) may be sent after the first. It must be a non-negative integer — `0` sends every request once — and `new AgentClient` / `new ControlClient` throws on a negative, `NaN`, fractional or infinite value, or on a non-number (a numeric string such as `"2"` included; `null` / `undefined` are read as absent, so the default `2` applies).
+
 ## Surface
 
 - `client.tasks` / `client.runs` — submit, durable runs, SSE event streams with resume.
@@ -102,7 +104,7 @@ for await (const ev of client.runs.events(task.taskId)) {
 A separate subpath (**types + pure functions, zero runtime dependency**) mirroring `@sema-agent/server/model-route-env`: `MODEL_ROUTE_ENV_KEYS` (the closed set of
 env names that steer model routing), `readModelRouteEnv(env)` (a pure reader: env record in, a typed `ModelRouteEnvReading` out — it never touches `process.env`),
 `envLaneTable(mainId, main, cheap)` (the env leg's entry table: the main slot under `default` and its own id, plus the minted cheap slot) and `laneAndEndpointFor(env, model, routes)`
-(which brain lane a model takes on a route table, and which env key *names* carry that lane's endpoint and credential — names, never values). A shell or an embedder that needs the same routing facts as the server depends on **this**, never on the
+(which brain lane a model takes on a route table, and which env key *names* carry that lane's endpoint and credential — names, never values). On the Anthropic lane the two credential names are mutually exclusive — `ANTHROPIC_API_KEY` is sent as `x-api-key`, `ANTHROPIC_AUTH_TOKEN` as `Authorization: Bearer`, and the lane carries exactly one — so `laneAndEndpointFor` **throws** the server's startup refusal sentence (`[config.anthropic_credential_conflict] …`) when both are set (server ≥ 7.136.0; earlier servers let `ANTHROPIC_AUTH_TOKEN` win silently). A shell or an embedder that needs the same routing facts as the server depends on **this**, never on the
 server package, and never re-types the key names; the mirror is watched by a same-source gate (exports, constants, a differential run of the reader over several hundred env
 cases, the lane matrix, and the `.d.ts` type bodies) against the server's *published bytes*.
 
@@ -135,6 +137,84 @@ The registry's 409 carries two opposite meanings, split by one reader (`classify
 `ScopeGoneError` on the registry subpath — the target scope was deleted or re-created under the same name, nothing was
 written, **never** retry it as a conflict).
 
+## 27.0.0 — BREAKING changes(待发包;对表 server **7.136.0** 发布字节〔tag v7.136.0 = 0c4fcc35,shasum 77563635f167d9394f38189e1b8becad10e9b896〕与它自己解析到的引擎 core **7.55.0**〔契约包 14.5.0〕;公开类型面只加不删,**破坏点八处:子路径 `@sema-agent/sdk/model-route-env` 的 `laneAndEndpointFor` 在一个原先可答的输入上改为抛;输出型 `ParkedDecideAccepted` 放宽为联合;导出守卫 `isApprovalRequestFrameV1` 对卡上集外的 `approvalCard` 由判是改判否;`sessions.head` 不带 `etag` 而对端答 304 时由答 `{ changed: false }` 改为抛 `APIError`;取消律收紧(已 abort 的调用不再发出、失败的拒因改为 `signal.reason`);JSON 请求遇带 `permanence: "terminal"` 的可重试状态(server 放在 503 上)不再重试;`principalHeader` 撞传输层 / 条件请求 / 连接层的头名时构造即抛;`maxRetries` 不是非负整数时构造即抛**)—— 唯一 server 支持底线 **`7.52.0`**(不抬)
+
+**一句话**:server 7.136.0 把 anthropic 腿的两个凭据名读成各走各的头(`ANTHROPIC_API_KEY` ⇒ `x-api-key`,`ANTHROPIC_AUTH_TOKEN` ⇒ `Authorization: Bearer`)并互斥 —— 两把都非空 ⇒ 起服拒启,值级端口 `laneAndEndpointFor` 在这一形上抛起服那同一句拒句,不再答 `ANTHROPIC_AUTH_TOKEN`(≤7.135.x 的读法是 `ANTHROPIC_AUTH_TOKEN` 压过 `ANTHROPIC_API_KEY`,`x-api-key` 被静默丢弃)。同版对表 server 7.136.0 的 wire 面:呈卡帧的 `card` 带引擎卡词 `approvalCard`、运维队列行与订阅流 `pending` 帧带技能卡三位(`boundGrantDigest` / `boundGrants` / `classifierNoRuling`),外加一批值变 / 读法订正(复活不了的停驻行 deny 出路、收件箱 `objective` 改读 run 行预览、凭据位闭集再加四位、图片 URL 带凭据拒、`a2aPeers` 坏形拒、会话同步拉取口库断连 503、会话标题不可见字符拒、elicitation 没人应答统一 `cancel`)。
+
+**为什么是 major**:`laneAndEndpointFor` 是子路径的公开导出,它在 anthropic 腿两把凭据同设的输入上由「答 `ANTHROPIC_AUTH_TOKEN`」改为「抛」—— **一个原先可答的输入现在抛**,旧读法不留(零别名、零旋钮);按 `docs/RELEASE.md` 的 BREAKING 读法走 major(「行为面 BREAKING」一条)。**第二个破坏点**:输出型 `ParkedDecideAccepted`(停驻腿 `/decide` 的 200 回执)放宽成两臂联合(受理形 ∪ server ≥7.136.0 的作废形),读它的消费方里把 `status` 当字面 `"resuming"` 的窄写法编不过、按 `status` 的穷举 switch 要补一臂 —— RELEASE.md 的「输出型放宽」一条。**第三个破坏点**:导出守卫 `isApprovalRequestFrameV1` 对 `card.approvalCard` 按闭集成员判 —— 卡上带集外词(或非串)的帧,26.1.0 判是(那时不看卡上这一位)、本版判否(随包 spec 同判:`ApprovalCard.approvalCard` 是闭枚举)—— RELEASE.md 的「改答」一条。**第四个破坏点**:`sessions.head` 不带(或空串)`etag` 而对端答 304 —— 26.1.0 答 `{ changed: false }`(`etag` 是空串或 `undefined`,型却说它是串)或抛 `TypeError`(不传第二参时),本版按「304 只答条件请求」抛 `APIError`(status 304);子路径 registry 的 `getEffective` 同一条(不带 `etag` 收 304:26.1.0 答 `{ status: 304 }`,本版抛 `RegistryApiError`)—— RELEASE.md 的「改为抛」一条;只在对端违反 HTTP 语义(对没带校验头的请求答 304)时可达。**第五个破坏点**:取消律收紧 —— 子路径 `RegistryClient` / `fleet.snapshot()` 的已 abort 调用不再发出、飞行中 abort 的拒因改为调用方的 `signal.reason`(`AbortSignal.timeout()` 下由 `AbortError` 变 `TimeoutError`);registry 读体时 abort、设备码轮询环首 abort、重试器读错误体时 abort 的拒因同改为 `signal.reason`(逐形见下)—— RELEASE.md 的「改答」一条。**第六个破坏点**:JSON 请求遇带 `permanence: "terminal"` 的可重试状态(server 放在 503 上)不再重试(26.1.0 照状态重试、对端随后答 200 就答了;本版只发 1 次、抛按状态与码映射的类型错)—— RELEASE.md 的「改为抛」一条;只在店先判 terminal、随后又答成功时可达。**第七个破坏点**:构造参数 `principalHeader` 撞传输层自己装的头、条件请求头或连接层的头名时构造即抛(26.1.0 照用)—— RELEASE.md 的「改为抛」一条。**第八个破坏点**:构造参数 `maxRetries` 不是非负整数(负数 / `NaN` / 非整数 / `Infinity` / 非数值〔含数字串;`null` / `undefined` 读作缺席〕)时 `AgentClient` / `ControlClient` 构造即抛(26.1.0 照收 —— `1.5` 当 `2` 用、`Infinity` 无限重试、`≤ -1` 的负数与 `NaN` 让会重试的调用一发不发,`-1 < 值 < 0` 当 `0` 用,数字串 `"2"` 被拼进算术〔`"2"` + 1 = `"21"`〕、持续可重试失败时发 21 次)—— RELEASE.md 的「改为抛」一条。公开类型与随包 spec 的**形**没有删、没有改名、没有收窄(唯一例外是第三点那一位:随包 spec 的 `ApprovalCard.approvalCard` 闭枚举)。server 7.136.0 的升级说明另有两条嵌入方类型面 BREAKING —— 自建装配 server 的人给 `ServiceDeps.webAdminJwtVerifier` 写的验证器(成功身份的 `scope` 必填、失败词多 `scope_claim_missing`)、`StoreBackend.runOneTimeMigrations()` 的返回型 `OneTimeMigrationReport` 去两键 —— 它们**不在本包公开面上**(本包是客户端,不镜像这两只型),零动作。
+
+**消费方**:@client-core · @cli · @web-client · @web-admin(凡在引擎起之前调 `laneAndEndpointFor` 预判 anthropic 腿凭据键的壳 / 客户端运行时;读审批队列 / 订阅流 / 收件箱的壳)。
+
+**对表物**:根 devDep `@sema-agent/server` 精确钉 **7.136.0**(装树字节 = registry tarball,`diff -r` 逐文件同;随装 core 7.55.0、契约包 `@sema-agent/settings-schema` 14.5.0);live 围栏 `CALIBRATED_SERVER_HEAD` 7.135.0 → **7.136.0**(校准账逐面写在 `test/live/_fence.ts` 的校准注里)。
+
+### 改(BREAKING)
+
+- **`laneAndEndpointFor(env, model, routes)` 的 anthropic 腿**:设了哪一把凭据,`apiKeyEnvName` 就是哪一把;空串 = 未设(不遮蔽另一把,也不构成同设);都没设 ⇒ `undefined`;**两把都非空 ⇒ 抛** `[config.anthropic_credential_conflict] both ANTHROPIC_API_KEY and ANTHROPIC_AUTH_TOKEN are set — they are two different credentials (ANTHROPIC_API_KEY is sent as the x-api-key header, ANTHROPIC_AUTH_TOKEN as Authorization: Bearer) and the Anthropic route carries exactly one; keep the one your endpoint expects and unset the other`(不回显任何值;端点声明与否都抛)。网关腿不看这两个名,同设也不判。
+- **镜像整段重镜**(公开面不变:运行时导出仍是四个名、类型导出仍是七个):三只公开函数与它们依赖的私有判官(`judgeAnthropicCredential` · `anthropicCredentialRefusal` · `anthropicLaneCredentialOf`,及 `declaredValue` / `csvOf` / `declaredRootUrl`)的声明 = server 发布字节 `dist/model-route-gap.js` / `dist/model-provider.js` 的同名声明,**去类型、去注释、去空白后逐字相等**(照发布字节抄、只补类型,一处不手改);唯一有意不逐字的是 `brainLaneFor`(server 调引擎 `brainLaneOf`,镜像零运行时依赖,按 `Object.hasOwn` 读同一张路由表原型)与 `DEFAULT_MODEL_REF`(server 从别的模块导入),两处的行为由同源锚门格③c / ④ 钉。
+- **`ParkedDecideAccepted` 放宽为联合**(输出型;server ≥7.136.0):`{ taskId, status: "resuming", decision: "approve" | "deny" }`(受理回执,复活在飞)∪ `{ taskId, status: "failed", decision: "deny" }`(**作废回执** —— 复活不了的停驻行〔后台子代省略了 `name` 的无名行 / 行上没有根会话锚〕上 deny = 作废这张卡,没有续跑在飞)。此前 `status` 恒为字面 `"resuming"`:把它当字面读的代码编不过,按 `status` 穷举 switch 补一臂 `"failed"`。随包 spec `ParkedDecideAccepted` 同形(两臂 `oneOf`),decide 200 描述与 `ApprovalDecisionResult` 同句 —— 一处读法。判别:`decision` 在场且 `sessionId` 缺席 = parked 回执,再看 `status` 分臂。**型别名改形**:它由 interface 改成联合型别名,所以 `interface X extends ParkedDecideAccepted` ⇒ **TS2312**、`class X implements ParkedDecideAccepted` ⇒ **TS2422**(改成 `type X = ParkedDecideAccepted & { … }`,或按臂各自声明)。
+- **`isApprovalRequestFrameV1` 判卡上的 `approvalCard`**(server ≥7.136.0 起卡上带引擎卡词):在场必须是 `TOOL_APPROVAL_CARD_WORDS` 的成员(与帧顶层同一座、同一张词表,型是闭集、spec 是闭枚举,守卫不比它们宽);集外词 / 非串 ⇒ **判否**(26.1.0 不看卡上这一位 ⇒ 判是)。判否的读法不变:走通用卡(安全元数据 + 人工 approve / deny),不是拒绝。缺席照旧判是(7.136.0 之前的行与引擎没铸卡词的卡)。**随包 spec 同判**:`ApprovalCard.approvalCard` 是闭枚举(卡本身仍是开放对象)—— 卡上集外词在 26.1.0 的 spec 下靠开放对象过校验,本版不过。
+- **`sessions.head` 不带 `etag` 时的 304**:304 只是条件请求的答案 —— 传了非空 `etag`(请求带 `if-none-match`)⇒ `{ changed: false }`,照旧;没传 `etag` / 空串(不发条件头)而对端答 304 ⇒ **抛 `APIError`(status 304)**(26.1.0:`head(id, {})` / `head(id, { etag: "" })` 答 `{ changed: false }` 且 `etag` 为 `undefined` / 空串,`head(id)` 抛 `TypeError`)。其余读口与 JSON 请求收到无条件的 304 本来就是类型错,不变。子路径 `@sema-agent/sdk/registry` 的 `getEffective` 同一条:不带 `etag` 而对端答 304 ⇒ 抛 `RegistryApiError`(status 304)(26.1.0 答 `{ status: 304 }`,叫调用方复用一份它没有的缓存)。
+- **取消律收紧**(只写真变了的):① 子路径 `RegistryClient` 与 `fleet.snapshot()`:signal 已 abort 的调用**不再发出**(26.1.0 原生 `fetch` 下也照发、照交回结果),飞行中 abort 以调用方的 **`signal.reason`** 拒(26.1.0 拒自己 controller 的平台 `AbortError` —— `AbortSignal.timeout()` 下由此变成 **`TimeoutError`**);② registry 子路径读体时 abort(`RegistryClient` / 设备码 / 刷新 / 登出):体被截断 ⇒ 以 `signal.reason` 拒(26.1.0:200 吞成 `undefined`、错误码丢、`refreshTokens` 抛 `TypeError`);读完的体从不因 abort 丢弃;③ 设备码轮询环首 / 间隔 abort:以 `signal.reason` 拒(26.1.0 自铸 `DOMException("polling aborted by caller")`;裸 `abort()` 名字仍是 `AbortError`);注入的 `fetch` 不听 `signal` 时,间隔里 abort 之后 27.0.0 不再发 device/token(0 次)、以 `signal.reason` 拒,26.1.0 睡满间隔后再发 1 次 —— 那次应答若是令牌就交回令牌,若是 pending / slow_down 则回到环首自铸 `AbortError`;④ `sessions.sync.entries()` 体阶段两次读之间 abort:以 `signal.reason` 拒(26.1.0 裸 `Error("sync: aborted")`;挂起的 read 上 abort 两版都是 `signal.reason`);⑤ 重试器:读错误体时 abort 以 `signal.reason` 拒,不论第几次尝试(26.1.0 原生 `fetch` 下:最后一次尝试〔或遇不可重试的状态〕抛读完体后铸的无码错 —— 5xx 是服务端错,4xx 是带状态的无码 `APIError`;体不跟 signal 的注入 fetch 读到完整错误体,抛带码的类型错),注入的 fetch 不听 signal 时已 abort 的调用不再调用它 —— **原生 `fetch` 下重试器本来就**不出网(`fetch` 见已 abort 即拒)、本来就以 `signal.reason` 拒(`AbortSignal.timeout()` 才是 `TimeoutError`)。已经到手的成功应答照样交回。谁需要:取消调用的壳 —— 已取消的调用此前还会发出去(`RegistryClient` / `fleet.snapshot()` 照样交回结果),失败时被报成服务端故障或平台 `AbortError`(调用方给的原因丢了)。谁受伤:靠「abort 之后还会拿到结果」或靠错误名 `AbortError` 写分支的调用方 —— 现在拒因是你给的 `signal.reason`(`AbortSignal.timeout()` ⇒ `TimeoutError`,不再是 `AbortError`)。补偿:按 `signal.aborted` / `signal.reason` 判,不按错误名;已经到手的成功应答照样交回(本包不丢弃它;原生 `fetch` 下 abort 落在读体期间时体读不完 —— 令牌换发这类一次性调用别挂会早早 abort 的 signal)。
+- **`permanence: "terminal"` 不重试**(JSON 请求 —— 经 `request()` 的 GET 与带键提交;原始读口在 26.1.0 本来单发):可重试状态的应答体上带 `permanence: "terminal"`(店判「修店之前重试没用」;server 把它放在 503 上)⇒ 只发 1 次,抛按状态与码映射的那只类型错(`503 state.*` 落 `ServiceStateError`;`err.extra.permanence` = `terminal`)。26.1.0 照状态重试至多 `maxRetries` 次 —— 对端若随后答 200,就答了;本版在同一输入上抛。只在店先判 terminal、随后又答成功时可达(对端自相矛盾,与第四点同一可达性口径)。谁需要:同步端与运维 —— 店已判修好之前重试无益,本包不再替调用方多打坏店(每次调用省至多 `maxRetries` 次请求与退避等待)。谁受伤:靠本包的自动重试穿过一次 terminal 503 拿到成功的调用方。补偿:接住那只类型错、看 `err.extra.permanence === "terminal"`,确要再试就自己重发(或先修店)。
+- **`principalHeader` 不许撞保留头**:构造参数 `principalHeader`(身份头的名字)落在传输层自己装的头(`authorization` / `content-type` / `idempotency-key` / `accept` / `last-event-id`)、RFC 9110 五只前置条件头(`if-none-match` / `if-modified-since` / `if-match` / `if-unmodified-since` / `if-range`)或连接层的头(`host` / `content-length` / `connection` / `transfer-encoding`)⇒ **构造 `AgentClient` 即抛**(26.1.0 照用 —— 身份值顶掉凭据 / 内容类型 / 去重键,或让每个请求都成了条件请求)。谁需要:所有调用方 —— 身份头一旦是条件头,304 判据与身份一起失真(无条件 GET 被读成「没变」);是凭据 / 内容类型头,则身份值顶掉它。谁受伤:把身份头名配成这十四只之一的部署(实际部署用的身份头名 —— `x-agent-principal` / `x-remote-user` / `x-forwarded-user` 之类 —— 都不在集内)。补偿:把 server 的 `principalHeader` 配置与本包同改成一个专用的头名;报错句点名整张闭集。
+- **`maxRetries` 必须是非负整数**:构造参数 `maxRetries`(`AgentClient` 与 `ControlClient`,同在传输层构造处一条规则)是负数、`NaN`、非整数、无穷或**非数值(含数字串 `"2"`;`null` / `undefined` 读作缺席、取缺省 `2`)** ⇒ **构造即抛**(26.1.0 照收 —— `1.5` 当 `2` 用〔至多 3 次尝试〕,`Infinity` 无限重试,`≤ -1` 的负数与 `NaN` 让会重试的调用〔JSON GET 与带键提交〕一发不发、拒成 `undefined`,`-1 < 值 < 0` 当 `0` 用,数字串 `"2"` 被拼进算术〔`"2"` + 1 = `"21"`〕、会重试的请求遇持续的可重试失败时发 21 次)。谁需要:所有调用方 —— 本版把五个原始 GET 读口也并进同一只重试器,同一个非法值会让它们也一发不发;构造期响亮拒,好过运行期拒成 `undefined`。谁受伤:把 `maxRetries` 配成这几类值的部署(尤其配置从环境变量读出的壳:`Number(...)` 读不到就成了 `NaN`,没转 `Number` 就是数字串 `"2"`;`0`、`1`、`2`… 与缺省 `2` 都不受影响)。补偿:改成非负整数;要关重试写 `0`(每个请求只发一次)。
+- 不变:`readModelRouteEnv` 的读数形(两把凭据原样交出,`anthropicRouteMounted` 仍是「任一在场」)。同源锚门(`test/live/model-route-env-mirror.test.ts`)的准入由「server ≥ 7.133.0」抬为「server ≥ 7.136.0」:更老的发布字节在同设输入上答一把,不是这面镜像的对端,整只文件 SKIP。
+
+### 加(additive)
+
+- **`ApprovalCard.approvalCard?: ToolApprovalCardWord`**(server ≥7.136.0)+ `APPROVAL_CARD_KEYS` 加 `"approvalCard"` + 随包 spec `ApprovalCard.approvalCard`:引擎卡词进卡 —— 活铸 `approval_request` 帧的 `card`、落库的 `card_json` 信封、断连重放帧的 `card` 三面同源(活铸帧上与帧顶层是同一个词;重放帧顶层十位全缺,只有卡上这一份);此前重放帧没有这一位,断线重连后壳退化成通用卡。缺席 = 引擎没铸 / 7.136.0 之前落下的行,**不编 `generic`**。`isApprovalRequestFrameV1` 对 `card.approvalCard` 按闭集成员判(集外词判否 ⇒ 走通用卡,不是拒绝;这是本版第三个破坏点,见上「改(BREAKING)」)。卡信封是严格的耐久形:7.135.x 副本读不动带本键的新行(重放跳过、幂等重入走耐久停驻)—— 升级请整队一次滚完。
+- **`PendingCheckpoint` 与 `ApprovalStreamEvent`(`pending` 帧)的 `boundGrantDigest?` / `boundGrants?` / `classifierNoRuling?`**(server ≥7.136.0)+ 随包 spec 两处同声明:停驻的技能卡在运维队列行与订阅流上补上「批它放行了什么」—— 三位由**一只**投影投队列行、流帧与收件箱行,同一张停驻行三面逐字相等;值是引擎对这一行投的检查点摘要,server 不重算哈希(清单只在哈希等于摘要时才发布)。`boundGrants` 是部署文本,渲染按上下文转义。在场才带,普通卡缺席;`card_json` 仍不带。
+
+- **GET 读口同律:`AgentClient` / `ControlClient` 的全部 GET 读口进同一只重试器**(行为面;两只 client 共用同一个传输层)。**行为变化:请求次数与失败时机变了** —— 五个读口(`entries()` / `getHistoryBlob()` / `attachments.get` / `sessions.head` / `metrics.prometheus`)此前单发,可重试状态或网络错一发即拒;现在先重试至多 `maxRetries` 次:一次瞬时失败之后的成功由「抛」变成「答」,持续失败则拒得更晚(多等至多 `maxRetries` 轮退避)。**这不是破坏点**:`docs/RELEASE.md` 写的行为面 BREAKING 是「导出函数在原先可答的输入上改为抛 / 改答」,而这五个读口上原先答得出的输入(首发即 2xx、条件请求的 304)答案不变(`sessions.head` 无条件请求收 304 一形除外,那是第四个破坏点;及第五点的已 abort 调用 —— 注入的 `fetch` 不听 `signal` 时,四个口(`sessions.head` / `metrics.prometheus` / `attachments.get` / `getHistoryBlob`)在 26.1.0 发 1 次并答,本版五个口都发 0 次、以 `signal.reason` 拒;`entries()` 在 26.1.0 就已拒(`sync: aborted`));要旧行为设 `maxRetries: 0`(它是整只 client 的旋钮:同时关掉这只 client 上 JSON GET 与带键提交的重试;只想让这五个口单发,给它们单开一只 `maxRetries: 0` 的 client)。下面是读法:会话同步三条拉取读腿 `manifest()` / `entries()` / `getHistoryBlob()`,**加上原先单发的三个一次性读口 —— 附件下载 `attachments.get`、会话轻探针 `sessions.head`(条件 GET)、Prometheus 文本 `metrics.prometheus`** —— 与 `request()` 的 JSON GET 读同一只重试器、同一个 `maxRetries`:可重试状态 ∧ server 没说「重试改不了判」(码不在确定性失败码表、体上 `permanence` 不是 `"terminal"`;`503 state.file_history_unreadable` + `permanence: "transient"` 是典型形)由本包重试,**只在首字节之前**(开流 / 开 blob / 开下载的那一次请求);**`permanence: "terminal"`(店判「修店之前重试无益」)不重试**(各腿只发 1 次,同一只判官读 server 放这件事的两处:码表与这个键),键缺席(店没判)按状态矩阵照旧;耗尽后抛 `ServiceStateError`(`permanence` 在 `err.extra`)。**304 只是条件请求的答案**:`sessions.head` 带 `etag` 时重试发的每一次都带 `if-none-match`,304 读作没变、不重试;没带条件头的请求收到 304 ⇒ 类型错 `APIError`(status 304)—— 其余读口与 JSON 请求与 26.x 同,不带 `etag` 的 `head` 是本版第四个破坏点(见上「改(BREAKING)」)。**`timeoutMs` 管 JSON 请求的每一次尝试(含读体);原始读口(`entries()` / `getHistoryBlob()` / `attachments.get` / `sessions.head` / `metrics.prometheus`)的开请求没有逐次超时**(与 26.x 同:逐次超时是交给 `fetch` 的那只 signal,它同时管响应体、到点不可撤,套上会把长体截断),要限时传 `signal`(如 `AbortSignal.timeout(ms)`)。子路径 `@sema-agent/sdk/registry` 的 `RegistryClient` 是另一只薄引擎(401 刷新后重发一次,不做网络重试),不在这条律里。`ControlClient` 的错误(控制面 `ControlError`)不带码、不带 `permanence`,只按状态矩阵重试 —— 码表与 `permanence` 两条只对工作面(`AgentClient`)的应答起作用。长连接 SSE 流**不是**读口(断了按 `Last-Event-ID` / 游标续传,由调用方的环重开)。**取消律**:调用方 `signal` abort ⇒ 退避等待立即中止、不再发请求,以 `signal.reason` 拒(`abort()` 不带原因 ⇒ `AbortError`;`AbortSignal.timeout()` ⇒ `TimeoutError`;显式 `abort(x)` 原样是 `x`,含 `null`);**已 abort 的调用不发**:调用方的 signal 一路交到 `fetch`(单发口原样交出 —— 原生 `fetch` 见已 abort 即拒、不出网);会重发的重试器每次尝试前查,把 signal 桥到自己 controller 的子路径 `RegistryClient` 与 `fleet.snapshot()` 发前也查(此前这两处照发、照交回);**飞行中 abort 而请求以失败告终 ⇒ 以 `signal.reason` 拒**(重试器:请求在途、读错误体期间,**不论第几次尝试** —— 此前最后一次尝试抛读完体后铸的服务端错,已取消的调用被报成故障;`RegistryClient` / `fleet.snapshot()` 此前拒的是自己 controller 的平台 `AbortError`);**已经到手的成功应答照样交回**(本包不因取消丢弃它;但原生 `fetch` 把 signal 绑在响应体上,abort 落在读体期间时体本身读不完 —— 令牌换发这类一次性调用别挂会早早 abort 的 signal);**扩到本包每一处退避 / 轮询睡眠**(同一只 `sleep`):SSE 续读环(`parseSse` / `parseFrameStream`)与 `approvals.stream` 的重连退避、设备码轮询的间隔,abort 时也立即醒(此前睡满;原生 `fetch` 下 abort 后本来就不再发请求),流环安静结束、设备码轮询以 `signal.reason` 拒(裸 `abort()` 时名字仍是 `AbortError`;调用方取消不盗用服务端码);这一条的「已 abort 不发 / 失败拒因 = `signal.reason`」是本版第五个破坏点(见上「改(BREAKING)」)。**边界**:构造时注入的 `fetch` 若不听 `signal`,请求与读体何时结束由它自己决定 —— 单发口上已 abort 的调用照发,读响应体时(错误体、SSE 心跳看门狗等下一块字节)要等体自己结束(SSE 等心跳宽限到点:默认 45 s,`sessions.watch` 60 s);原生 `fetch` 下这些都立即结束。本包目前不在 abort 时主动取消读者(已知缺口)。**另一处例外 —— 子路径 `RegistryClient` 的共享刷新**:401 后的令牌刷新是单飞的(并发的 401 共用一次);请求加入一次在飞的刷新后再被 abort,**不会**立即以 `signal.reason` 拒,而是等这次刷新落定 —— 刷新失败 ⇒ 以**刷新自己的错误**拒(不是 `signal.reason`),刷新成功 ⇒ 不再重发、以 `signal.reason` 拒;**另一面**:刷新用的是发起它的那个请求的 `signal` —— 发起者 abort ⇒ 刷新随之取消(`fetch` 听 signal 时),加入这次刷新的别的请求哪怕自己没 abort,也以**发起者的 `signal.reason`** 拒(abort 落在刷新请求在途时两版同;落在读刷新应答体时 26.1.0 拒 `TypeError`,见上「改(BREAKING)」第五点②)(已知缺口)。**射程 = 所有 JSON 请求(同一只重试器),不只这几条腿**:相对 26.x,`manifest()` 与其余经 `request()` 的 GET / 带键提交也变了 —— `permanence:"terminal"` 的 503 由 3 发变 1 发;`signal` 已 abort 的调用一次都不发、不调 `fetch`(此前交给 `fetch`:原生 `fetch` 当场拒、不出网,不听 signal 的注入 fetch 会发一次);退避期间 abort 立即拒(此前睡满退避,至多挂满 `Retry-After` 的 60 s 上限);方向都是请求更少、拒得更快。体读到一半断了**不重试**(`entries()` 缺结尾行 ⇒ `SyncTruncatedError`,带 `afterSeq` 重开续读)。**此前单发**的是 `entries()` / `getHistoryBlob()` / `attachments.get` / `sessions.head` / `metrics.prometheus` 五个读口(同一台假 503 服务器上调用次数 1,现在 3;terminal 仍是 1)。实现:`Transport.request()` 与 `Transport.openRawGet()` 共用唯一的重试器,有界体的原始 GET 读口一律走后者(结构钉扫 `src/` 里 `openRaw({ method: "GET" })` 的调用点,只剩 SSE 流)。
+
+### 值变 / 读法订正(不改公开型)
+
+- **收件箱行 `InboxRow.objective`**:≥7.136.0 是门所属 run 行的 `objectivePreview`(写入时已脱敏、约 120 字符、与 `GET /v1/assistant/tasks` 同一列),**`null` = 读不到预览**(没有 run 账本是原因之一;读那一行失败、委派链断了或超 8 跳、run 行没有预览也回 `null` —— 本键不分辨是哪一种,别读出单一原因);此前是停驻上下文里存着的目标原文。**7.136.0 服务端没有全量目标读口**(`GET /v1/runs/:id` 不带 `objective` / `objectivePreview`)—— 本键就是预览;全量读口随 server 后续版本,届时本包锁步,本包不编造替代路径。
+- **复活不了的停驻行**(后台子代省略 `name` 的无名行 / 行上没有根会话锚):deny = 作废这张卡(`200 { taskId, status: "failed", decision: "deny" }` —— `ParkedDecideAccepted` 的作废臂,见上「改(BREAKING)」),approve 仍 `409 decide.row_unrevivable`(句尾指路 deny)。
+- **`409 conflict.checkpoint_ctx_unsealable` 的凭据位闭集再加四位**:stdio MCP 传输与 command hook 条目的 `command` / `args`(`args` 整只数组封成一个值);错误类注补坐标与 7.135.x / 7.136.0 混跑时的两个读数(`plaintext` / `unrecognized_seal`)。
+- **请求面**:`images[i].url` 带凭据 ⇒ `400 request.field_invalid`(第六座,同一对 `reason`);`a2aPeers` 的列表 / 条目 / 键值写坏在新提交上 ⇒ `400 request.field_invalid`(**只有句子、不带 `field` / `reason`**;带凭据的 url 与超 32 条才带;词表外的键 ⇒ `400 request.body_shape` + `unknownKeys`;续跑重放腿仍降级);`mcpServers` 超 32 条改走全仓同一形的撞帽拒(体多机读位);`PATCH /v1/sessions/:id` 与 2c 导入的 `title` 只含不可见字符 ⇒ `400 request.field_invalid`。
+- **会话同步三条拉取读腿**(`GET …/sync/manifest` · `GET …/sync/entries` 开流前 · `GET …/sync/history/blobs/:hash`):库断连统一答 `503 state.file_history_unreadable` + `permanence: "transient"`(此前落通用 `500 internal.error`;三条腿的开请求本包都自动重试,见上「加」);文件历史店故障的 `422 adopt_failed` 等店答在连接类故障上也带 `permanence: "transient"`。码名里的 `file_history` 是出身,动作只看 `permanence`。
+- **elicitation 没人应答的释放**(答题窗到期 · run 中止 · 腿退出时仍挂着 · 开帧没送达)统一 `cancel`,`decline` 只留给「拒」:`elicitation_complete.action` 的型本就含三词,到期那一帧由 `decline` 变 `cancel`。
+
+### 🔴 迁移表(26.x 的写法 → 本版 → 怎么改)
+
+| 26.x 的写法 | 27.0.0 | 怎么改 |
+|---|---|---|
+| `laneAndEndpointFor(env, model, routes).apiKeyEnvName` 对 `ANTHROPIC_API_KEY` 与 `ANTHROPIC_AUTH_TOKEN` 同设的 env 读到 `"ANTHROPIC_AUTH_TOKEN"` | **抛** `[config.anthropic_credential_conflict] …`(旧答案不留) | 调用前把 env 收成只留端点期望的那一把(要 Bearer 留 `ANTHROPIC_AUTH_TOKEN`,要 `x-api-key` 留 `ANTHROPIC_API_KEY`),或接住这一抛;要在调用前自己判:`readModelRouteEnv(env)` 的 `anthropicApiKey` / `anthropicAuthToken` 同时非 `undefined` 即同设 |
+| 把 `InboxRow.objective` 当目标全文(全文展示、按全文匹配) | run 行的 `objectivePreview`(约 120 字符,已脱敏) | 7.136.0 服务端没有全量目标读口:只能展示预览;全量读口随 server 后续版本,届时本包锁步 |
+| 把 `ParkedDecideAccepted` 当恒受理(`const s: "resuming" = r.status` / 只判 `status === "resuming"`);或 `interface X extends ParkedDecideAccepted` / `class X implements ParkedDecideAccepted` | 联合型别名:`"resuming"` ∪ 作废回执 `"failed"`;`extends` ⇒ TS2312、`implements` ⇒ TS2422 | 按 `status` 分臂;`"failed"` = 卡已作废、没有续跑在飞,别等复活;`extends` / `implements` 改成 `type X = ParkedDecideAccepted & { … }` 或按臂各自声明 |
+| `sessions.head` 不带非空 `etag`(`head(id)` / `head(id, {})` / `head(id, { etag: "" })`)遇对端答 304 时读 `{ changed: false }`(或接 `TypeError`) | 抛 `APIError`(status 304) | 轮询传上一次的非空 `etag`;没有 `etag` 时的 304 是对端违反 HTTP 语义,按类型错处理(别当「没变」) |
+| 靠「abort 之后还会拿到结果」写流程,或按错误名 `AbortError` 判取消 | 已 abort 的调用不发;abort 之后的失败以 `signal.reason` 拒(`AbortSignal.timeout()` ⇒ `TimeoutError`) | 按 `signal.aborted` / `signal.reason` 判取消,不按错误名;一次性调用(令牌换发)别挂会早早 abort 的 signal |
+| `new AgentClient({ principalHeader: "<传输层 / 条件请求 / 连接层的头名>" })` | 构造即抛 | 身份头换一个专用名(server 侧 `principalHeader` 同改) |
+| `new AgentClient({ maxRetries: <负数 / NaN / 非整数 / Infinity / 非数值(含数字串;`null` / `undefined` 读作缺席)> })`(`ControlClient` 同) | 构造即抛(句子点名 `maxRetries` 与收到的值) | 改成非负整数;要关重试写 `0`(每个请求只发一次) |
+| 靠这五个读口(`entries()` / `getHistoryBlob()` / `attachments.get` / `sessions.head` / `metrics.prometheus`)一发即拒:429 / 503 / 网络错时立刻拿到错误 | 先重试至多 `maxRetries` 次再拒(退避按 `Retry-After`,封顶 60 s);一次瞬时失败之后的成功现在直接答 | 无动作;要旧行为设 `maxRetries: 0`(一发即拒,`retryAfterMs` 留在错误上;整只 client 的旋钮,同时关掉 JSON GET 与带键提交的重试 —— 只想让这五个口单发,给它们单开一只 `maxRetries: 0` 的 client);要限时传 `signal` |
+| 靠本包自动重试穿过带 `permanence: "terminal"` 的可重试状态(server 放在 503 上;随后对端答 200) | 只发 1 次,抛按状态与码映射的类型错(`503 state.*` ⇒ `ServiceStateError`;`extra.permanence` = `terminal`) | 确要再试:接住它、自己重发(或先修店) |
+| `getEffective(client)` 不带 `etag` 遇对端答 304 时读 `{ status: 304 }` | 抛 `RegistryApiError`(status 304) | 带上一次的非空 `etag` 做条件请求;没有缓存就别把 304 当「没变」 |
+| 用 `isApprovalRequestFrameV1` 判帧、卡上 `approvalCard` 是集外词或非串(26.x 判是) | 判否(走通用卡) | 卡词随引擎加员时把本包锁步升级到认得新词的版本;判否的帧按通用卡渲染(安全元数据 + 人工 approve / deny),别当拒绝 |
+| 按「deny ⇒ `409 decide.row_unrevivable`」写分支 / 告警 | 无名 / 无根会话锚行的 deny ⇒ `200`,`status: "failed"` | 按 `status` / `errorCode` 分支,不按句子 |
+| 把会话同步三条拉取读腿的 `500` 当终局失败 | 库断连 ⇒ `503 state.file_history_unreadable` + `permanence: "transient"` | 三条腿的开请求本包都自动重试(首字节前、至多 `maxRetries` 次;`permanence: "terminal"` 不重试);耗尽后按 `permanence` 稍后再来;体读到一半断了不重试(`afterSeq` 续读) |
+
+### 🔴 升级须知(三问;行为面)
+
+1. **同设两个 anthropic 凭据名时 `laneAndEndpointFor` 抛**。谁需要:锁步 server 7.136.0 —— 起服对这一形已拒启,壳首启 / 客户端运行时在引擎起之前预判的读口必须同一读法,否则「壳读到的凭据键」与「引擎实际带的头」分叉。谁受伤:对同一份 env 同时设了 `ANTHROPIC_API_KEY` 与 `ANTHROPIC_AUTH_TOKEN` 并调用 `laneAndEndpointFor` 的嵌入方(此前答 `ANTHROPIC_AUTH_TOKEN`,现在抛;对这样的 env 起 server 7.136.0 本来也拒启)。补偿:拒句点名两键与出路 —— 只留端点期望的那一把、另一把 unset;只设一把的部署读数不变。
+2. **收件箱 `objective` 变预览**。谁需要:所有读收件箱的壳(目标里的凭据形不再原样回给调用方,两只分诊视图对同一任务显示同一句)。谁受伤:把 `objective` 当完整目标用的壳。补偿:7.136.0 服务端没有全量目标读口 —— 按预览展示;`null` 读作「读不到预览」(原因不止一种,含没有 run 账本与读失败,本键不分辨);全量读口随 server 后续版本、届时本包锁步。
+3. **停驻审批的 deny 出路(`ParkedDecideAccepted` 联合)与同步拉取的 503**。谁需要:用未命名后台子代、审批会停驻的部署(这张卡第一次处理得掉);同步端(库抖动时拿到可机读的「稍后重试」,值班按 `internal.error` 告警的运维不再被库断连误报)。谁受伤:按旧 409 / 500 写了分支的消费方。补偿:按 `status` / `errorCode` / `permanence` 分支。
+4. **新提交上写坏的声明改拒**(`images[i].url` 带凭据 / `a2aPeers` 坏形 / 只含不可见字符的会话标题)。谁需要:凭据不再落停驻上下文 / run 行 / 日志;写坏的声明不再换回「生效了」的 200。谁受伤:此前靠「写坏了也 200」混过去的请求。补偿:按 `errorCode` / `field` / `reason` / `unknownKeys` 改对那一格(图片字节改走内联 `{ data, mimeType }`);续跑重放腿不拒。
+5. **`isApprovalRequestFrameV1` 对卡上集外 `approvalCard` 判否**。谁需要:按卡词分支渲染的壳 —— 守卫判是就承诺整张卡成形,卡上一个本包不认识的卡词判是会让壳按一个不存在的卡分支(或落进没写的 `default`)。谁受伤:用这只守卫判帧、而对端 server 的引擎比本包新(卡上有本包词表外的新卡词)的消费方 —— 这些帧此前判是、现在判否(走通用卡)。补偿:卡词随 core minor 加员时本包同批加入词表,锁步升级即回到判是;判否的读法本来就是「走通用卡」,不丢审批能力。
+6. **五个读口改重试**(`entries()` / `getHistoryBlob()` / `attachments.get` / `sessions.head` / `metrics.prometheus`;此前单发;行为变化,不属破坏点)。谁需要:同步端与下载方 —— 库抖动 / 中间层 503 时拿到的是一次重试后的成功,而不是让调用方各自写一层重试。谁受伤:按自己节拍轮询 `sessions.head` 的壳(`sessions.watch` 在 SSE 帽满时就让它回落轮询 `/head`)—— 对端答 429 / 503 + `Retry-After` 时,一次 `head` 会被本包挂住至多 `maxRetries` 轮 `Retry-After`(每轮封顶 60 s;实测 503 + `Retry-After: 2` 下 26.1.0 约 0.3 s 抛、本版约 4.1 s、3 次请求后抛),叠在调用方自己的退避之下;对端卡死时原始读口本来就没有逐次超时(与 26.x 同);`fetch` 自己拒的形(如 `etag` 含非法头字符)与网络错同为 `TypeError`,同样按网络错重试(此前单发、一次就拒)。补偿:构造时 `maxRetries: 0`(回到单发,一次就拒、拿得到 `retryAfterMs` 自己排期;这是整只 client 的旋钮,同时关掉它上面 JSON GET 与带键提交的重试 —— 只想让这五个口单发,给它们单开一只 `maxRetries: 0` 的 client)· 每次调用传 `signal`(如 `AbortSignal.timeout(ms)`;退避中 abort 立即以 `signal.reason` 拒,不睡满)。
+7. **`sessions.head` 不带 `etag` 时的 304 改抛**。谁需要:所有读 `head` 的壳 —— 304 只在条件请求上是「没变」;对没带校验头的请求答 304 的对端是坏的,26.1.0 把它读成「没变」并交回空串 / `undefined` 的 `etag`(型说是串),轮询方拿它当下一次的 `etag` 就一直带着坏值。谁受伤:不传 `etag` 调 `head`、而对端(或中间缓存层)对无条件请求答 304 的部署 —— 此前得到 `{ changed: false }`,现在接到 `APIError`。补偿:轮询时传上一次读到的非空 `etag`(这是 `head` 的本意);接住 `APIError` 的 `status === 304` 即可识别这类对端。
+8. **`maxRetries` 非法值构造即抛**。谁需要:所有调用方 —— 尤其把环境变量 / 配置中心的值直接喂给 `maxRetries` 的壳(`Number(process.env.X)` 读不到是 `NaN`)。谁受伤:配成负数 / `NaN` / 小数 / `Infinity` / 数字串(环境变量原样传入的 `"2"`)的部署 —— 升级后在构造处响亮失败(此前 `NaN` / `≤ -1` 的负数让会重试的调用一发不发、拒成 `undefined`;`-1 < 值 < 0` 当 `0` 用,小数、`Infinity` 照跑,数字串被拼进算术、会重试的请求遇持续的可重试失败时发 21 次)。补偿:改成非负整数;`0` = 每个请求只发一次。
+
+### 门 6(对已发布字节的契约套)
+
+server 7.136.0 发车链门 6 首跑(对 26.1.0 基线,主树):17 文件 / 196 过 / 2 红 / 1 跳 —— `fence-calibration`(fixture 7.136.0 高于已核账 head 7.135.0)· `model-route-env-mirror` 格③c(同设行镜像仍答 `ANTHROPIC_AUTH_TOKEN`)。本版两格都转绿:head 抬到 7.136.0(校准账逐面核了 7.136.0 的 wire 清单,见 `_fence.ts`),镜像照发布字节重镜。对 7.136.0 发布字节整套:17 文件 / 200 格 = 199 过 / 1 跳(`server-7109-faces` 一格既有 skip)/ 0 红。抬 devDep 到 7.136.0 后默认套的邻居文件另有四处被发布字节抬动的旧钉按真相翻面(无 server 回归):键集对账门表 3(卡上多 `approvalCard`)· 收件箱技能卡投影搬到一只共用投影 · URL 凭据判官上移到契约包根 · 一条 PG 说明串里的 `read_only` 字样登记。
+
+### 未闭环
+
+- 全量目标读口缺席:server 7.136.0 的升级说明让消费者去 run 的单条详情读面取全量目标,但该读面没有这个字段(server 侧订正随其后续版本),本包不编造替代路径,读口出现时锁步。
+- server 7.136.0 的升级说明另有两条嵌入方类型面 BREAKING(`webAdminJwtVerifier` 验证器的 `scope`、`OneTimeMigrationReport` 去两键)与本包公开面无交集(本包是客户端),零动作。
+- 同源锚门对三只函数 + 私有判官只在**行为**上逐条对拍(含抛与句子);「声明逐字同」本版是照发布字节重镜后一次性核过,尚无常驻的函数体对拍格 —— server 对这几只函数做纯重构(行为不变)时,镜像不会红。
+
 ## 26.1.0 — minor(待发包;对表 server **7.135.0** 发布字节〔tag v7.135.0 = e1ea5bd2,shasum bfd57921eb6ac33644a23935599209e590a2cc0a〕与它自己解析到的引擎 core **7.55.0**;型面与随包 spec **加性或值变**:零删 / 零改名 / 零收窄的公开型,spec 工具未判出 BREAKING)—— 唯一 server 支持底线 **`7.52.0`**(不抬)
 
 **一句话**:对表 server 7.135.0 的 wire 加性 / 值变面 —— `GET /v1/models` 顶层 `aliases`、`workflow_complete.completionId`、按问读口 `parked.reopened`、会话规则 `operatorRules` 与三个能力位、请求键 `projectMemory`、URL 带凭据拒的两个新 `reason` 与五座 `field` 坐标、会话同步的 `permanence` / `adopt_failed` / `missing_blob` 第一阶段、workflow `parked` 位与 `workflow.journal_incompatible`、场景卡 `skills[]`、`wiring_manifest.sessionRules` / `projectMemory`、`tool_end.gate.disposition.clearedBy`、`persistedRule.match` 加 `pattern`、`advisor.not_attached` 与 side-query 失败体三位;外加门 6 在已发布字节上的校准。

package/dist/abort.d.ts

@@ -0,0 +1,25 @@
+/**
+ * 取消律的三件原语 —— 调用方 `signal` abort 之后,本包既不再睡、也不再发。**一处定义**:重试器(`transport.ts`)、SSE 续读环(`sse.ts`)、审批流重连环(`resources/approvals.ts`)、
+ * 设备码轮询(`registry/auth.ts`)的每一次「等一会再来」都用同一只 {@link sleep};各自手写 `new Promise((r) => setTimeout(r, ms))` 就是另一份不听 `signal` 的拷贝
+ * (`test/abortable-sleep-loops.test.ts` 的结构钉扫 `src/` 里计时器的裸名与属性形调用点 —— `setTimeout(` / `globalThis.setTimeout(` / `setInterval(`:只许这只睡眠 + 写明角色的超时计时器 / 写侧心跳)。
+ * 「已 abort ⇒ 不发」:调用方的 signal 一路交到 `fetch`(单发口原样交出,原生 `fetch` 见已 abort 即拒、不出网);会重发的重试器每次尝试前、把 signal 桥到自己 controller 的两处
+ * (子路径 `RegistryClient`、`fleet.snapshot()`)发前另查同一只 {@link throwIfAborted}。飞行中 abort 以 `signal.reason` 拒的是:重试器(请求在途 / 读完错误体后,不论第几次尝试)、两只桥接引擎、
+ * 子路径 registry 的两只发送点(`RegistryClient` 与设备码 / 刷新 / 登出共用的 `postJson`:`fetch` 拒了而调用方已 abort、或体因 abort 读不出时)、设备码轮询(环首 / 间隔 / 飞行中);已经到手的成功应答照样交回。
+ * 单发口的消费点(`openRaw` / `openStream` 之后的 `if (!res.ok) throw await errorFrom(res)`)读错误体时 abort 仍报成无码服务端错(既有,26.1.0 同)—— 这一条律不覆盖它。
+ */
+/**
+ * 调用方 signal 的中止原因,**原样**交回:`abort()` 不带原因时平台已把它定成 `AbortError`、`AbortSignal.timeout()` 定成 `TimeoutError`、
+ * 显式 `abort(x)` 就是 `x` —— **含显式的 `null`**(`null` 是调用方给的值,不是「没给」)。只有运行时根本没有 `signal.reason`
+ * (读出来是 `undefined`)时才补一只平台同形的 `AbortError`。
+ */
+export declare const abortReasonOf: (signal: AbortSignal) => unknown;
+/** 取消律的「前半」:signal 已 abort ⇒ 以它的原因拒(调用点在每次尝试之前)。 */
+export declare function throwIfAborted(signal: AbortSignal | undefined): void;
+/**
+ * 退避睡眠;**可被 `signal` 中止**(取消律的「后半」):已 abort ⇒ 立即拒;睡眠中 abort ⇒ 清定时器、立即以 `signal.reason` 拒,不睡满。
+ * 顶部的「已 abort」守卫不可省:`abort` 事件只在 abort 的那一刻触发一次,监听器挂在一只**已** abort 的 signal 上永不触发 ⇒ 没有守卫就睡满整个时长
+ * (任何调用点在 abort 之后才走到睡眠都是这一形)。
+ * 需要「abort ⇒ 安静结束」的环(流续读 / 重连)在调用点自己接住这一拒:`sleep` 只会因 abort 而拒。
+ */
+export declare function sleep(ms: number, signal?: AbortSignal): Promise<void>;
+//# sourceMappingURL=abort.d.ts.map

package/dist/abort.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"abort.d.ts","sourceRoot":"","sources":["../src/abort.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH;;;;GAIG;AACH,eAAO,MAAM,aAAa,GAAI,QAAQ,WAAW,KAAG,OAAuH,CAAC;AAE5K,oDAAoD;AACpD,wBAAgB,cAAc,CAAC,MAAM,EAAE,WAAW,GAAG,SAAS,GAAG,IAAI,CAEpE;AAED;;;;;GAKG;AACH,wBAAgB,KAAK,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAarE"}

package/dist/abort.js

@@ -0,0 +1,42 @@
+/**
+ * 取消律的三件原语 —— 调用方 `signal` abort 之后,本包既不再睡、也不再发。**一处定义**:重试器(`transport.ts`)、SSE 续读环(`sse.ts`)、审批流重连环(`resources/approvals.ts`)、
+ * 设备码轮询(`registry/auth.ts`)的每一次「等一会再来」都用同一只 {@link sleep};各自手写 `new Promise((r) => setTimeout(r, ms))` 就是另一份不听 `signal` 的拷贝
+ * (`test/abortable-sleep-loops.test.ts` 的结构钉扫 `src/` 里计时器的裸名与属性形调用点 —— `setTimeout(` / `globalThis.setTimeout(` / `setInterval(`:只许这只睡眠 + 写明角色的超时计时器 / 写侧心跳)。
+ * 「已 abort ⇒ 不发」:调用方的 signal 一路交到 `fetch`(单发口原样交出,原生 `fetch` 见已 abort 即拒、不出网);会重发的重试器每次尝试前、把 signal 桥到自己 controller 的两处
+ * (子路径 `RegistryClient`、`fleet.snapshot()`)发前另查同一只 {@link throwIfAborted}。飞行中 abort 以 `signal.reason` 拒的是:重试器(请求在途 / 读完错误体后,不论第几次尝试)、两只桥接引擎、
+ * 子路径 registry 的两只发送点(`RegistryClient` 与设备码 / 刷新 / 登出共用的 `postJson`:`fetch` 拒了而调用方已 abort、或体因 abort 读不出时)、设备码轮询(环首 / 间隔 / 飞行中);已经到手的成功应答照样交回。
+ * 单发口的消费点(`openRaw` / `openStream` 之后的 `if (!res.ok) throw await errorFrom(res)`)读错误体时 abort 仍报成无码服务端错(既有,26.1.0 同)—— 这一条律不覆盖它。
+ */
+/**
+ * 调用方 signal 的中止原因,**原样**交回:`abort()` 不带原因时平台已把它定成 `AbortError`、`AbortSignal.timeout()` 定成 `TimeoutError`、
+ * 显式 `abort(x)` 就是 `x` —— **含显式的 `null`**(`null` 是调用方给的值,不是「没给」)。只有运行时根本没有 `signal.reason`
+ * (读出来是 `undefined`)时才补一只平台同形的 `AbortError`。
+ */
+export const abortReasonOf = (signal) => (signal.reason === undefined ? new DOMException("This operation was aborted", "AbortError") : signal.reason);
+/** 取消律的「前半」:signal 已 abort ⇒ 以它的原因拒(调用点在每次尝试之前)。 */
+export function throwIfAborted(signal) {
+    if (signal?.aborted)
+        throw abortReasonOf(signal);
+}
+/**
+ * 退避睡眠;**可被 `signal` 中止**(取消律的「后半」):已 abort ⇒ 立即拒;睡眠中 abort ⇒ 清定时器、立即以 `signal.reason` 拒,不睡满。
+ * 顶部的「已 abort」守卫不可省:`abort` 事件只在 abort 的那一刻触发一次,监听器挂在一只**已** abort 的 signal 上永不触发 ⇒ 没有守卫就睡满整个时长
+ * (任何调用点在 abort 之后才走到睡眠都是这一形)。
+ * 需要「abort ⇒ 安静结束」的环(流续读 / 重连)在调用点自己接住这一拒:`sleep` 只会因 abort 而拒。
+ */
+export function sleep(ms, signal) {
+    if (signal?.aborted)
+        return Promise.reject(abortReasonOf(signal));
+    return new Promise((resolve, reject) => {
+        const onAbort = () => {
+            clearTimeout(timer);
+            reject(abortReasonOf(signal));
+        };
+        const timer = setTimeout(() => {
+            signal?.removeEventListener("abort", onAbort);
+            resolve();
+        }, ms);
+        signal?.addEventListener("abort", onAbort, { once: true });
+    });
+}
+//# sourceMappingURL=abort.js.map

package/dist/abort.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"abort.js","sourceRoot":"","sources":["../src/abort.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH;;;;GAIG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,MAAmB,EAAW,EAAE,CAAC,CAAC,MAAM,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,YAAY,CAAC,4BAA4B,EAAE,YAAY,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;AAE5K,oDAAoD;AACpD,MAAM,UAAU,cAAc,CAAC,MAA+B;IAC5D,IAAI,MAAM,EAAE,OAAO;QAAE,MAAM,aAAa,CAAC,MAAM,CAAC,CAAC;AACnD,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,KAAK,CAAC,EAAU,EAAE,MAAoB;IACpD,IAAI,MAAM,EAAE,OAAO;QAAE,OAAO,OAAO,CAAC,MAAM,CAAC,aAAa,CAAC,MAAM,CAAC,CAAC,CAAC;IAClE,OAAO,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QAC3C,MAAM,OAAO,GAAG,GAAS,EAAE;YACzB,YAAY,CAAC,KAAK,CAAC,CAAC;YACpB,MAAM,CAAC,aAAa,CAAC,MAAO,CAAC,CAAC,CAAC;QACjC,CAAC,CAAC;QACF,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE;YAC5B,MAAM,EAAE,mBAAmB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;YAC9C,OAAO,EAAE,CAAC;QACZ,CAAC,EAAE,EAAE,CAAC,CAAC;QACP,MAAM,EAAE,gBAAgB,CAAC,OAAO,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;IAC7D,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/client.d.ts

@@ -48,6 +48,8 @@ interface AgentClientConfigBase {
     baseUrl: string;
     /** openai-node-style defaults. */
     timeoutMs?: number;
+    /** 会重试的请求(GET 读口 · 带键提交)在首发之外**再发**至多这么多次;缺省 `2`。**必须是非负整数**:`0` = 每个请求只发一次;负数 / `NaN` / 非整数 / 无穷 / 非数值(含数字串;`null` / `undefined` 读作缺席) ⇒ **构造 `AgentClient` 即抛**
+     *  (fail-closed,与 `principalHeader` 的保留头守卫同一处;`ControlClient` 同一条规则)。 */
     maxRetries?: number;
     /** Escape hatch for tests / a deliberate browser BFF that injects the token itself. Default false. */
     allowBrowser?: boolean;
@@ -59,10 +61,13 @@ interface AgentClientConfigBase {
      *  ⇒ 认不出身份;此前唯一出路是绕开 SDK 手抄 fetch —— 恰是 SDK 宪法①禁止的那件事。
      *  🔴 改名是**替换**不是新增:配了之后不再发缺省名(同时自报两个身份头是更糟的形)。
      *  🔴 RESERVED 守卫跟着改:配置的头名同样进保留集,caller extras 覆盖不了它(内建恒胜)—— 否则
-     *  改个名就等于把身份头的注入权交还给调用方。 */
+     *  改个名就等于把身份头的注入权交还给调用方。
+     *  🔴 名字不许是传输层自己装的头、条件请求头(`if-none-match` / `if-modified-since` / …)或连接层的头(`host` / `content-length` / …)—— 构造即抛(fail-closed;
+     *  身份头一旦是条件头,每个请求都成了条件请求,304 判据与身份一起失真)。闭集在 `transport.ts` 的 `PRINCIPAL_HEADER_FORBIDDEN`。 */
     principalHeader?: string;
 }
-/** 判别联合(G22):relay 态 principal 可省略;其余两态 principal 类型级必填不弱化。 */
+/** 判别联合(G22):按 `authToken` 的形分臂(令牌串 / `loopback-unauthed` 一臂,`same-origin-relay` 一臂)。两臂的 `principal` 都是可选(`principal?: Principal`):
+ *  缺席(键不给)⇒ 不发身份头;空串 ⇒ 非 relay 态构造期拒、relay 态当缺席(同样不发头)。 */
 export type AgentClientConfig = (AgentClientConfigBase & {
     /** Worker `SERVICE_AUTH_TOKEN`. SERVER-SIDE ONLY (the browser guard enforces this).
      *  For a loopback dev engine, `{ mode: "loopback-unauthed" }` is the explicit no-token posture. */
@@ -221,7 +226,7 @@ export declare class AgentClient {
     }): Promise<McpProbeFace>;
     /** Per-request principal (pinned wire contract): the wire principal is a per-request header, so multi-tenant
      *  callers (façade/BFF) scope a cheap view per end-user instead of caching principal as ambient state.
-     *  Principal stays REQUIRED and explicit — no default, no fallback (fail-closed structure unchanged). */
+     *  This method's argument stays REQUIRED and explicit (falsy ⇒ throws, in every mode) — no default, no fallback; it is the constructor's `principal` that may be absent. */
     withPrincipal(principal: Principal): AgentClient;
     constructor(config: AgentClientConfig);
 }

package/dist/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}

package/dist/client.js

@@ -1,7 +1,8 @@
 /**
  * AgentClient — config + resource roots. This file is where the体系铁律 become STRUCTURAL constraints (so the
  * design can't drift into the SDK):
- *   - principal-first (DESIGN §2.4): `principal` is REQUIRED at the type level — no anonymous-by-default.
+ *   - principal-first (DESIGN §2.4): no anonymous-by-default — the SDK never mints an identity for the caller. `principal` is optional (absent = local single-user,
+ *     no header sent; an empty string is refused outside same-origin-relay); the multi-tenant identity gate lives on the server.
  *   - secret discipline (DESIGN §2.5): `authToken` is a server-side construct param. The browser guard refuses
  *     to construct a token-bearing client when `window` exists — the SDK gives NO sugar for browser→worker
  *     direct calls (a web frontend's browser talks to its own BFF, which holds the token).
@@ -194,7 +195,7 @@ export class AgentClient {
     }
     /** Per-request principal (pinned wire contract): the wire principal is a per-request header, so multi-tenant
      *  callers (façade/BFF) scope a cheap view per end-user instead of caching principal as ambient state.
-     *  Principal stays REQUIRED and explicit — no default, no fallback (fail-closed structure unchanged). */
+     *  This method's argument stays REQUIRED and explicit (falsy ⇒ throws, in every mode) — no default, no fallback; it is the constructor's `principal` that may be absent. */
     withPrincipal(principal) {
         if (!principal)
             throw new Error("AgentClient.withPrincipal: principal is required (use 'anon:<id>' to be explicitly anonymous).");
@@ -247,8 +248,8 @@ export class AgentClient {
                 const h = {};
                 if (authToken !== undefined)
                     h.authorization = `Bearer ${authToken}`;
-                // relay 态 principal 可缺席 ⇒ 头也缺席(不铸 anon 假值;BFF 注入是它的职责面)。
-                // 其余两态 principal 构造期已验必填,此处恒发——字节不变。
+                // principal 缺席 ⇒ 头也缺席(不铸 anon 假值;relay 态由 BFF 逐请求注入);空串只可能出现在 relay 态(其余态构造期已拒)⇒ 同样不发头。
+                // 给了的 principal 原样发出——字节不变。
                 if (principal !== undefined && principal !== "")
                     h[principalHeader] = principal;
                 h["content-type"] = "application/json";

package/dist/client.js.map

@@ -1 +1 @@
-{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}

package/dist/control-client.d.ts

@@ -17,10 +17,12 @@ export interface ControlClientConfig {
      *  env (env-agnostic, same as AgentClient.authToken). */
     token: string;
     /** Audit principal (OPTIONAL). Maps to the registry's x-agent-principal → audited as `ai:<principal>`.
-     *  Omitted ⇒ the header is not sent ⇒ the registry records `unknown`. (Registry does NOT require principal-
-     *  first, unlike the worker — so this is optional here.) */
+     *  Omitted ⇒ the header is not sent ⇒ the registry records `unknown`. (The registry does not require a
+     *  principal, so it is optional here.) */
     principal?: string;
     timeoutMs?: number;
+    /** 会重试的请求(GET 读口 · 带键提交)在首发之外**再发**至多这么多次;缺省 `2`。**必须是非负整数**:`0` = 每个请求只发一次;负数 / `NaN` / 非整数 / 无穷 / 非数值(含数字串;`null` / `undefined` 读作缺席) ⇒ **构造 `ControlClient` 即抛**
+     *  (fail-closed,与 `AgentClient` 同一处同一条规则)。 */
     maxRetries?: number;
     /** Escape hatch for tests / a deliberate BFF that injects the token itself. Default false. */
     allowBrowser?: boolean;

package/dist/control-client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"control-client.d.ts","sourceRoot":"","sources":["../src/control-client.ts"],"names":[],"mappings":"AA2BA,OAAO,EAAE,qBAAqB,EAAE,MAAM,+BAA+B,CAAC;AACtE,OAAO,EAAE,yBAAyB,EAAE,MAAM,mCAAmC,CAAC;AAC9E,OAAO,EAAE,sBAAsB,EAAE,MAAM,gCAAgC,CAAC;AACxE,OAAO,EAAE,oBAAoB,EAAE,MAAM,8BAA8B,CAAC;AACpE,OAAO,EAAE,sBAAsB,EAAE,MAAM,gCAAgC,CAAC;AACxE,OAAO,EAAE,wBAAwB,EAAE,MAAM,kCAAkC,CAAC;AAC5E,OAAO,EAAE,qBAAqB,EAAE,MAAM,+BAA+B,CAAC;AACtE,OAAO,EAAE,sBAAsB,EAAE,MAAM,gCAAgC,CAAC;AACxE,OAAO,EAAE,4BAA4B,EAAE,MAAM,uCAAuC,CAAC;AACrF,OAAO,EAAE,oBAAoB,EAAE,MAAM,8BAA8B,CAAC;AAEpE,MAAM,WAAW,mBAAmB;IAClC;uEACmE;IACnE,OAAO,EAAE,MAAM,CAAC;IAChB;;6DAEyD;IACzD,KAAK,EAAE,MAAM,CAAC;IACd;;gEAE4D;IAC5D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,8FAA8F;IAC9F,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;CACtB;AAED,qBAAa,aAAa;IACxB,uGAAuG;IACvG,QAAQ,CAAC,MAAM,EAAE,qBAAqB,CAAC;IACvC,iFAAiF;IACjF,QAAQ,CAAC,UAAU,EAAE,yBAAyB,CAAC;IAC/C,wEAAwE;IACxE,QAAQ,CAAC,OAAO,EAAE,sBAAsB,CAAC;IACzC,4FAA4F;IAC5F,QAAQ,CAAC,KAAK,EAAE,oBAAoB,CAAC;IACrC,yFAAyF;IACzF,QAAQ,CAAC,OAAO,EAAE,sBAAsB,CAAC;IACzC,+EAA+E;IAC/E,QAAQ,CAAC,SAAS,EAAE,wBAAwB,CAAC;IAC7C,kHAAkH;IAClH,QAAQ,CAAC,MAAM,EAAE,qBAAqB,CAAC;IACvC,mHAAmH;IACnH,QAAQ,CAAC,OAAO,EAAE,sBAAsB,CAAC;IACzC,iGAAiG;IACjG,QAAQ,CAAC,aAAa,EAAE,4BAA4B,CAAC;IACrD,iGAAiG;IACjG,QAAQ,CAAC,KAAK,EAAE,oBAAoB,CAAC;IAErC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAsB;IAC9C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAY;IAEtC;yGACqG;IACrG,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,aAAa;gBAInC,MAAM,EAAE,mBAAmB;CA0CxC"}
+{"version":3,"file":"control-client.d.ts","sourceRoot":"","sources":["../src/control-client.ts"],"names":[],"mappings":"AA2BA,OAAO,EAAE,qBAAqB,EAAE,MAAM,+BAA+B,CAAC;AACtE,OAAO,EAAE,yBAAyB,EAAE,MAAM,mCAAmC,CAAC;AAC9E,OAAO,EAAE,sBAAsB,EAAE,MAAM,gCAAgC,CAAC;AACxE,OAAO,EAAE,oBAAoB,EAAE,MAAM,8BAA8B,CAAC;AACpE,OAAO,EAAE,sBAAsB,EAAE,MAAM,gCAAgC,CAAC;AACxE,OAAO,EAAE,wBAAwB,EAAE,MAAM,kCAAkC,CAAC;AAC5E,OAAO,EAAE,qBAAqB,EAAE,MAAM,+BAA+B,CAAC;AACtE,OAAO,EAAE,sBAAsB,EAAE,MAAM,gCAAgC,CAAC;AACxE,OAAO,EAAE,4BAA4B,EAAE,MAAM,uCAAuC,CAAC;AACrF,OAAO,EAAE,oBAAoB,EAAE,MAAM,8BAA8B,CAAC;AAEpE,MAAM,WAAW,mBAAmB;IAClC;uEACmE;IACnE,OAAO,EAAE,MAAM,CAAC;IAChB;;6DAEyD;IACzD,KAAK,EAAE,MAAM,CAAC;IACd;;8CAE0C;IAC1C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;kDAC8C;IAC9C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,8FAA8F;IAC9F,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;CACtB;AAED,qBAAa,aAAa;IACxB,uGAAuG;IACvG,QAAQ,CAAC,MAAM,EAAE,qBAAqB,CAAC;IACvC,iFAAiF;IACjF,QAAQ,CAAC,UAAU,EAAE,yBAAyB,CAAC;IAC/C,wEAAwE;IACxE,QAAQ,CAAC,OAAO,EAAE,sBAAsB,CAAC;IACzC,4FAA4F;IAC5F,QAAQ,CAAC,KAAK,EAAE,oBAAoB,CAAC;IACrC,yFAAyF;IACzF,QAAQ,CAAC,OAAO,EAAE,sBAAsB,CAAC;IACzC,+EAA+E;IAC/E,QAAQ,CAAC,SAAS,EAAE,wBAAwB,CAAC;IAC7C,kHAAkH;IAClH,QAAQ,CAAC,MAAM,EAAE,qBAAqB,CAAC;IACvC,mHAAmH;IACnH,QAAQ,CAAC,OAAO,EAAE,sBAAsB,CAAC;IACzC,iGAAiG;IACjG,QAAQ,CAAC,aAAa,EAAE,4BAA4B,CAAC;IACrD,iGAAiG;IACjG,QAAQ,CAAC,KAAK,EAAE,oBAAoB,CAAC;IAErC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAsB;IAC9C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAY;IAEtC;yGACqG;IACrG,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,aAAa;gBAInC,MAAM,EAAE,mBAAmB;CA0CxC"}

package/dist/control-client.js

@@ -9,9 +9,9 @@
  *     prefix" branch in header assembly — exactly the fail-open shape to avoid. Two clients = two header
  *     closures = two independently-captured secrets; it is structurally impossible to send the registry token
  *     to the worker (or vice-versa).
- *   - principal semantics differ: the worker REQUIRES principal-first; the registry's x-agent-principal is
- *     OPTIONAL (audit slug `ai:<principal>`, absent → `unknown`). Forcing it into AgentClient's REQUIRED
- *     principal would be a semantic mismatch.
+ *   - principal semantics differ: the worker's principal is explicit and never minted (absent = no header; the multi-tenant
+ *     gate is the server's); the registry's x-agent-principal is OPTIONAL (audit slug `ai:<principal>`, absent → `unknown`).
+ *     Forcing the worker's explicit-identity contract into the control plane would be a semantic mismatch.
  *
  * It REUSES Transport's request/retry/timeout/Retry-After/parseJson engine (token-agnostic) via two injection
  * points: `buildHeaders` (registry Bearer + optional principal) and `mapError` (toControlError — the registry's

package/dist/control-client.js.map

@@ -1 +1 @@
-{"version":3,"file":"control-client.js","sourceRoot":"","sources":["../src/control-client.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"control-client.js","sourceRoot":"","sources":["../src/control-client.ts"],"names":[],"mappings":"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"}

package/dist/errors.d.ts

@@ -869,19 +869,23 @@ export interface CheckpointUnsupportedVersionExtra {
 }
 /**
  * `409 conflict.checkpoint_ctx_unsealable` 的 `reason` 闭集(server ≥7.134.0;server `CHECKPOINT_CTX_UNSEALABLE_REASONS` 逐词同序,`dist/http/checkpoint-ctx.d.ts`)——
- * 任务的续跑上下文里有**请求自带的凭据**(MCP / A2A 头与 env 值、`settings.env`、`settings.webSearch.apiKey`、http hook 头)—— 提交时要把它们**封**进续跑上下文、续跑时要**开**封,
+ * 任务的续跑上下文里有**请求自带的凭据**(MCP / A2A 头与 env 值、`settings.env`、`settings.webSearch.apiKey`、http hook 头;**server ≥7.136.0 起还有子进程的命令行**:stdio MCP 传输与 command hook 条目的 `command` / `args`)—— 提交时要把它们**封**进续跑上下文、续跑时要**开**封,
  * 而这台 server 封不了或开不了:
  *  · `no_key_store` —— 这台副本没有保管店(封签器);
  *  · `key_not_held` —— 封它的那把钥匙不在这台副本的保管店里(别的副本的钥匙,或保管目录被换了);
  *  · `unopenable` —— 封签值坏了,或属于别的会话;
  *  · `plaintext` —— 老版本(≤7.133.x)写下的明文凭据;
  *  · `unrecognized_seal` —— 本版不认识的封签格式(server ≥7.135.0 另一臂:落盘的凭据位代数〔`credentialSlotGeneration`〕比本版新 / 不是正整数,此时 `field` 读 `credentialSlotGeneration`,不是体内坐标;
- *    凭据位闭集同批多一行 `settings.hooks.<事件>[].hooks[].plugin.options` —— 带选项插件 hook 的停驻任务从此只以封签落盘)。
+ *    凭据位闭集同批多一行 `settings.hooks.<事件>[].hooks[].plugin.options` —— 带选项插件 hook 的停驻任务从此只以封签落盘);
+ *    **server ≥7.136.0 凭据位闭集再加四位(读法记号第 3 代)**:`mcpServers[i].transport.command` / `mcpServers[i].transport.args`(stdio 传输)与 `settings.hooks.<事件>[g].hooks[h].command` / `.args`(command hook;`field` 就是这几格的体内坐标)——
+ *    命令行里的密钥(`--token=…`、`-p <口令>`、shell 形 hook 的整行 `curl -H 'Authorization: Bearer …'`)同样只以封签落盘;`command` 封成一个值、**`args` 整只数组封成一个值**(不逐元素认形);续跑开封后逐字交执行器,调用方零改动。
+ *    提交体带这四格而本服务没有保管店 ⇒ 与其它凭据位同一道提交口拒(`field` 点名那一格;哪些门会发、拒怎样到达见下方「哪些门会发这只 409」权威句,本句不复述);7.135.x 副本新写的、带命令行的行在 7.136.0 上续跑 ⇒ `plaintext`(下一次起服的一次性迁移补封,只在窗内);
+ *    7.136.0 停驻的这类任务在 7.135.x 副本上续跑 ⇒ `unrecognized_seal`(`field: "credentialSlotGeneration"`)—— 多副本升级先停光旧副本。三只拒句改成规则形(类别名,不再逐条列实例):按 `errorCode` / `field` / `reason` 读,不按句子。
  *
  * **哪些门会发这只 409(权威句 —— 本包只在这里写一次;读法句、README、`index.ts`、随包 spec 都指向这里,不各自重复门清单)**:
- *  · 续跑口 —— 续跑入口(`POST /v1/approvals/:sessionId/decide`、`POST /v1/tool-approvals/:id/respond` 的停驻赎回、`/v1/assistant/tasks/:id/resume`、`plan_review`、`/v1/sessions/:id/wake`)与终态 run 的 `POST /v1/runs/:id/steer`:开封,server 码上五词都可能(装配好的 server 上实际能到达的是其中四词,见「钉版 server 7.134.0 的发布字节」那一条);
- *  · 提交口 —— `POST /v1/tasks` / `/v1/runs`(体带请求凭据时要把它们封进续跑上下文):HTTP 409,封口只铸 `no_key_store` 一词;流式的 `POST /v1/tasks/stream` 上同一道拒经 SSE `done` 帧到达(`status: "failed"` + `errorCode`,**不带** `field` / `reason`,不是 HTTP 409);
- *  · 钉版 server 7.134.0 的发布字节、经公开出口装配时**两个门都走不到 `no_key_store`**:server 包公开出口里能装起这两个门的只有 `createHttpServer`(路由模块不在 `exports` 里;按文件路径直接 import dist 内部模块自拼门,不在受支持面内),它在有 `checkpointStore` 而没有封签器时直接拒启(`./main` 的起服同一句),提交口也只在 `checkpointStore` 在场时存续跑上下文 ——
+ *  · 续跑口 —— 续跑入口(`POST /v1/approvals/:sessionId/decide`、`POST /v1/tool-approvals/:id/respond` 的停驻赎回、`/v1/assistant/tasks/:id/resume`、`plan_review`、`/v1/sessions/:id/wake`)与终态 run 的 `POST /v1/runs/:id/steer`:开封,server 码上五词都可能(装配好的 server 上实际能到达的是其中四词,见「钉版 server 7.136.0 的发布字节」那一条);
+ *  · 提交口 —— `POST /v1/tasks` / `/v1/runs`(体带请求凭据时要把它们封进续跑上下文):HTTP 409 `conflict.checkpoint_ctx_unsealable` + `reason: "no_key_store"`(封口只铸 `no_key_store` 这一个 reason 词);流式的 `POST /v1/tasks/stream` 上同一道拒经 SSE `done` 帧到达(`status: "failed"` + `errorCode`,**不带** `field` / `reason`,不是 HTTP 409);
+ *  · 钉版 server 7.136.0 的发布字节、经公开出口装配时**两个门都走不到 `no_key_store`**:server 包公开出口里能装起这两个门的只有 `createHttpServer`(路由模块不在 `exports` 里;按文件路径直接 import dist 内部模块自拼门,不在受支持面内),它在有 `checkpointStore` 而没有封签器时直接拒启(`./main` 的起服同一句),提交口也只在 `checkpointStore` 在场时存续跑上下文 ——
  *    所以装配好的 server 上这只 409 能到达的是续跑口的 `key_not_held` / `unopenable` / `plaintext` / `unrecognized_seal`;`no_key_store` 是封口的防御臂(server 码里有这一词,经公开出口装配的 server 上走不到)。
  * **续跑口的拒:没有问被决、没有续跑开始**(卡仍待决;已知的例外是终局 run 的 steer 竞态臂 —— 它先立一张唤醒卡,第二次读到不可开再把那张卡撤掉〔撤卡失败只记 server 日志〕,然后 409);**提交口的拒在任务开跑之前**(什么都没跑;持久 run 行已立时,server 随即把那条 run 标 `failed`、释放它的幂等键 —— 两步都是尽力而为,失败只记 server 日志,答的仍是这只 409),确定性拒:原样重试同答。
  */
@@ -924,8 +928,17 @@ export type FaultPermanence = (typeof FAULT_PERMANENCE_WORDS)[number];
  *    不答「没有这只 blob」(那是 `404 not_found.blob` 的义),也不越界给字节。落 {@link ServiceStateError}(`state.` 前缀族);
  *  · `422 adopt_failed` —— 推送口 `POST …/sync/import` 的文件历史重放(第一阶段的 `identical` 重推臂与第二阶段提交臂同一口):店的 `importHistory` 答「收编失败」(SQL 店取云端自己的 blob 时抛 / 发布那一步撞上库的故障),
  *    店码原样上 wire;7.134.x 这两形答 `unsupported_format`。🔴 **与缺 blob 是两件事**:缺 blob 只答 `missing_blob`(补 PUT 再推)。落带码 {@link APIError}(无专属子类,按 `errorCode` 判别)。
- * 读法(两码同):**按 `permanence` 分** —— `transient` ⇒ 什么都不改,稍后重试同一形;`terminal` ⇒ 不重试,查 / 修云端文件历史店(店修好之前重试无益);**键缺席**(店没判)⇒ 稍后再推 / 拉一次,仍红则查店。
- * ⚠️ 本包的自动重试臂按**码 + 状态**(`503` 在重试集里,`state.file_history_unreadable` 不在确定性失败码表):`terminal` 不会让自动重试停手,那是调用方读 `permanence` 之后的决定。
+ * 读法(两码同):**按 `permanence` 分** —— `transient` ⇒ 什么都不改,稍后重试同一形;`terminal` ⇒ 不重试,查 / 修云端文件历史店(店修好之前重试无益);**键缺席**(店没判)⇒ 不是 terminal,按状态矩阵重试(拉取口本包已自动重试至多 `maxRetries` 次;推送口调用方稍后再推一次),仍红则查店。
+ * **本包的自动重试臂读 `permanence`**(27.0.0 起,唯一重试器的唯一判官,见 `Transport` 的 `isDeterministicFailure`):`terminal` ⇒ **不重试**(server 说修店之前重试无益,本包不替调用方多打坏店);`transient` ⇒ 重试(受状态矩阵与 `maxRetries` 约束);
+ * **键缺席**(店没判)⇒ 状态矩阵照旧(`503` 在重试集里,至多 `maxRetries` 次)—— 缺席不是 terminal。`state.file_history_unreadable` 这类 transient / terminal 共用的码进不了确定性失败码表,所以读体上的这个键。
+ *
+ * 🔴 **server ≥7.136.0:`transient` 的判官扩到连接类故障**(连接被重置 / 拒连 / 池断 / 库关停或切成只读;识别表是闭集,认不出的一律仍**不判**:死锁、锁等待 / 语句超时、认证类拒连、语句级的库错都在表外)——
+ * 文件历史店故障的 `422 adopt_failed` / `restore_failed` 等店答因此在库断连上也带 `permanence: "transient"`(此前只有永久码带 `terminal`,其余都不判);
+ * **会话同步三条拉取读腿 `GET …/sync/manifest` · `GET …/sync/entries`(开流前)· `GET …/sync/history/blobs/:hash` 对库断连统一答 `503 state.file_history_unreadable` + `permanence: "transient"`**
+ * (此前落通用 `500 internal.error`、码丢)。🔴 **码名里的 `file_history` 是出身,动作只看 `permanence`**:这只码现在也会在条目 id 集合、policy、锚点、会话行等**别的读腿**断连时出现,不再只意味着文件历史撕裂;
+ * 把这三口的 `500` 当终局失败的客户端,在库断连上现在读到 `503`(重试集内:**三条拉取腿的开请求都由本包自动重试**,至多 `maxRetries` 次、**只在首字节之前** —— `manifest()` 走 `request()` 的 GET 腿,
+ * `entries()` / `getHistoryBlob()` 走 `Transport.openRawGet`,**同一只重试器**;耗尽后抛 `ServiceStateError`,`permanence` 在 `err.extra`)。`entries` 开流**之后**的断连仍只能截断(没有结尾行 ⇒ `SyncTruncatedError`,体读到一半不重试,
+ * 调用方带 `afterSeq` 续读);会话门那一读与推送 / 干跑口的读腿遇库断连仍落通用 `500`。
  */
 export interface StoreFaultExtra {
     permanence?: FaultPermanence;
@@ -973,10 +986,14 @@ export interface ResumeRefusalExtra {
  * 续跑腿同判:折成 409 `resume_blocked_by_policy`(`blockedBy: "request.field_invalid"`),本组键随体原样带上。
  *
  * 🔴 **server ≥7.135.0:URL 带凭据的拒**也走这一组机读位({@link URL_CREDENTIAL_REFUSAL_REASONS} 两词:`url_userinfo`〔`user:pass@host`〕/ `url_credential_param`〔query / fragment 里有凭据名参数,
- * 名表 = 服务日志脱敏器认作凭据的 23 个名〕),`field` 点名**五座**的体内坐标:`mcpServers[i].transport.url`(新提交三腿 + `POST /v1/capabilities/mcp/probe`)·
+ * 名表 = 服务日志脱敏器认作凭据的 23 个名〕),`field` 点名**五座**的体内坐标(**server ≥7.136.0 加第六座 `images[i].url`,见下**):`mcpServers[i].transport.url`(新提交三腿 + `POST /v1/capabilities/mcp/probe`)·
  * `a2aPeers[i].url` / `a2aPeers[i].cardUrl` · `settings.hooks.<事件>[g].hooks[h].url`(**全坐标** `field`,不是 `field: "settings.hooks"` + `detail` 嵌套形 —— 按 `field === "settings.hooks"` 分流的消费端读不到这一拒)·
- * `settings.webSearch.endpoint`(带 userinfo 的体句子不变、另带 `field` / `reason: "url_userinfo"`)。原因句不回显 url 值;出路 = 凭据挪进封签位(`headers` / `apiKey`;钩子 `$NAME` + `allowedEnvVars`),
+ * `settings.webSearch.endpoint`(带 userinfo 的体句子不变、另带 `field` / `reason: "url_userinfo"`)。🔴 **第六座 `images[i].url`(server ≥7.136.0;六座 = 上面五座 + 它)**:`images` 的 `{ url }` 臂的串值过同一只判官,新提交 ⇒ `400 request.field_invalid` + `field: "images[i].url"` + 同一对 `reason`;
+ * 内联 `{ data, mimeType }` 臂与非串 `url` 不归本座,个数帽(20,`413`)与内联字节帽排在它前面,耐久 resume 重放存量体不判;出路 = 图片字节改走内联(内联图有自己的字节帽,不落 URL)或换一个不靠这些参数名鉴权的地址。原因句不回显 url 值;出路 = 凭据挪进封签位(`headers` / `apiKey`;钩子 `$NAME` + `allowedEnvVars`),
  * 部署面声明的地址不判。升级前已停驻的任务照常续跑(url 原字节在续跑上下文里)。**`a2aPeers` 超 32 条** ⇒ `400` `field: "a2aPeers"` · `reason: "over_cap"` · `count` · `cap`(此前截尾丢弃、请求 200)。
+ *
+ * **server ≥7.136.0 的同族面**:`mcpServers` 超 32 条改走全仓同一形的撞帽拒(头一句 `mcpServers has 33 entries — at most 32 are accepted`,体加性带 `field: "mcpServers"` · `reason: "over_cap"` · `count` · `cap`;探测口 `POST /v1/capabilities/mcp/probe` 同句同机读位;此前一句不带机读位的 `… carries N declarations …`,按旧句文案匹配的客户端改按机读位);
+ * `a2aPeers` 的列表 / 条目 / 键值写坏在**新提交**上 ⇒ `400 request.field_invalid` **只有句子、不带 `field` / `reason`**(带凭据的 url 与超 32 条才带这组机读位),词表外的键 ⇒ `400 request.body_shape` + `unknownKeys`(全坐标)—— 全文见 {@link import("./types.js").TaskRequest.a2aPeers}。
  */
 export interface RequestFieldRefusalExtra {
     field?: string;
@@ -1317,8 +1334,13 @@ export declare class RunNotLiveError extends ConflictError {
     name: string;
 }
 /** Base of the `decide.*` family — catch this to handle the whole decide door in one place.
- *  Codes that fall on THIS class rather than a subclass need a human: `row_unrevivable` (damaged row),
+ *  Codes that fall on THIS class rather than a subclass need a human: `row_unrevivable` (a parked row the server cannot revive),
  *  `revive_failed`, `revive_rejected`.
+ *  🔴 **server ≥7.136.0 — `row_unrevivable` has an exit: deny closes the card.** The two forms that never revive — a parked background child whose row carries no agent name (an unnamed `Agent` call), and a row with no root-session anchor —
+ *  still answer **approve** with `409 decide.row_unrevivable` (the sentence now ends by pointing at deny), but **deny** answers `200 { taskId, status: "failed", decision: "deny" }`: the card is voided under its own scope CAS,
+ *  leaves the pending queue and the `/v1/approvals/stream` snapshot, the child ends `failed`, nothing of the gated tool runs and no `remember` is granted. A lost void CAS (the card was swept by its window or voided a moment earlier) is the existing `409 decide.gate_moved`.
+ *  A client that branched on "deny ⇒ 409 `decide.row_unrevivable`" must branch on `status` / `errorCode`, not on the sentence; the wanted approval is still impossible (re-dispatch a **named** background child on the host).
+ *  Before 7.136.0 the same forms answered both decisions `409`, and an unnamed row was read as damaged — it is the normal form today.
  *  🔴 server ≥7.104.0 (S-790) gives `decide.row_unrevivable` a SECOND trigger, same code, same body keys: the parked row carries no
  *  root-session anchor, so the server cannot tell which session the card belongs to and refuses BEFORE claiming it (nothing consumed).
  *