@sema-agent/sdk 0.1.9 → 1.1.0

package/dist/errors.js

@@ -5,36 +5,96 @@
  */
 export class APIError extends Error {
     status;
-    code;
+    errorCode;
     /** `true` = the server said this failure is RETRIABLE: the durable park is still pending, so re-fetching and
      *  deciding/resuming again is meaningful (server sets `retriable: true` on the /decide + resume legs).
      *
      *  🔴 `undefined` means "the server did not say", NOT "not retriable" — it is a CONDITIONAL field server-side
      *  (absent ⇒ key omitted), so reading its absence as an explicit `false` over-reads the wire.
      *
-     *  ⚠️ 为什么它不是 `readonly` / 不是构造参数:`retriable` 可以伴随**任何**分支的错误一起回来,而这里已有 25 个
+     *  ⚠️ 为什么它不是 `readonly` / 不是构造参数:`retriable` 可以伴随**任何**分支的错误一起回来,而这里已有三十多个
      *  子类、其中好几个有自己的位置化构造签名(retryAfterMs / allowlist / relation …)。做成第 4 个构造参数就得逐个
      *  子类穿线,漏一个就是静默丢信号;做成 mapper 末尾的**单点盖章**则天然覆盖全部返回路径。这是刻意取舍。 */
     retriable;
-    constructor(status, code, message) {
+    constructor(status, errorCode, message) {
         super(message);
         this.status = status;
-        this.code = code;
+        this.errorCode = errorCode;
         this.name = new.target.name;
     }
 }
-/** 401 / 503 — fail-closed auth (missing/bad SERVICE_AUTH_TOKEN). */
+/** `auth.*` 前缀族 + 401/503 状态兜底 —— fail-closed auth(缺/错 SERVICE_AUTH_TOKEN、非属主、
+ *  operator-only、bake-runner-only、principal 头缺席…)。
+ *
+ *  🔴 键位优先于状态(SDK 1.1.0):此前这个类**只**按 `status === 401 || status === 503` 分,于是
+ *  `auth.forbidden` / `auth.operator_only` / `auth.bake_runner_only` / `auth.ingest_secret_invalid`
+ *  四个 403 全塌成裸 APIError,而同一条 503 分支还错吞了 `state.*`(见 {@link ServiceStateError})。
+ *  现在先按 `auth.` 前缀分,状态兜底留作**没有机器码时**的退路。 */
 export class AuthError extends APIError {
 }
+// ── 附录 A 判据三:9 个稳定前缀族的兜底 typed 面(SDK 1.1.0 × server 3.0.0)────────────────────────
+// 服务端契约原文(ASSISTANT-WIRE-CONTRACT 附录 A 判据三):「前缀族(`auth.` / `request.` /
+// `not_found.` / `conflict.` / `limit.` / `capability.` / `feature.` / `internal.` / `state.`)是稳定的
+// **粗分支面** —— 按前缀兜底(未知码 → 看前缀 → 再不行看状态码)永远安全。」
+//
+// 🔴 为什么这不是「把码抄进 SDK」这么轻:补齐之前,`capability.run_store_required`(**换部署形态**才可能有)
+// 与 `feature.elicitation_disabled`(**开个开关**就行)都是 501、都塌成裸 `APIError` —— 消费端拿不到任何
+// 可分支的东西,而这两者给用户的行动建议正好相反。契约套件第一批把这件事做成了可执行断言
+// (`COLLAPSED_BASELINE` 棘轮 = 25 行塌型),本批销账。
+//
+// 两族**复用已有类,不新铸**:`auth.*` → {@link AuthError};`conflict.*` → {@link ConflictError}
+// (它已经携带 `activeTaskId`,正是 `conflict.session_active_run` 要的那个字段)。
+//
+// ⚠️ 前缀兜底是**开集**的:server 明天新增一个 `capability.xxx_required`,今天这份 SDK 就已经把它
+// 铸成 `CapabilityUnavailableError` —— 未知码的降级仍然是有信息的(与 `stop.*` / `decide.*` 同款设计)。
+/** `request.*` 前缀族 —— **请求本身有问题,改请求即可**(400 为主,另有 413 / 422 / 4xx 兜底粗码)。
+ *  一律 NOT retryable verbatim:同一个 body 重发永远同一个结果。子类 {@link PayloadTooLargeError} 专指
+ *  「某个字段/整体太大」这一支(处置更具体:缩短后重发)。 */
+export class BadRequestError extends APIError {
+}
+/** `not_found.*` 前缀族 —— 资源不存在。⚠️ 也包含**属主门**:server 对非属主一律回 404 同码同文
+ *  (不给存在性 oracle),所以「404」不等于「东西真不在」,只等于「你看不到它」。 */
+export class NotFoundError extends APIError {
+}
+/** `limit.*` 前缀族 —— 配额 / 限流 / 保留窗(429 限流与成本配额、416 续读点过保留窗)。
+ *  `retryAfterMs` 来自 `Retry-After` 头(由 transport 喂入)。
+ *  ⚠️ 429 那两个成员码({@link RateLimitedError} 起)走更具体的子类,见下。 */
+export class LimitExceededError extends APIError {
+    retryAfterMs;
+    constructor(status, errorCode, message, retryAfterMs) {
+        super(status, errorCode, message);
+        this.retryAfterMs = retryAfterMs;
+    }
+}
+/** `capability.*` 前缀族 —— **本部署没接这个面**(501)。重试无意义、开开关也没用:要么换部署形态
+ *  (接上 store / 打开 fleet 接线),要么在 UI 上**别提供这个入口**。
+ *  🔴 与 {@link FeatureDisabledError} 的区别正是 P0-1 的全部后果:同为 501,处置相反。 */
+export class CapabilityUnavailableError extends APIError {
+}
+/** `feature.*` 前缀族 —— **面存在,但开关是关的**(501;`feature.metrics_disabled` 是 404)。
+ *  处置:提示管理员打开对应开关(`RESOURCE_SUSPEND` / 三个 LIVE HITL 开关 / metrics)——不需要换部署形态。 */
+export class FeatureDisabledError extends APIError {
+}
+/** `internal.*` 前缀族 —— 服务端自己出错(500 / 502)。细节不上 wire。
+ *  部分成员**明确可重试**(`internal.cancel_not_terminalized` = 重试 cancel;
+ *  `internal.snapshot_blobs_missing` = 重试或换快照),按 `.errorCode` 分。 */
+export class InternalServerError extends APIError {
+}
+/** `state.*` 前缀族 —— 服务端**当前状态**不接受这个请求(503):roster 还没拉到、没有可用的
+ *  sandbox-base。**稍后重试**是主处置。
+ *  🔴 修的是一条真缝:这一族此前撞进 `status === 503` 那条分支,被铸成了 {@link AuthError} —— 一个
+ *  「稍后重试」的信号被读成了「你没有权限」。 */
+export class ServiceStateError extends APIError {
+}
 /** 413 `workspace_file_too_large`(#3 workspace file 面,[1894]①)——结构化超限信封的 typed 形:
  *  `sizeBytes`=文件真实大小、`limit`=部署帽(capabilities.workspace.maxFileBytes)。web 用它渲
  *  「文件过大({sizeBytes}),下载查看」卡;archive 端点是退路。由 WorkspaceResource.file 铸
- *  (面局部判别,不进全局 classify——code 是这个面独有的)。 */
+ *  (面局部判别,不进全局 classify——errorCode 是这个面独有的)。 */
 export class WorkspaceFileTooLargeError extends APIError {
     sizeBytes;
     limit;
-    constructor(status, code, message, sizeBytes, limit) {
-        super(status, code, message);
+    constructor(status, errorCode, message, sizeBytes, limit) {
+        super(status, errorCode, message);
         this.sizeBytes = sizeBytes;
         this.limit = limit;
     }
@@ -46,40 +106,39 @@ export class WorkspaceFileTooLargeError extends APIError {
  *  dead).**Retryable against the replacement instance**; honor `retryAfterMs` (from `retry-after`). */
 export class DrainingError extends APIError {
     retryAfterMs;
-    constructor(status, code, message, retryAfterMs) {
-        super(status, code, message);
+    constructor(status, errorCode, message, retryAfterMs) {
+        super(status, errorCode, message);
         this.retryAfterMs = retryAfterMs;
     }
 }
-export class RateLimitedError extends APIError {
-    retryAfterMs;
-    constructor(status, code, message, retryAfterMs) {
-        super(status, code, message);
-        this.retryAfterMs = retryAfterMs;
-    }
+/** 429 —— per-principal 限流。`retryAfterMs` 来自 `Retry-After`(SDK 重试时遵守它)。
+ *  自 SDK 1.1.0 起继承 {@link LimitExceededError}(`limit.*` 族的成员码 `limit.rate_exceeded` /
+ *  `limit.cost_quota_exceeded` 就是从这里下来的)——**additive**:既有 `instanceof RateLimitedError`
+ *  一字不改,同时 `catch (e instanceof LimitExceededError)` 也能一把接住整族。 */
+export class RateLimitedError extends LimitExceededError {
 }
-/** 429 `code:"quota_exhausted"` — the principal's usage quota (token windows / budget) is exhausted
+/** 429 `errorCode:"quota_exhausted"` — the principal's usage quota (token windows / budget) is exhausted
  *  (E4 double-rail, service ≥1.150.0). Extends RateLimitedError so existing 429 handling still matches;
  *  carries the structured deny detail so the RENDER layer can produce a human message (人话归壳 — the wire
  *  stays structured, no display strings here). NOT usefully retryable inside the deny window. */
 export class QuotaExhaustedError extends RateLimitedError {
     detail;
-    constructor(status, code, message, retryAfterMs, detail) {
-        super(status, code, message, retryAfterMs);
+    constructor(status, errorCode, message, retryAfterMs, detail) {
+        super(status, errorCode, message, retryAfterMs);
         this.detail = detail;
     }
 }
-/** 400 `code:"scenario_not_allowed"` — the request's explicit `body.scenario` is outside the principal's
+/** 400 `errorCode:"scenario_not_allowed"` — the request's explicit `body.scenario` is outside the principal's
  *  assigned allowlist (scenario governance, service ≥1.152.0). Carries the service's
  *  `allowlist` VERBATIM (pure scenario names) so the RENDER layer can offer the valid choices (人话归壳 —
  *  the wire stays structured, no display strings here). NOT retryable verbatim: pick a scenario from
  *  `allowlist`, or omit `scenario` entirely to run on the assigned default. */
 export class ScenarioNotAllowedError extends APIError {
     allowlist;
-    constructor(status, code, message, 
+    constructor(status, errorCode, message, 
     /** The principal's allowed scenario names (may be empty on an older service / defensive drop). */
     allowlist) {
-        super(status, code, message);
+        super(status, errorCode, message);
         this.allowlist = allowlist;
     }
 }
@@ -89,8 +148,8 @@ export class BudgetExceededError extends APIError {
 /** 409 — session already has an active run, or an idempotency conflict / session CAS conflict. */
 export class ConflictError extends APIError {
     activeTaskId;
-    constructor(status, code, message, activeTaskId) {
-        super(status, code, message);
+    constructor(status, errorCode, message, activeTaskId) {
+        super(status, errorCode, message);
         this.activeTaskId = activeTaskId;
     }
 }
@@ -98,15 +157,15 @@ export class ConflictError extends APIError {
  *  lose destination history: the relation classified to `fork` or `stale` and the caller did NOT pass
  *  `{ resolution: "overwrite-dst" }`. 409, errorCode `conflict`, with the classified `relation` carrying the
  *  exclusive entry sets (mirrors the service SyncConflictError). DISTINCT from the session-CAS ConflictError
- *  (same status+code, but THIS one carries a `relation` — that's how the mapper tells them apart). Client action:
+ *  (same status+errorCode, but THIS one carries a `relation` — that's how the mapper tells them apart). Client action:
  *  surface the keep-local / keep-cloud divergence to the user; to override, re-push with `resolution:"overwrite-dst"`.
  *  NEVER auto-overwrite (a silent clobber is exactly the data loss the classifier exists to prevent). */
 export class SyncConflictError extends ConflictError {
     relation;
-    constructor(status, code, message, 
+    constructor(status, errorCode, message, 
     /** The §7 `fork`/`stale` relation with the exclusive entry sets (untyped at the JSON boundary). */
     relation) {
-        super(status, code, message);
+        super(status, errorCode, message);
         this.relation = relation;
     }
 }
@@ -115,8 +174,8 @@ export class SyncConflictError extends ConflictError {
  *  and from session-CAS 409. Client action: this pending is gone → REFETCH the inbox; do not retry the decide. */
 export class ApprovalStaleError extends APIError {
     terminal;
-    constructor(status, code, message, terminal) {
-        super(status, code, message);
+    constructor(status, errorCode, message, terminal) {
+        super(status, errorCode, message);
         this.terminal = terminal;
     }
 }
@@ -125,8 +184,8 @@ export class ApprovalStaleError extends APIError {
  *  Client action: REFETCH the PendingCheckpoint, RE-PRESENT it to the human, NEVER auto-retry. */
 export class ApprovalBindingMismatchError extends APIError {
     field;
-    constructor(status, code, message, field) {
-        super(status, code, message);
+    constructor(status, errorCode, message, field) {
+        super(status, errorCode, message);
         this.field = field;
     }
 }
@@ -136,18 +195,43 @@ export class ApprovalBindingMismatchError extends APIError {
  *  again (retryable). */
 export class ApprovalConcurrentlyReopenedError extends APIError {
 }
+/** `steering.*` 族的基类(SDK 1.1.0 —— 从**逐码枚举**改成**前缀分派**,与 `stop.*` / `decide.*` 同形)。
+ *
+ *  🔴 改之前是这样的:server 真能发 5 个 `steering.*` 码,SDK 只 `===` 认了 2 个,另 3 个
+ *  (`ambiguous_label` / `ambiguous_target` / `still_running`)塌成通用 409 `ConflictError` —— 一个**开集**
+ *  被当成闭集写。契约套件第一批用「钉版 server 产物扫码 → 逐码喂 mapper」把这 3 条塌型做成了
+ *  `STEERING_COLLAPSED_BASELINE = 3` 的棘轮读数,本批销账(基线降到 0)。
+ *
+ *  ⚠️ 前缀开集的代价必须说清楚:那 3 个码此前偶然是 `ConflictError`(因为它们是 409),现在**不再是**了。
+ *  这是有意的 —— 「409」是传输层的巧合,「steer 目标有歧义」才是消费端要分支的东西;按 [clean-cut] 硬切,
+ *  不留双继承之类的兼容层。整族一把接:`catch (e instanceof SteeringError)`。 */
+export class SteeringError extends APIError {
+}
 /** design/80 D-A — you steered a run that is NOT running (it is durable-`suspended`, terminal, or unknown).
  *  Steer is at-most-once and NOT queued. Client action: surface "task isn't running"; if suspended, the path
  *  forward is the approval decide, not a steer. */
-export class SteeringNotRunningError extends APIError {
+export class SteeringNotRunningError extends SteeringError {
 }
 /** design/80 D-A — the steer text carried a control-plane escape (e.g. `</system-reminder>`) and core rejected
  *  it (runtask.ts:489). Client action: it's an injection attempt or a malformed steer — surface it; don't retry
  *  verbatim. (The BFF also fences steer text defensively; this is core's authoritative reject.) */
-export class SteeringInvalidContentError extends APIError {
+export class SteeringInvalidContentError extends SteeringError {
+}
+/** `steering.ambiguous_target`(子代 steer/resume 面,server `http/routes/runs.ts`)/
+ *  `steering.ambiguous_label`(workflow agent steer 面,`http/routes/workflows.ts`)—— **这一个 run 里有
+ *  不止一个活体匹配你给的 target/label**,server 拒绝替你猜。409。
+ *  Client action:两个码同一个处置 —— **换一个唯一的定位方式**(子代面用 `parentToolCallId`;workflow 面
+ *  用更具体的 label/句柄),原样重试永远同一个结果。`.errorCode` 区分是哪条轴上歧义。 */
+export class SteeringAmbiguousTargetError extends SteeringError {
+}
+/** `steering.still_running` —— 你对一个**还在飞**的子代调了 `resume`(revive 只在 settle 之后合法;
+ *  也可能是上一次 resume 还没落地)。409。
+ *  Client action:要么改调 steer(给在跑的它递话),要么等它 settle 再 resume。**与
+ *  {@link SteeringNotRunningError} 正好互为反面**,两个码塌在一起会让 UI 说反话。 */
+export class SteeringStillRunningError extends SteeringError {
 }
 /** `413` + `steer.content_too_large` / `reason_too_large` —— 请求里某个**自由文本**字段超过 server 的字符上限。
- *  两个成员码同族同处置,所以共用一个类型(`err.code` 保留具体是哪一个):
+ *  两个成员码同族同处置,所以共用一个类型(`err.errorCode` 保留具体是哪一个):
  *   · `steer.content_too_large`(server 1.279.2):steer 入参上限 256 KiB。脱敏门是同步的,一次超大 steer 卡住的
  *     是整个副本,所以服务端**拒**而不是先截 —— 先截会让引擎的 `[+N chars]` 披露低报。
  *   · `reason_too_large`(server 1.284.0):审批决定的 `reason` 上限 4096 字符,`/decide` 与 plan_review 两道门同值。
@@ -160,7 +244,7 @@ export class PayloadTooLargeError extends APIError {
  *  `stop.not_local`(run 在别的副本,无本地进程可 kill)/ `stop.not_landed`(kill 尝试了未落地)/
  *  `stop.parked`(行在 parked,无活跃进程)/ `stop.park_resume_won`(stop 与「审批落地→恢复」竞态,
  *  恢复赢了)/ `stop.park_arbiter_unreachable`(仲裁店不可达,真相未知——core 1.397 三分)。
- *  开集:未来新 `stop.*` 码同样落到本类(`code` 原样携带),消费方 switch 要留 default。 */
+ *  开集:未来新 `stop.*` 码同样落到本类(`errorCode` 原样携带),消费方 switch 要留 default。 */
 export class TaskStopConflictError extends ConflictError {
 }
 /** design/80 D-G (direct-connect door, service [84]) — the signed principal JWT (`X-Approval-Principal-Token`)
@@ -205,8 +289,8 @@ export class ResumeOutcomeInvalidError extends APIError {
  *  longer admissible. Not a race: retrying as-is stays blocked until the policy or the request changes. */
 export class ResumeBlockedByPolicyError extends APIError {
     blockedBy;
-    constructor(status, code, message, blockedBy) {
-        super(status, code, message);
+    constructor(status, errorCode, message, blockedBy) {
+        super(status, errorCode, message);
         this.blockedBy = blockedBy;
     }
 }
@@ -220,7 +304,7 @@ export class ResumeBlockedByPolicyError extends APIError {
 // "re-check the pending list"). These types are what makes it branchable without string-matching a message.
 /** 409 `resume.*`(dot 前缀;design/122 D2)—— subagent revive 的合同拒绝族:still_running(等 settle)/
  *  retain_off(父 run 没开 retainSubagentSessions)/evicted(留存被逐)/cap(留存上限)/
- *  session_not_found。前缀开集:core 未来新码至少落到本类(`.code` 判别),不塌匿名 409。
+ *  session_not_found。前缀开集:core 未来新码至少落到本类(`.errorCode` 判别),不塌匿名 409。
  *  ⚠️ 与下划线形的 resume_outcome_invalid / resume_blocked_by_policy 是**两族**(那两个在上面,先判)。 */
 export class SubagentResumeConflictError extends ConflictError {
 }
@@ -229,7 +313,7 @@ export class SubagentResumeConflictError extends ConflictError {
 export class WakeGatePendingError extends ConflictError {
 }
 /** 409 `compact.not_running` / `detach.not_running` —— replica-local live-verb 族:run 已终态,或活在
- *  另一副本(手动 compact/detach 只对本副本的活流有效)。`.code` 判别是哪个 verb。 */
+ *  另一副本(手动 compact/detach 只对本副本的活流有效)。`.errorCode` 判别是哪个 verb。 */
 export class RunNotLiveError extends ConflictError {
 }
 /** Base of the `decide.*` family — catch this to handle the whole decide door in one place.
@@ -239,10 +323,10 @@ export class RunNotLiveError extends ConflictError {
 export class DecideError extends APIError {
     taskId;
     rollback;
-    constructor(status, code, message, taskId, 
+    constructor(status, errorCode, message, taskId, 
     /** revive legs only — the claim-rollback disposition the server reported. */
     rollback) {
-        super(status, code, message);
+        super(status, errorCode, message);
         this.taskId = taskId;
         this.rollback = rollback;
     }
@@ -280,110 +364,124 @@ function classifyApiError(status, body, retryAfterMs) {
     // the typed code) instead of crashing scrub() INSIDE the error path (a throw here would mask the real HTTP
     // failure with a TypeError).
     // ⚠️ 纠正(2026-07-25):这段注释原先说「scenario-detail 的 404 body 就是 `{error:{code:…}}`」——已不成立,
-    // server [939] 把那一路统一成了「字符串 `error` + 顶层 `errorCode`」(亲读 `http/server.ts:1517-1527` 确认)。
+    // server [939] 把那一路统一成了「字符串 `error` + 顶层 `errorCode`」(亲读 `src/http/routes/capabilities.ts` 确认)。
     // 本分支**保留**,但定位从「适配某条已知路由」改为「防御任何对象形 error body」:它不该是任何路由的期望形,
     // 而是错误路径上不许崩的兜底。真形走下面 `b.errorCode` 那条(优先级更高)。
     const errField = body?.error;
     const nestedCode = typeof errField === "object" && errField !== null && typeof errField.code === "string"
         ? errField.code
         : undefined;
-    // 🔴 `?? b.code` 是 2026-07-25 补的兜底,补的是一个真缺陷:server 在 `/decide` 上把 CheckpointError 家族的码
-    //    发在 **`code`** 字段(`http/server.ts` 的 `body: { error: e.message, code: e.code, … }`),而这里此前只看
-    //    `errorCode` ⇒ 那一族(`checkpoint.*`/`resume.*`/`wake.*`)的 `APIError.code` **恒为 undefined**,并且下面
-    //    两条既有映射(checkpoint.already_resolved / checkpoint.reopened_concurrently)在那条路上**不可达**。
-    //    优先级刻意是 errorCode > nested > code:server 在 `checkpoint.invalid_outcome` 上正是「`code` 留原码、
-    //    `errorCode` 另铸一个 gate-appropriate 码」,重铸必须压过原码,否则那次刻意区分就被这条兜底抹平了。
-    //    机器枚举过所有用裸 `code:` 发的 HTTP 错误体(memory_sync_* / resume_blocked_by_policy / quota_exhausted /
-    //    CheckpointError 族),无一与本兜底冲突;`event: error` 流帧那套(WORKER_DOWN 等)不经本函数。
-    const code = b.errorCode ?? nestedCode ?? b.code;
+    // 🔴 单键(SDK 1.0.0 / server 3.0.0 [1989][1990]):wire 上**唯一**的机器码键位是 `errorCode`。
+    //    历史留档:2026-07-25 这里曾有一条 `?? b.code` 兜底,补的是 server 在 `/decide` 上把 CheckpointError
+    //    家族的码发在裸 `code` 字段这个真缺陷(后果:`checkpoint.*`/`resume.*`/`wake.*` 一族的机器码恒为
+    //    undefined,两条既有 typed 映射在那条路上不可达)。server 3.0.0 已在**发端**根治(`http/send.ts` 的
+    //    `sendError(res,status,errorCode,message,extra)` + `/decide` 归一臂),兜底随之删除 —— 留着它只会让
+    //    「对端还在发老键」这件事被静默吸收、下游测不出来。`event: error` 流帧那套不经本函数(见 sse.ts)。
+    const errorCode = b.errorCode ?? nestedCode;
     const rawMsg = b.errorMessage ?? (typeof errField === "string" ? errField : undefined);
     const msg = scrub(rawMsg ?? nestedCode ?? `HTTP ${status}`);
-    // scenario governance — the service 400 keys the typed code on `code` (same posture as the E4 quota
-    // 429; the worker envelope's `errorCode` stays untouched for every other route). The allowlist passes
-    // through with a per-entry type guard (a malformed entry is dropped, never crashes the error path); a bare
-    // code with no/bad allowlist still maps to ScenarioNotAllowedError with an empty list (generic-fallback).
-    // (`code` 已由上面的通用兜底吸收了 `b.code`,所以这里不再需要 `code ?? b.code` 的特判形 —— 2026-07-25 收掉,
-    //  免得读者以为有两套取码机制在并行。)
-    if (code === "scenario_not_allowed") {
+    // scenario governance — server 侧 `HttpError(400, msg, { code: "scenario_not_allowed", extra:{allowlist} })`
+    // 经 `sendError` 落到 wire 的 `errorCode` 单键。The allowlist passes through with a per-entry type guard
+    // (a malformed entry is dropped, never crashes the error path); a bare code with no/bad allowlist still maps
+    // to ScenarioNotAllowedError with an empty list (generic-fallback contract).
+    if (errorCode === "scenario_not_allowed") {
         const allowlist = Array.isArray(b.allowlist) ? b.allowlist.filter((x) => typeof x === "string" && x.length > 0) : [];
         return new ScenarioNotAllowedError(status, "scenario_not_allowed", msg, allowlist);
     }
-    if (code === "budget.precall" || code === "budget.exceeded")
-        return new BudgetExceededError(status, code, msg);
+    if (errorCode === "budget.precall" || errorCode === "budget.exceeded")
+        return new BudgetExceededError(status, errorCode, msg);
     // server ≥1.309:drain 503 有机器码;旧 server 只发 error:"draining" 字面(冻结契约)——两形同映射,
     // 消费端 instanceof DrainingError 即可,不再抄文案。retryAfterMs 由调用方从 retry-after 头喂入(见 transport)。
-    if (code === "draining" || (status === 503 && errField === "draining"))
+    if (errorCode === "draining" || (status === 503 && errField === "draining"))
         return new DrainingError(status, "draining", msg, retryAfterMs);
     // design/80 D-1 — keyed on errorCode, NOT status (both are independent of the session-CAS 409 ConflictError).
     // [1833] G13:taskStop 409 五形(stop.* 前缀开集)→ typed(壳此前手抄 code 自判,engineTaskHandleWire.ts:186-197)
-    if (typeof code === "string" && code.startsWith("stop."))
-        return new TaskStopConflictError(status, code, msg);
-    if (code === "approval_stale" || code === "checkpoint.already_resolved")
-        return new ApprovalStaleError(status, code, msg, b.terminal);
-    if (code === "checkpoint.reopened_concurrently")
-        return new ApprovalConcurrentlyReopenedError(status, code, msg); // D-1 transient (core 1.101.0)
-    if (code === "approval_binding_mismatch" || code === "checkpoint.invalid_outcome")
-        return new ApprovalBindingMismatchError(status, code, msg, b.field);
+    if (typeof errorCode === "string" && errorCode.startsWith("stop."))
+        return new TaskStopConflictError(status, errorCode, msg);
+    if (errorCode === "approval_stale" || errorCode === "checkpoint.already_resolved")
+        return new ApprovalStaleError(status, errorCode, msg, b.terminal);
+    if (errorCode === "checkpoint.reopened_concurrently")
+        return new ApprovalConcurrentlyReopenedError(status, errorCode, msg); // D-1 transient (core 1.101.0)
+    if (errorCode === "approval_binding_mismatch" || errorCode === "checkpoint.invalid_outcome")
+        return new ApprovalBindingMismatchError(status, errorCode, msg, b.field);
     // ASSISTANT-WIRE-CONTRACT §4b/§4c — 错门守卫, 键于 errorCode（都是 409 但语义 ≠ session-CAS ConflictError, 不能塌进通用 409）。
-    if (code === "gate_not_resumable")
-        return new GateNotResumableError(status, code, msg); // §4b resume 撞 human/policy_ask
-    if (code === "gate_not_plan_review")
-        return new GateNotPlanReviewError(status, code, msg); // §4c plan_review 撞非 plan_review
-    if (code === "steering.not_running")
-        return new SteeringNotRunningError(status, code, msg); // design/80 D-A
-    if (code === "steering.invalid_content")
-        return new SteeringInvalidContentError(status, code, msg); // design/80 D-A (422)
+    if (errorCode === "gate_not_resumable")
+        return new GateNotResumableError(status, errorCode, msg); // §4b resume 撞 human/policy_ask
+    if (errorCode === "gate_not_plan_review")
+        return new GateNotPlanReviewError(status, errorCode, msg); // §4c plan_review 撞非 plan_review
+    // `steering.*` —— 前缀分派(SDK 1.1.0,与 `stop.*` / `decide.*` 同形;见 SteeringError 顶注)。
+    // 未来 server 新铸的 steering 码至少落到 SteeringError 基类,不再塌成匿名 409。
+    if (errorCode?.startsWith("steering.")) {
+        if (errorCode === "steering.not_running")
+            return new SteeringNotRunningError(status, errorCode, msg); // design/80 D-A
+        if (errorCode === "steering.invalid_content")
+            return new SteeringInvalidContentError(status, errorCode, msg); // design/80 D-A (422)
+        // 两个「歧义」码同一个处置(换唯一定位方式)⇒ 共用一个类,`.errorCode` 保留是哪条轴。
+        if (errorCode === "steering.ambiguous_target" || errorCode === "steering.ambiguous_label") {
+            return new SteeringAmbiguousTargetError(status, errorCode, msg);
+        }
+        if (errorCode === "steering.still_running")
+            return new SteeringStillRunningError(status, errorCode, msg);
+        return new SteeringError(status, errorCode, msg);
+    }
     // 自由文本超上限族(413):两个成员码同处置 —— 缩短后重发,重试原文无意义。见 PayloadTooLargeError 顶注。
-    if (code === "steer.content_too_large" || code === "reason_too_large")
-        return new PayloadTooLargeError(status, code, msg);
+    if (errorCode === "steer.content_too_large" || errorCode === "reason_too_large")
+        return new PayloadTooLargeError(status, errorCode, msg);
+    // 413 `workspace_file_too_large` —— **铸造点从 WorkspaceResource.file 挪到这里**(S2 收编,SDK 1.1.0)。
+    // 原先的理由是「errorCode 是这个面独有的,面局部判别就够了」;实况证否了它:面局部的手写分支恰恰是
+    // 唯一没有任何 mapper 测试保护的地方,S2 就死在那里(读裸 `code`,typed 类真机零触发)。
+    // 两个结构化字段都在才铸(缺一个 ⇒ web 的卡拿到 undefined,不如老实降级成通用 413)。
+    if (errorCode === "workspace_file_too_large" && typeof b.sizeBytes === "number" && typeof b.limit === "number") {
+        return new WorkspaceFileTooLargeError(status, errorCode, msg, b.sizeBytes, b.limit);
+    }
     // design/80 D-G (direct-connect door, service [84]) — service-locked wire codes; forward-draft until M2 BFF signer.
-    if (code === "principal_unverified")
-        return new PrincipalUnverifiedError(status, code, msg);
-    if (code === "principal_unbound")
-        return new PrincipalUnboundError(status, code, msg); // cnf.bnd ≠ SHA256(token) = token-lift
-    if (code === "approval_mac_required")
-        return new ApprovalMacRequiredError(status, code, msg);
-    if (code === "approval_mac_invalid")
-        return new ApprovalMacInvalidError(status, code, msg);
+    if (errorCode === "principal_unverified")
+        return new PrincipalUnverifiedError(status, errorCode, msg);
+    if (errorCode === "principal_unbound")
+        return new PrincipalUnboundError(status, errorCode, msg); // cnf.bnd ≠ SHA256(token) = token-lift
+    if (errorCode === "approval_mac_required")
+        return new ApprovalMacRequiredError(status, errorCode, msg);
+    if (errorCode === "approval_mac_invalid")
+        return new ApprovalMacInvalidError(status, errorCode, msg);
     // resume 侧两个 server 刻意铸出来的码(见各自类注释)。
-    if (code === "resume_outcome_invalid")
-        return new ResumeOutcomeInvalidError(status, code, msg);
-    if (code === "resume_blocked_by_policy") {
-        return new ResumeBlockedByPolicyError(status, code, msg, typeof b.blockedBy === "string" ? b.blockedBy : undefined);
+    if (errorCode === "resume_outcome_invalid")
+        return new ResumeOutcomeInvalidError(status, errorCode, msg);
+    if (errorCode === "resume_blocked_by_policy") {
+        return new ResumeBlockedByPolicyError(status, errorCode, msg, typeof b.blockedBy === "string" ? b.blockedBy : undefined);
     }
     // 2026-07-28 补齐批:三小族(此前裸串)。resume.* 是 dot 前缀开集——必须排在上面两个下划线码之后。
-    if (code?.startsWith("resume."))
-        return new SubagentResumeConflictError(status, code, msg);
-    if (code === "wake.gate_pending")
-        return new WakeGatePendingError(status, code, msg);
-    if (code === "compact.not_running" || code === "detach.not_running")
-        return new RunNotLiveError(status, code, msg);
+    if (errorCode?.startsWith("resume."))
+        return new SubagentResumeConflictError(status, errorCode, msg);
+    if (errorCode === "wake.gate_pending")
+        return new WakeGatePendingError(status, errorCode, msg);
+    if (errorCode === "compact.not_running" || errorCode === "detach.not_running")
+        return new RunNotLiveError(status, errorCode, msg);
     // decide.* 家族 —— 前缀分派,按「调用方该做什么」分组(见 DecideError 上方那段注释)。
     // 前缀式而非逐码穷举:server 新增一个 decide.* 码时,它至少会落到 DecideError 基类(带 taskId,可被
     // `catch (e instanceof DecideError)` 接住),而不是塌成一个匿名 409 —— 未知码的降级仍然是有信息的。
-    if (code?.startsWith("decide.")) {
+    if (errorCode?.startsWith("decide.")) {
         const taskId = typeof b.taskId === "string" ? b.taskId : undefined;
         const rollback = typeof b.rollback === "string" ? b.rollback : undefined;
         // 重查 pending 列表后再决定
-        if (code === "decide.not_parked" || code === "decide.gate_moved" || code === "decide.claim_lost") {
-            return new DecideParkMovedError(status, code, msg, taskId, rollback);
+        if (errorCode === "decide.not_parked" || errorCode === "decide.gate_moved" || errorCode === "decide.claim_lost") {
+            return new DecideParkMovedError(status, errorCode, msg, taskId, rollback);
         }
         // 换 decide 形(原样重试无意义)
-        if (code === "decide.parked_answer_unsupported" || code === "decide.parked_question_unsupported" || code === "decide.parked_remember_unsupported") {
-            return new DecideUnsupportedError(status, code, msg, taskId, rollback);
+        if (errorCode === "decide.parked_answer_unsupported" || errorCode === "decide.parked_question_unsupported" || errorCode === "decide.parked_remember_unsupported") {
+            return new DecideUnsupportedError(status, errorCode, msg, taskId, rollback);
         }
         // 原样重试
-        if (code === "decide.store_unreachable")
-            return new DecideStoreUnreachableError(status, code, msg, taskId, rollback);
+        if (errorCode === "decide.store_unreachable")
+            return new DecideStoreUnreachableError(status, errorCode, msg, taskId, rollback);
         // 其余(row_unrevivable / revive_failed / revive_rejected)= 交给人看
-        return new DecideError(status, code, msg, taskId, rollback);
+        return new DecideError(status, errorCode, msg, taskId, rollback);
     }
     if (status === 429) {
-        // E4 quota deny — the SERVICE 429 body keys the typed code on `code` (NOT `errorCode`; the
-        // worker envelope's errorCode stays untouched for every other route). Structured fields pass through
-        // VERBATIM with type guards (a malformed field is dropped, never crashes the error path); a bare code
-        // with no fields still maps to QuotaExhaustedError with an empty detail (generic-fallback contract).
-        if (code === "quota_exhausted") { // 同上:通用兜底已覆盖 `b.code` 这个键位
+        // E4 quota deny — the SERVICE 429 body keys the typed code on `errorCode` (`sendError(res, 429,
+        // "quota_exhausted", …)`, server 3.0 单键). Structured fields pass through VERBATIM with type guards
+        // (a malformed field is dropped, never crashes the error path); a bare code with no fields still maps
+        // to QuotaExhaustedError with an empty detail (generic-fallback contract).
+        if (errorCode === "quota_exhausted") {
             const detail = {
                 ...(b.windowType === "fiveHour" || b.windowType === "weekly" || b.windowType === "budget" ? { windowType: b.windowType } : {}),
                 ...(typeof b.remaining === "number" && Number.isFinite(b.remaining) ? { remaining: b.remaining } : {}),
@@ -392,20 +490,54 @@ function classifyApiError(status, body, retryAfterMs) {
                 ...(typeof b.pool === "string" ? { pool: b.pool } : {}),
                 ...(typeof b.retryAfterSec === "number" && Number.isFinite(b.retryAfterSec) ? { retryAfterSec: b.retryAfterSec } : {}),
             };
-            return new QuotaExhaustedError(status, code, msg, retryAfterMs, detail);
+            return new QuotaExhaustedError(status, errorCode, msg, retryAfterMs, detail);
+        }
+        // `limit.rate_exceeded` / `limit.cost_quota_exceeded` 也从这里出去 —— RateLimitedError 是
+        // LimitExceededError 的子类,所以走这条更具体的腿**不会**让 `limit.*` 族的兜底落空,反而多带了
+        // `retryAfterMs`。⚠️ 正因如此,下面的 `limit.` 前缀分派必须排在 429 之后(排前面会把这条腿吃掉)。
+        return new RateLimitedError(status, errorCode, msg, retryAfterMs);
+    }
+    // ── 附录 A 判据三:9 个稳定前缀族的兜底 ────────────────────────────────────────────────────────
+    // 位置:所有**具名码**的精确分派之后(具体优先于粗分支)、状态码兜底之前(键位优先于状态)。
+    // 🔴 中间那句不是可有可无的排序偏好:`state.*` 全是 503,若让 `status === 503` 先手,它们会被铸成
+    //    AuthError —— 「稍后重试」读成「你没有权限」。所以前缀族**必须**排在状态兜底之前。
+    if (errorCode !== undefined) {
+        if (errorCode.startsWith("auth."))
+            return new AuthError(status, errorCode, msg); // 401/403/503 三种状态同一族
+        if (errorCode.startsWith("request.")) {
+            // 族内唯一分岔:「太大了」的处置更具体(缩短后重发),与 steer/reason 两个扁平码同类。
+            if (errorCode === "request.payload_too_large")
+                return new PayloadTooLargeError(status, errorCode, msg);
+            return new BadRequestError(status, errorCode, msg);
         }
-        return new RateLimitedError(status, code, msg, retryAfterMs);
+        if (errorCode.startsWith("not_found."))
+            return new NotFoundError(status, errorCode, msg);
+        // `conflict.*` 复用 ConflictError —— 它本来就携带 `activeTaskId`,正是 `conflict.session_active_run`
+        // 要消费的那个字段。⚠️ 裸码 `conflict`(session-sync 的扁平码)**不**以 `conflict.` 开头,不受影响,
+        // 仍走下面 SyncConflictError / 409 那两条腿。
+        if (errorCode.startsWith("conflict."))
+            return new ConflictError(status, errorCode, msg, b.activeTaskId);
+        if (errorCode.startsWith("limit."))
+            return new LimitExceededError(status, errorCode, msg, retryAfterMs);
+        if (errorCode.startsWith("capability."))
+            return new CapabilityUnavailableError(status, errorCode, msg);
+        if (errorCode.startsWith("feature."))
+            return new FeatureDisabledError(status, errorCode, msg);
+        if (errorCode.startsWith("internal."))
+            return new InternalServerError(status, errorCode, msg);
+        if (errorCode.startsWith("state."))
+            return new ServiceStateError(status, errorCode, msg);
     }
     if (status === 401 || status === 503)
-        return new AuthError(status, code, msg);
+        return new AuthError(status, errorCode, msg);
     // 2c session-sync: a 409 `conflict` that CARRIES a fork/stale `relation` is the SyncConflictError (distinct from
     // the session-CAS ConflictError, which has no `relation`). Keyed on the relation's presence + tag, not status alone.
-    if (status === 409 && code === "conflict" && (b.relation?.relation === "fork" || b.relation?.relation === "stale")) {
-        return new SyncConflictError(status, code, msg, b.relation);
+    if (status === 409 && errorCode === "conflict" && (b.relation?.relation === "fork" || b.relation?.relation === "stale")) {
+        return new SyncConflictError(status, errorCode, msg, b.relation);
     }
     if (status === 409)
-        return new ConflictError(status, code, msg, b.activeTaskId);
-    return new APIError(status, code, msg);
+        return new ConflictError(status, errorCode, msg, b.activeTaskId);
+    return new APIError(status, errorCode, msg);
 }
 // ── control plane (sema-registry /api/config/*) typed errors ────────────────────────────────────────────
 // The control plane is a DIFFERENT backend from the worker /v1 plane and uses a DIFFERENT error envelope: