@sema-agent/client-core 0.19.0 → 0.20.0

package/dist/attachmentsWireCaps.js

@@ -4,8 +4,7 @@
 /**
  * src/sema/attachmentsWireCaps.ts — design/133 + G1 turn-boundary attachments WIRE pure-projection:
  * the shell's intent → the top-level `TaskRequest.attachments` object the service normalizes
- * (spec-fields.ts normalizeAttachments, @sema-ai/server 1.128.0) → core `TaskSpec.attachments`
- * (all producers opt-in engine-side; core 1.253).
+ * (spec-fields.ts normalizeAttachments) → core `TaskSpec.attachments`.
  *
  * DEFAULT ON for the TOC live path ([487]② — CC parity): CC's own /compact announces the still
  * pending/running background tasks after compaction and notices newly-available deferred tools at
@@ -19,8 +18,54 @@
  *     only; interactive deployments stay byte-identical) is respected until a behavior leg says
  *     otherwise.
  *
- * Core wire contract (board [479] ask-2): literal-true unions — "off = DELETE the key, never send
- * false". This projection never emits `false`; OFF ⇒ `undefined` ⇒ no `attachments` field at all.
+ * ══ 🔴 FIX⑤(2026-08-07)—— 这个字段下面其实躺着**两族契约**,此前只实现了一族 ═══════════════
+ *
+ * 契约真源 = `@sema-agent/sdk` `types.d.ts` 的 `TaskRequest.attachments`(6.3.0 起 10 键)。
+ * 两族的「关」是两种**不同**的动作,混为一谈就必然有一族关不掉:
+ *
+ *  ① **literal-true 族**(7 员:todoReminder / changedFiles / planModeReminder / budgetUsd /
+ *     backgroundTasks / toolsDelta / mcpInstructions,外加取值型的 todoReminderMode):
+ *     引擎侧默认**关**,键在场即开。板 [479] ask-2 的原话是「off = DELETE the key, never send
+ *     false」—— 对这一族,发 `false` 是违约(核心根本没有「显式关」这个语义位),所以本模块对
+ *     它们**永不产出 false**:OFF ⇒ 键不出现。
+ *
+ *  ② **explicit-false 族**(2 员:agentListing / skillsListing):
+ *     它们在 core 里是 **DEFAULT-ON**,SDK 头注写死「`agentListing`/`skillsListing` 是 core
+ *     DEFAULT-ON —— **explicit false 才关**(1.254 起 false 真透传;更老 server 静默丢)」。
+ *     于是「删键」在这一族上的含义是**保持开着**,而不是关掉。旧的 `AttachmentsSpec` 把全部键
+ *     钉成 `?: true`,literal 类型层面就表达不出 `false` ⇒ 这两个 DEFAULT-ON 的附件**没有任何
+ *     路径可以关闭**(不是「难关」,是类型层封死)。本批把这两键的类型放宽成 `boolean` 并给出
+ *     产出 `false` 的路径。
+ *
+ * ── env 面(`SEMA_ATTACHMENTS`)的取值语法,以及为什么选这一种 ────────────────────────────────
+ * 目标是「**默认行为逐字节不变** + 有路可关 DEFAULT-ON 两键」,所以选了**在既有值上加逗号 token
+ * 列表**,而不是新开一个 env:
+ *   · 新开一个 env(如 `SEMA_ATTACHMENTS_OFF`)会让「附件面怎么配」有两个入口,而两个入口之间的
+ *     优先级又要再定义一次 —— 这类第二真源正是本仓反复登记的病族;
+ *   · 逗号 token 列表对**存量取值零影响**:`unset` / `full` / `all` / off 拼法四种老写法解析结果
+ *     逐字节不变(FIX7 段 ⑤ 有正面钉),新语法只在用户真写了逗号 token 时才被触发。
+ * 语法(逗号分隔,大小写不敏感,允许空白):
+ *   · `off|0|false|no|none`(整值)     ⇒ **真·全关**:literal-true 族一个不发(那一族的 off 就是
+ *                                        删键)+ DEFAULT-ON 两键发 `false`。
+ *     🔴 codex 复审 [medium](2026-08-07)判的真病:这一支此前直接 `return undefined`(不发字段),
+ *     而「不发字段」对 DEFAULT-ON 两键的含义**恰恰是保持开着** —— 一个叫 off 的总开关关不掉十件里
+ *     的两件,且用户没有任何办法察觉。旧行为在 <1.254 的 server 上与新行为**逐字节等价**(那些
+ *     server 静默丢 false),在 ≥1.254 上新行为才第一次兑现这个旋钮的字面承诺。
+ *     ⚠️ **能力边界说清楚**(codex 复审二轮):本模块是**纯 env→spec 投影**,手里没有 server
+ *     版本/capability 这个量,所以对 <1.254 的部署它兑现不了「全关」—— 那两键仍会默认开着,而
+ *     壳侧无从察觉。补这个洞的正位在**请求装配层**(按已探到的 capability 判,与 limitsWire 的
+ *     两道地板同族),已记进 docs/refactor/README.md 的宿主/上游工单表。本层只保证两件:
+ *     ① 新行为在任何 server 代际上都**不比旧行为差**(旧行为在所有代际上都关不掉那两键);
+ *     ② 不在自己的能力之外说大话 —— 所以上面那句「真·全关」的适用范围就是 ≥1.254。
+ *   · `full` / `all`                   ⇒ literal-true 族 7 员全开(**不含** DEFAULT-ON 两键 ——
+ *                                        不发 = 保持 core 默认开,壳不替 core 做那个决定)
+ *   · `default`                        ⇒ CC-parity 那一对(显式写出「默认」这个意思)
+ *   · `<key>` / `+<key>`               ⇒ 单点打开一个 literal-true 族成员
+ *   · `-agentListing` / `-skillsListing` ⇒ 产出 **`false`**(explicit-false 族唯一的关法)
+ *   · `todoReminderMode=baseline|off`  ⇒ 取值型键
+ * 🔴 未登记 token / 对 literal-true 族用 `-` / todoReminderMode 取闭集外的值 ⇒ **fail-loud 抛错**。
+ *    静默忽略是这条链上最坏的失效形:用户以为自己关掉了 agentListing,而请求照发、附件照进上下文,
+ *    并且没有任何一处会说出来。
  *
  * PURE — no env/file IO of its own (callers pass `env`), the verified wireCaps pattern. The CALLER
  * (seamQuery / the print-mode ask) gates the read to LIVE mode so the mock request shape never
@@ -28,21 +73,150 @@
  */
 import { hostEnv } from './hostEnv.js';
 import { envFlagOff } from './envFlag.js';
-/** The env key the shell reads. An {@link envFlagOff} spelling(REF-CC-141 dup-02 单源:
- *  `0`/`false`/`no`/`off`/`none`)⇒ no stamp; `full|all` ⇒ all five producers; unset/anything else
- *  ⇒ the CC-parity default pair. */
+/** The env key the shell reads. 取值语法见文件头注 §env。 */
 export const ATTACHMENTS_ENV = 'SEMA_ATTACHMENTS';
+/** 键面台账(机读位):加键必须同批登记,否则下方 `Covers` 双向钉编译红。 */
+export const ATTACHMENTS_SPEC_KEYS = [
+    'todoReminder',
+    'todoReminderMode',
+    'changedFiles',
+    'planModeReminder',
+    'budgetUsd',
+    'backgroundTasks',
+    'toolsDelta',
+    'mcpInstructions',
+    'agentListing',
+    'skillsListing',
+];
+/** ② 族(core DEFAULT-ON,explicit false 才关)。 */
+export const ATTACHMENTS_DEFAULT_ON_KEYS = ['agentListing', 'skillsListing'];
+/** ① 族里 `full` 会全开的那 7 员(`todoReminderMode` 是取值型,不搭 full 的车)。 */
+const LITERAL_TRUE_KEYS = [
+    'todoReminder',
+    'changedFiles',
+    'planModeReminder',
+    'budgetUsd',
+    'backgroundTasks',
+    'toolsDelta',
+    'mcpInstructions',
+];
+/** CC-parity 默认对(TOC live 路径,[487]②)。 */
+const DEFAULT_PAIR = ['backgroundTasks', 'toolsDelta'];
+const _attachmentsKeyPins = [true, true, true, true];
+void _attachmentsKeyPins;
+const TODO_REMINDER_MODES = ['baseline', 'off'];
+/** fail-loud 的统一措辞:说清**哪个 token 坏了**、以及合法形是什么(判词要指得出下一步)。 */
+function refuse(token, why) {
+    throw new Error(`${ATTACHMENTS_ENV}: refusing token "${token}" — ${why}. ` +
+        `Legal tokens: off | full | all | default | <literalTrueKey> | +<literalTrueKey> | ` +
+        `-agentListing | -skillsListing | todoReminderMode=baseline|off`);
+}
 /**
- * ENV source → the `TaskRequest.attachments` stamp. Returns `undefined` (⇒ no field) on explicit
- * opt-out; the G1 pair by default; all five on `full`. Never `false` values (core contract).
+ * ENV source → the `TaskRequest.attachments` stamp.
+ *
+ * 恒返回一个对象:literal-true 族永远只出现 `true`(core 契约:off = 删键),而
+ * `agentListing`/`skillsListing` 只在被显式关掉时出现,值恒为 `false`(它们的 core 默认是开,
+ * 不发 = 不动那个默认)。返回型保留 `| undefined` 是给未来留位,今天没有分支产出它。
+ *
+ * @throws 未登记 token / 对 literal-true 族用 `-` / todoReminderMode 取闭集外的值(fail-loud:
+ *         静默忽略会让「我明明关了」与「它其实还开着」同时为真)。
  */
 export function attachmentsForRequest(env = hostEnv()) {
     const raw = (env[ATTACHMENTS_ENV] ?? '').trim().toLowerCase();
+    // 总开关 off = 真·全关(见文件头注 §env 的 codex [medium] 登记),不是「不发字段」。
     if (envFlagOff(raw))
-        return undefined;
-    if (raw === 'full' || raw === 'all') {
-        return { todoReminder: true, changedFiles: true, planModeReminder: true, backgroundTasks: true, toolsDelta: true };
+        return allDefaultOnOff();
+    const tokens = raw.split(',').map(t => t.trim()).filter(t => t.length > 0);
+    // 存量取值零变化:空 / `full` / `all` 单 token 走与本批之前逐字节相同的两条老路。
+    if (tokens.length === 0)
+        return { backgroundTasks: true, toolsDelta: true };
+    if (tokens.length === 1 && (tokens[0] === 'full' || tokens[0] === 'all'))
+        return allLiteralTrue();
+    // 单 token 且不是任何已登记词 ⇒ 维持历史语义(「unset/anything else ⇒ 默认对」),不 fail-loud:
+    // 那是本模块自建起就写在头注里的契约,收紧它属于行为面改动,不在本批。多 token 形是**本批新增
+    // 的语法**,没有存量语义可破,所以它逐 token fail-loud。
+    if (tokens.length === 1 && !isKnownToken(tokens[0])) {
+        return { backgroundTasks: true, toolsDelta: true };
     }
-    // default (TOC CC parity): post-compact background-task recap + deferred-tools boundary notice.
-    return { backgroundTasks: true, toolsDelta: true };
+    const spec = {};
+    for (const token of tokens) {
+        if (token === 'full' || token === 'all') {
+            Object.assign(spec, allLiteralTrue());
+            continue;
+        }
+        if (token === 'default') {
+            for (const k of DEFAULT_PAIR)
+                spec[k] = true;
+            continue;
+        }
+        if (token.startsWith('-')) {
+            const key = canonicalKey(token.slice(1));
+            if (key === undefined)
+                refuse(token, 'unknown attachments key');
+            if (!isDefaultOnKey(key)) {
+                refuse(token, `"${key}" belongs to the literal-true family whose OFF is "delete the key", not "send false" ` +
+                    '(core wire contract, board [479] ask-2) — simply do not turn it on. ' +
+                    'Only the core DEFAULT-ON keys (agentListing / skillsListing) accept an explicit false');
+            }
+            spec[key] = false;
+            continue;
+        }
+        const [lhs, rhs] = splitAssign(token);
+        if (rhs !== undefined) {
+            if (canonicalKey(lhs) !== 'todoReminderMode')
+                refuse(token, 'only `todoReminderMode` takes a `key=value` form');
+            const mode = TODO_REMINDER_MODES.find(v => v === rhs);
+            if (mode === undefined)
+                refuse(token, `todoReminderMode must be one of ${TODO_REMINDER_MODES.join('|')}`);
+            spec.todoReminderMode = mode;
+            continue;
+        }
+        const key = canonicalKey(lhs.startsWith('+') ? lhs.slice(1) : lhs);
+        if (key === undefined)
+            refuse(token, 'unknown attachments key');
+        if (isDefaultOnKey(key)) {
+            refuse(token, `"${key}" is core DEFAULT-ON — turning it "on" is a no-op that would send a redundant true; ` +
+                `use "-${key}" to turn it OFF`);
+        }
+        if (key === 'todoReminderMode')
+            refuse(token, 'todoReminderMode needs a value: `todoReminderMode=baseline|off`');
+        spec[key] = true;
+    }
+    return spec;
+}
+/** 总开关 off 的产出:literal-true 族一个不发(删键即关)+ DEFAULT-ON 两键显式 `false`。 */
+function allDefaultOnOff() {
+    const out = {};
+    for (const k of ATTACHMENTS_DEFAULT_ON_KEYS)
+        out[k] = false;
+    return out;
+}
+function allLiteralTrue() {
+    const out = {};
+    for (const k of LITERAL_TRUE_KEYS)
+        out[k] = true;
+    return out;
+}
+/** `k=v` 的一次拆分(值里再有 `=` 一律归右侧,交给取值校验去拒)。 */
+function splitAssign(token) {
+    const i = token.indexOf('=');
+    return i < 0 ? [token, undefined] : [token.slice(0, i).trim(), token.slice(i + 1).trim()];
+}
+/** 大小写不敏感的键名归一(env 值整体已 lowercase,而键名是 camelCase)。 */
+function canonicalKey(lower) {
+    return ATTACHMENTS_SPEC_KEYS.find(k => k.toLowerCase() === lower);
+}
+function isDefaultOnKey(k) {
+    return ATTACHMENTS_DEFAULT_ON_KEYS.includes(k);
+}
+/** 单 token 形的历史回落判据(见 `attachmentsForRequest` 里那段注释)。 */
+function isKnownToken(token) {
+    if (token === 'full' || token === 'all' || token === 'default')
+        return true;
+    if (token.startsWith('-'))
+        return canonicalKey(token.slice(1)) !== undefined;
+    const [lhs, rhs] = splitAssign(token);
+    if (rhs !== undefined)
+        return canonicalKey(lhs) !== undefined;
+    return canonicalKey(lhs.startsWith('+') ? lhs.slice(1) : lhs) !== undefined;
 }

package/dist/controlRouter.d.ts

@@ -22,9 +22,10 @@
  *     `runs.steer(taskId, { text, mode? })`. The text is untrusted DATA — the shell sends it RAW and the
  *     SERVER fences it (the shell does NOT pre-sanitize control markers). AT-MOST-ONCE: steer is NOT
  *     idempotent, so it is NEVER retried (runs.ts:43). `mode` drains queued steers at the TURN boundary
- *     ("all" = inject all next turn; "one-at-a-time" = one per turn, FIFO). Errors are fail-closed:
- *     `SteeringNotRunningError` (run suspended/terminal — resolve its gate, don't steer) and
- *     `SteeringInvalidContentError` (the text carried a control-plane escape — SURFACE, never strip-and-retry).
+ *     ("all" = inject all next turn; "one-at-a-time" = one per turn, FIFO). Errors are fail-closed and
+ *     dispatched by the WHOLE `steering.*` family (FIX③ 2026-08-07 — 此前只认 2 个码;server 7.4.0
+ *     dist 实扫 7 个,主 run steer 路由可达 4 个)。逐码语义 + 处置见 `ControlSafetyCode` 与
+ *     文件底部的 `STEERING_CODE_TO_SAFETY` / `STEERING_ADVICE` 两张表。
  *
  *  3. **cancel** (IH-8, §5.3, catalog L84). HARD-STOP an async run: `runs.cancel(taskId)` → 202 `CancelAck`
  *     (`status:"cancelling"` or a terminal no-op). The run then SETTLES to `failed` + `errorCode:"cancelled"`
@@ -71,14 +72,47 @@ export interface RunsResourceLike {
 export interface ControlClientLike {
     runs: RunsResourceLike;
 }
-/** A supervision-verb stop the shell must HANDLE, not retry (contract/04 §9.1). The `code` is stable so the
- *  shell can branch: `not_running` (steer a non-running run) | `invalid_content` (steer carried an escape) |
- *  `cancel_lost_race` (409: 挂起的 gate 被并发决定/过期 — 重读状态后重试 cancel) | `not_found`。 */
+/**
+ * A supervision-verb stop the shell must HANDLE, not retry (contract/04 §9.1). The `code` is stable so the
+ * shell can branch.
+ *
+ * 🔴 FIX③(2026-08-07,server 7.4.0 `dist/` 亲扫)—— steering 族此前只认 2 个码。实测 `steering.*`
+ * 在 server 7.4.0 里共 **7 个**;主 run 的 `POST /v1/runs/:id/steer` 路由(本 router 唯一调用的那条)
+ * 可达其中 4 个:`not_running`(409)/ `invalid_content`(422)/ `queue_full`(409,core 5.14.0 队列
+ * 化后新出)/ `duplicate_input_id`(409,调用方带 `Idempotency-Key` 时可达);另外 3 个来自子代
+ * steer/resume 面与 workflow agent steer 面(`ambiguous_target` / `ambiguous_label` / `still_running`)。
+ * SDK 6.3.0 侧已把整族改成**前缀分派**(`SteeringError` 基类),所以「没认全」的后果不是崩溃,
+ * 而是那些码原样裸抛给壳 —— 壳只 `catch (e instanceof ControlSafetyError)` 就漏在外面。
+ *
+ * ⚠️ `still_running` 与 `not_running` **语义正相反**(前者=子代还在飞,该 steer 不该 resume;后者=
+ * 它不在飞)。两码塌进同一个判别位会让 UI 说反话,所以它们各占一个码,永不合并。
+ */
+export type ControlSafetyCode = 
+/** steer 了一个不在飞的 run(suspended/terminal/跨副本);处置=先解它的 gate,别 steer。 */
+'not_running'
+/** steer 正文带控制面越狱串,core 拒;处置=SURFACE,绝不 strip-and-retry。 */
+ | 'invalid_content'
+/** 挂起 checkpoint 上的 steer 队列满了(core fail-loud,绝不驱逐已接受的指令);处置=等它 drain。 */
+ | 'queue_full'
+/** 同一个 `Idempotency-Key` 配了**不同**正文;处置=换一个 key,别复用(重发原文没有意义)。 */
+ | 'duplicate_input_id'
+/** `ambiguous_target`(子代面)/ `ambiguous_label`(workflow 面)—— 不止一个活体匹配;
+ *  两码同一处置(换唯一定位方式),故共用一个判别位,`cause.errorCode` 保留是哪条轴。 */
+ | 'ambiguous_target'
+/** 对一个**还在飞**的子代调了 resume;处置=改调 steer,或等它 settle。`not_running` 的反面。 */
+ | 'still_running'
+/** 开集兜底:`steering.` 前缀但本表不认得的**未来**码(SDK 前缀分派同款姿势)。
+ *  处置=按「这条 steer 没落地」呈现,并把 `cause.errorCode` 原样打进日志,别按成员猜语义。 */
+ | 'steering_other'
+/** cancel 的 409:挂起的 gate 被并发决定/过期(重读状态后重试 cancel)。 */
+ | 'cancel_lost_race'
+/** 404 — non-owner / unknown run(无存在性谕示器)。 */
+ | 'not_found';
 export declare class ControlSafetyError extends Error {
-    readonly code: 'not_running' | 'invalid_content' | 'cancel_lost_race' | 'not_found';
+    readonly code: ControlSafetyCode;
     /** The original SDK error, for logging (never re-thrown blind). */
     readonly cause?: unknown | undefined;
-    constructor(message: string, code: 'not_running' | 'invalid_content' | 'cancel_lost_race' | 'not_found', 
+    constructor(message: string, code: ControlSafetyCode, 
     /** The original SDK error, for logging (never re-thrown blind). */
     cause?: unknown | undefined);
 }
@@ -146,6 +180,9 @@ export declare class ControlRouter {
      *    failure propagates; the router does NOT auto-resend (a double-steer must be impossible).
      *  - **Steer needs a RUNNING run.** A suspended/terminal run → 409 `SteeringNotRunningError` → surfaced as
      *    `ControlSafetyError('not_running')` (resolve its gate via the hitlBridge `decide`, don't steer).
+     *    🔴 FIX③:整个 `steering.*` 族(7 员)都归到 `ControlSafetyError` 上,含 core 5.14.0 队列化
+     *    新出的 `queue_full` / `duplicate_input_id`,以及与 `not_running` **语义相反**的 `still_running`
+     *    (两者永不合并);表外的未来码落开集位 `steering_other`,不再裸抛。
      *  - **`mode` drains at the TURN boundary** (FORWARD-DRAFT per-call mapping, runs.ts:49-50): `"all"` injects
      *    all queued steers at the next turn; `"one-at-a-time"` (default) one per turn, FIFO. Steer applies at
      *    the next turn boundary, not instantly.

package/dist/controlRouter.js

@@ -1,12 +1,4 @@
 import { uuid } from './adapter/types.js';
-// ── Errors the router surfaces (fail-closed; never auto-retried) ───────────────
-//
-// Mirrors hitlBridge.HitlSafetyError: every safety-relevant control error is a signal to re-present to the
-// human or surface the error, NEVER to silently retry or auto-decide (contract/04 §9.1 fail-closed law). The
-// router catches the SDK's typed errors and re-raises a stable, shell-branchable code.
-/** A supervision-verb stop the shell must HANDLE, not retry (contract/04 §9.1). The `code` is stable so the
- *  shell can branch: `not_running` (steer a non-running run) | `invalid_content` (steer carried an escape) |
- *  `cancel_lost_race` (409: 挂起的 gate 被并发决定/过期 — 重读状态后重试 cancel) | `not_found`。 */
 export class ControlSafetyError extends Error {
     code;
     cause;
@@ -99,6 +91,9 @@ export class ControlRouter {
      *    failure propagates; the router does NOT auto-resend (a double-steer must be impossible).
      *  - **Steer needs a RUNNING run.** A suspended/terminal run → 409 `SteeringNotRunningError` → surfaced as
      *    `ControlSafetyError('not_running')` (resolve its gate via the hitlBridge `decide`, don't steer).
+     *    🔴 FIX③:整个 `steering.*` 族(7 员)都归到 `ControlSafetyError` 上,含 core 5.14.0 队列化
+     *    新出的 `queue_full` / `duplicate_input_id`,以及与 `not_running` **语义相反**的 `still_running`
+     *    (两者永不合并);表外的未来码落开集位 `steering_other`,不再裸抛。
      *  - **`mode` drains at the TURN boundary** (FORWARD-DRAFT per-call mapping, runs.ts:49-50): `"all"` injects
      *    all queued steers at the next turn; `"one-at-a-time"` (default) one per turn, FIFO. Steer applies at
      *    the next turn boundary, not instantly.
@@ -113,11 +108,12 @@ export class ControlRouter {
             return await this.client.runs.steer(this.taskId, body, opts?.signal !== undefined ? { signal: opts.signal } : undefined);
         }
         catch (e) {
-            if (isSteeringNotRunning(e)) {
-                throw new ControlSafetyError('steering.not_running — the run is suspended/terminal; resolve its gate via decide, do not steer', 'not_running', e);
-            }
-            if (isSteeringInvalidContent(e)) {
-                throw new ControlSafetyError('steering.invalid_content — the steer text carried a control-plane escape; surface it, do not strip-and-retry', 'invalid_content', e);
+            // FIX③:整族逐码分派(表见文件底部)。前缀在场即归族 —— 未来新码落 `steering_other`,
+            // 绝不再裸抛给壳(裸抛 = 壳的 `instanceof ControlSafetyError` 分支整条漏在外面)。
+            const verdict = steeringVerdict(e);
+            if (verdict !== undefined) {
+                const wireCode = errCodes(e).code ?? errCodes(e).name ?? 'steering.<unknown>';
+                throw new ControlSafetyError(`${wireCode} — ${STEERING_ADVICE.get(verdict) ?? 'steering refused'}`, verdict, e);
             }
             // Any other error (auth/transport): NOT retried (steer is at-most-once) — propagate to the shell.
             throw e;
@@ -235,15 +231,51 @@ export function errCodes(e) {
     const status = typeof rawStatus === 'number' ? rawStatus : undefined;
     return { code, name, status };
 }
-/** 409 `steering.not_running` / `SteeringNotRunningError` — the run is suspended/terminal (runs.ts:45). */
-function isSteeringNotRunning(e) {
-    const { code, name } = errCodes(e);
-    return code === 'steering.not_running' || name === 'SteeringNotRunningError';
-}
-/** 422 `steering.invalid_content` / `SteeringInvalidContentError` — control-plane escape (runs.ts:46). */
-function isSteeringInvalidContent(e) {
+// ── steering 错误族的**逐码表**(FIX③,server 7.4.0 dist 亲扫 + SDK 6.3.0 errors.d.ts 对表)────
+//
+// 🔴 用 `Map` 不是对象字面量:键来自 wire 的 `errorCode` 字符串,对象字面量上 `map['__proto__']`
+//    会摸到 Object.prototype(adapt/arms.ts 头注登记的同一条纪律)。
+const STEERING_CODE_TO_SAFETY = new Map([
+    ['steering.not_running', 'not_running'],
+    ['steering.invalid_content', 'invalid_content'],
+    ['steering.queue_full', 'queue_full'],
+    ['steering.duplicate_input_id', 'duplicate_input_id'],
+    ['steering.ambiguous_target', 'ambiguous_target'],
+    ['steering.ambiguous_label', 'ambiguous_target'],
+    ['steering.still_running', 'still_running'],
+]);
+/** SDK 的 typed 子类名兜底(错误对象被传输层剥掉 `errorCode` 时仍认得族;`SteeringError` 基类本身
+ *  = 「是 steering 族但没有专属子类」⇒ 落开集臂)。 */
+const STEERING_NAME_TO_SAFETY = new Map([
+    ['SteeringNotRunningError', 'not_running'],
+    ['SteeringInvalidContentError', 'invalid_content'],
+    ['SteeringAmbiguousTargetError', 'ambiguous_target'],
+    ['SteeringStillRunningError', 'still_running'],
+    ['SteeringError', 'steering_other'],
+]);
+/** 每个判别位的处置指路(壳把它原样打给用户/日志 —— 判词必须说得出「现在该做什么」)。 */
+const STEERING_ADVICE = new Map([
+    ['not_running', 'the run is suspended/terminal/on another replica — resolve its gate via decide, do not steer'],
+    ['invalid_content', 'the steer text carried a control-plane escape; surface it, do not strip-and-retry'],
+    ['queue_full', 'the parked steering queue on this checkpoint is full (core fails loud rather than evicting an accepted instruction) — wait for it to drain, do not resend'],
+    ['duplicate_input_id', 'this Idempotency-Key is already parked with DIFFERENT steering content — reissue with a fresh key, resending verbatim will never succeed'],
+    ['ambiguous_target', 'more than one live target matches — address it uniquely (sub-agent: parentToolCallId; workflow: a more specific label); retrying verbatim yields the same result'],
+    ['still_running', 'the target is STILL RUNNING — steer it instead of resuming, or wait for it to settle (this is the exact opposite of not_running: never collapse the two)'],
+    ['steering_other', 'an unrecognized steering.* refusal (open set) — the steer did NOT land; log the errorCode verbatim, do not guess its meaning'],
+]);
+/**
+ * 把一个 steer 抛出的错误判成 steering 族的哪一位。不是 steering 族 ⇒ `undefined`(调用方原样抛,
+ * 路由器绝不越界吞 auth/transport 的错)。
+ */
+function steeringVerdict(e) {
     const { code, name } = errCodes(e);
-    return code === 'steering.invalid_content' || name === 'SteeringInvalidContentError';
+    if (typeof code === 'string' && code.startsWith('steering.')) {
+        // 前缀在场即归族:表里没有的**未来**码落开集臂,而不是漏出去(SDK 6.3.0 的同款前缀分派)。
+        return STEERING_CODE_TO_SAFETY.get(code) ?? 'steering_other';
+    }
+    if (typeof name === 'string')
+        return STEERING_NAME_TO_SAFETY.get(name);
+    return undefined;
 }
 /** A 409 on `cancel` = the pending gate was decided/expired concurrently (lost CAS race; server
  *  `conflict.approval_settled`). 🔴 它**不再**表示「run 是 suspended」——[868] 起 suspended/needs_review

package/dist/hitl/askGateWire.d.ts

@@ -73,7 +73,7 @@ import { type AskGateWireDeps } from './frameRouter.js';
 export { HITL_REJECT_MESSAGE, ENGINE_ABORT_TOOL_RESULT } from './frameRouter.js';
 export type { AskGateWireDeps } from './frameRouter.js';
 export type { AskAnsweredOutput } from './gateLedger.js';
-export { toAnsweredOutput, isAlreadyResolvedGateReason } from './parkResolver.js';
+export { toAnsweredOutput, isAlreadyResolvedGateReason, GATE_FAILURE_CODES } from './parkResolver.js';
 export type { GateOutcome, GateFailureCode } from './parkResolver.js';
 /**
  * 包一层 AgentEvent 流:把 AskUserQuestion 的 suspended park 变成「对话框 → decide → 续流」闭环。

package/dist/hitl/askGateWire.js

@@ -19,7 +19,7 @@ import { resolvePark } from './parkResolver.js';
 //    `toAnsweredOutput` / 下方 `bridgeAskUserQuestionGates`)、类型四个。定义搬去了实现所在的
 //    那一刀,本文件是它们对外的**唯一门牌**——下游 import 路径不变,public-export 基线不变。
 export { HITL_REJECT_MESSAGE, ENGINE_ABORT_TOOL_RESULT } from './frameRouter.js';
-export { toAnsweredOutput, isAlreadyResolvedGateReason } from './parkResolver.js';
+export { toAnsweredOutput, isAlreadyResolvedGateReason, GATE_FAILURE_CODES } from './parkResolver.js';
 /**
  * 包一层 AgentEvent 流:把 AskUserQuestion 的 suspended park 变成「对话框 → decide → 续流」闭环。
  * 其它事件原样透传;非 AskUserQuestion 的 gate 保持现状。fail-soft:任何桥内失败回退为

package/dist/hitl/frameRouter.js

@@ -300,7 +300,9 @@ async function routeToolApprovalFrame(ev, ctx) {
     const fromSubagent = isFromSubagent(ev);
     hostLog('debug', `liveHitlAskWire: tool_approval frame ${ev.approvalId} tool=${String(ev.toolName)}${fromSubagent ? ` from-subagent=${String(ev.sourceTaskId ?? ev.sourceAgentName ?? 'explicit')}` : ''}`);
     const gatedCallId = !fromSubagent ? led.lastPendingFsCall() : undefined;
-    const decision = await surfaceToolApprovalFrameAndRespond(ev, deps.respondToolApproval, argsOfGatedStart(led, gatedCallId), ctx.signal);
+    // FIX①(2026-08-07):产物是 `{decision, ack?}` —— ack 上的 `rememberApplied`/`updatedInputForwarded`
+    // 由 toolApprovalWire 就地收敛成宿主通知(本路由只认决断词,不重复解释 ack)。
+    const { decision } = await surfaceToolApprovalFrameAndRespond(ev, deps.respondToolApproval, argsOfGatedStart(led, gatedCallId), ctx.signal);
     if (decision === 'deny' && !fromSubagent) {
         // 该 call 的报错收口帧 stamp REJECT 文案(vendored `User rejected <op> to <path>` 卡)。
         if (gatedCallId !== undefined)

package/dist/hitl/hitlBridge.d.ts

@@ -131,11 +131,17 @@ export interface PlanReviewOutcome {
 export declare class HitlSafetyError extends Error {
     /** A stable code the shell can branch on (REF-CC-036,2026-08-02:闭集联合,不再是开集 string —
      *  与同族兄弟 `controlRouter.ts` 的 `ControlSafetyError.code` 同形)。 */
-    readonly code: 'binding_mismatch' | 'no_pending' | 'wrong_gate' | 'bad_plan_edit';
+    /** 🔴 闭集(FIX② 2026-08-07 加 `empty_answer`,第 5 员)。加员必须**同批**改齐
+     *  `parkResolver.GATE_FAILURE_CODES` 白名单 —— 那道白名单把不认得的码降成 `undefined`,
+     *  一边加一边不改另一边 = 新码在消费端被静默吞掉(比不加还坏:本地拦住了,判词却丢了)。 */
+    readonly code: 'binding_mismatch' | 'no_pending' | 'wrong_gate' | 'bad_plan_edit' | 'empty_answer';
     constructor(message: string, 
     /** A stable code the shell can branch on (REF-CC-036,2026-08-02:闭集联合,不再是开集 string —
      *  与同族兄弟 `controlRouter.ts` 的 `ControlSafetyError.code` 同形)。 */
-    code: 'binding_mismatch' | 'no_pending' | 'wrong_gate' | 'bad_plan_edit');
+    /** 🔴 闭集(FIX② 2026-08-07 加 `empty_answer`,第 5 员)。加员必须**同批**改齐
+     *  `parkResolver.GATE_FAILURE_CODES` 白名单 —— 那道白名单把不认得的码降成 `undefined`,
+     *  一边加一边不改另一边 = 新码在消费端被静默吞掉(比不加还坏:本地拦住了,判词却丢了)。 */
+    code: 'binding_mismatch' | 'no_pending' | 'wrong_gate' | 'bad_plan_edit' | 'empty_answer');
 }
 /** The active gate the downstream stream most recently suspended on (null when running). */
 export interface ActiveGate {
@@ -250,6 +256,17 @@ export declare class HitlBridge {
      * permission gate, but the answer rides `ApprovalDecision.answer` as the worker-validated
      * `{ answers: [{ header, selected, note? }] }` shape. The D-1 binding STILL binds (it is still a
      * checkpoint). Each answer's `header` MUST match a question header (the worker 400s on mismatch).
+     *
+     * 🔴 FIX②(2026-08-07)—— **本地 fail-loud**:此前本方法对 `answers: []` 与「某条 `selected: []`」
+     * 零校验,一条注定 400 的请求照样出门。这不是「多一次往返」而已 ——
+     *   · 用户面只看到「作答失败」,而失败的原因(空作答)在壳侧一个字都没说;
+     *   · `ToolPermissionDecision.answer` 的头注自己写着「a silently emptied answer is the user's
+     *     choice being thrown away without anyone noticing」—— 那条纪律此前只写在类型注释里,
+     *     没有任何一层真的执行它;
+     *   · `{answers:[]}` 在 wire 上另有确切含义(question 域 **deny** 的 NO_HUMAN 形),把它当成一次
+     *     approve 发出去 = 拿 deny 的载荷冒充 approve。
+     * 三形一律抛 `HitlSafetyError('empty_answer')`,一次 decide 都不发:空 `answers[]` /
+     * 任一条 `selected[]` 为空 / 任一条 `header` 为空串。
      */
     answerQuestion(answers: AskAnswer[], toolUseID?: string, opts?: {
         signal?: AbortSignal;

package/dist/hitl/hitlBridge.js

@@ -8,6 +8,9 @@ export class HitlSafetyError extends Error {
     constructor(message, 
     /** A stable code the shell can branch on (REF-CC-036,2026-08-02:闭集联合,不再是开集 string —
      *  与同族兄弟 `controlRouter.ts` 的 `ControlSafetyError.code` 同形)。 */
+    /** 🔴 闭集(FIX② 2026-08-07 加 `empty_answer`,第 5 员)。加员必须**同批**改齐
+     *  `parkResolver.GATE_FAILURE_CODES` 白名单 —— 那道白名单把不认得的码降成 `undefined`,
+     *  一边加一边不改另一边 = 新码在消费端被静默吞掉(比不加还坏:本地拦住了,判词却丢了)。 */
     code) {
         super(message);
         this.code = code;
@@ -185,11 +188,25 @@ export class HitlBridge {
      * permission gate, but the answer rides `ApprovalDecision.answer` as the worker-validated
      * `{ answers: [{ header, selected, note? }] }` shape. The D-1 binding STILL binds (it is still a
      * checkpoint). Each answer's `header` MUST match a question header (the worker 400s on mismatch).
+     *
+     * 🔴 FIX②(2026-08-07)—— **本地 fail-loud**:此前本方法对 `answers: []` 与「某条 `selected: []`」
+     * 零校验,一条注定 400 的请求照样出门。这不是「多一次往返」而已 ——
+     *   · 用户面只看到「作答失败」,而失败的原因(空作答)在壳侧一个字都没说;
+     *   · `ToolPermissionDecision.answer` 的头注自己写着「a silently emptied answer is the user's
+     *     choice being thrown away without anyone noticing」—— 那条纪律此前只写在类型注释里,
+     *     没有任何一层真的执行它;
+     *   · `{answers:[]}` 在 wire 上另有确切含义(question 域 **deny** 的 NO_HUMAN 形),把它当成一次
+     *     approve 发出去 = 拿 deny 的载荷冒充 approve。
+     * 三形一律抛 `HitlSafetyError('empty_answer')`,一次 decide 都不发:空 `answers[]` /
+     * 任一条 `selected[]` 为空 / 任一条 `header` 为空串。
      */
     async answerQuestion(answers, toolUseID, opts, 
     /** REF-CC-029(2026-08-02):see `decideTool`'s same-named param — the pending row the caller already
      *  fetched via `findPendingForTask`. */
     preResolvedPending) {
+        // 🔴 校验在 findPending **之前**:入参坏了跟 pending 行在不在场无关,而先 list 再拒会把
+        //    「你的作答是空的」这条真判词换成「no_pending」那条假判词(行恰好过期时)。
+        assertAnswersSendable(answers);
         const pending = preResolvedPending ?? (await this.findPending(toolUseID, opts));
         if (!pending) {
             throw new HitlSafetyError('no pending AskUserQuestion checkpoint to answer — refetch + re-present', 'no_pending');
@@ -304,6 +321,26 @@ export function makeHitlCanUseTool(bridge, prompt) {
     };
 }
 // ── helpers ───────────────────────────────────────────────────────────────────
+/**
+ * FIX②(2026-08-07):作答**出门前**的本地闭集校验(fail-closed;详见 `answerQuestion` 头注)。
+ * 只判「这批作答在 wire 上有没有意义」,不判 header 与题面对不对得上 —— 后者的真源在 worker
+ * (它持有题面),壳侧猜一份题面副本只会造出第二个真源。
+ */
+function assertAnswersSendable(answers) {
+    if (!Array.isArray(answers) || answers.length === 0) {
+        throw new HitlSafetyError('refusing to send an EMPTY AskUserQuestion answer set — `{answers:[]}` is the wire\'s DENY/NO_HUMAN form, ' +
+            'sending it as an approve would throw the human\'s choice away and 400 the worker', 'empty_answer');
+    }
+    for (const a of answers) {
+        if (typeof a?.header !== 'string' || a.header.length === 0) {
+            throw new HitlSafetyError('refusing to send an answer with an EMPTY `header` — the worker matches answers to questions BY header (400)', 'empty_answer');
+        }
+        if (!Array.isArray(a.selected) || a.selected.length === 0) {
+            throw new HitlSafetyError(`refusing to send an answer with an EMPTY \`selected\` for header "${a.header}" — ` +
+                'an emptied selection is the human\'s choice silently discarded (the worker 400s on it)', 'empty_answer');
+        }
+    }
+}
 /** Marshal one answer into the worker-validated wire entry (contract/04 §4.1). Drops undefined `note`.
  *  REF-CC-038(2026-08-02):return 类型是 `AskAnswer` 本身(唯一源),不再是一份重写的内联匿名形。 */
 function marshalAnswer(a) {

package/dist/hitl/hitlHostSurface.d.ts

@@ -37,6 +37,33 @@ export declare function surfaceForCurrentSession(): HitlHostSurface | null;
 export declare const CANCEL_DENY_BUDGET_MS = 2000;
 /** warn 行文案(测试锁字面)。 */
 export declare const CANCEL_DENY_WARN_TEXT = "could not cancel the pending question \u2014 the session may stay locked; the run may need engine-side recovery";
+/** 文案(测试锁字面)。措辞刻意描述**后果**而不是内部机制:用户要知道的是「下次还会问」。 */
+export declare const REMEMBER_NOT_APPLIED_WARN_TEXT = "this session-wide allow was not remembered by the worker \u2014 you will be asked again for this tool";
+/** 文案(测试锁字面)。"original" 是判据词:用户必须读到「跑的是原来那份」。 */
+export declare const EDIT_NOT_FORWARDED_WARN_TEXT = "your edited tool input was NOT forwarded \u2014 the tool is running with the ORIGINAL input you saw before editing";
+/**
+ * `allow_session` 决断的 ack 回报 `rememberApplied:false`(server 1.239 起诚实回显 —— 典型成因
+ * 是这条 run 没有 sessionId,grant 无处可落)。
+ *
+ * 🔴 为什么这必须上屏而不是只记 debug:三选卡第 2 项在用户心里签的是「本会话这个工具不再问我」。
+ * 记没落店而界面照渲「全放行」,就是**把一个没有发生的授权渲成发生了** —— 下一次弹卡时用户会以为
+ * 是 bug,更坏的是他可能因此养成「一路回车」的习惯。缺席(旧 server 不出这个位)= 未知,
+ * 按 [honest-absence-not-fabricated-zero] 一律不发通知,绝不把未知渲成失败。
+ * 无宿主口(print/headless 没屏)⇒ 静默,与 {@link surfaceCancelDenyWarn} 同语义。
+ */
+export declare function surfaceRememberNotApplied(): void;
+/**
+ * 「编辑并批准」带了 `updatedInput`,而 ack 回报 `updatedInputForwarded:false`(server 1.241 起
+ * 诚实回显)—— 引擎拿到的是**原始**入参。
+ *
+ * 🔴 这一条比 remember 那条严重一个量级,它是本批 codex 复审判的 [high]:用户在卡上把
+ * `rm -rf /tmp/x` 改成 `rm -rf /tmp/x/build` 然后按了批准,而真正执行的是他改之前那条。
+ * **事后没有 fail-closed 的余地**(allow 已经送达,工具已经在跑),所以唯一诚实的处置就是立刻
+ * 响亮地说出来 —— 静默(此前只写 debug 日志)等于让用户以为自己的编辑生效了。
+ * 上游的正位是让 server 在「带了 updatedInput 却转发不了」时 fail-closed 拒批;那属跨仓,
+ * 已记进 docs/refactor/README.md 的宿主/上游工单表,本层不做旁路补偿(只做如实告知)。
+ */
+export declare function surfaceEditNotForwarded(): void;
 /**
  * 中断 deny 的有界观察(壳侧单测 `hitlCancelDeny.test.ts` 的被测面;REF-CC-023 起两条决断腿共用)。
  * 铁律:不 await 进 abort 返回路径(用户立即拿回控制);这里只管后台 settle 的«观察»: