@sema-agent/client-core 0.41.0 → 0.42.0

package/dist/hitl/editedRuleTextPrecheck.d.ts

@@ -0,0 +1,102 @@
+/**
+ * editedRuleTextPrecheck.ts — 编辑臂的「边打字边校验」判官**转出口**(#225 / [5076] 自领件,0.42.0)。
+ *
+ * ## 这一格要解决的问题
+ * 卡上的规则编辑框想在人还在打字的时候就说「这条能不能提交」。唯一合法的判官是引擎自己那只 ——
+ * core 5.57.0 导出的纯函数 `precheckEditedRuleText(text, command)`,它与 `confirmRuleApproval` 的
+ * fresh-edit 臂**跑同一个函数体**(`checkEditedRuleText`),所以预检面与真裁判**结构性不可分歧**。
+ * 在边界上复读一遍 `parseAllowRuleText` 是**装第二个更严的判官**:`Bash(adb *)` 这类肌肉记忆形
+ * 会被它当场误杀,而编辑面本来先跑拼写归一(`normalizeEditedSpelling`)再接受
+ * ——[5071] 定界②的原话,core [5075] 复核确认。
+ *
+ * ## 🔴 为什么是**端口注入**而不是 `export { precheckEditedRuleText } from '@sema-agent/core'`
+ * [5076] 的自领件原话是「re-export + 类型面」。**逐字照做在本包里是不可能的**,而且不是口味问题,
+ * 是本仓门族的硬约束(0.42.0 施工时实测,证据两条):
+ *   · `scripts/run-client-core-portability-test.mjs` 的 `EXPECTED_PACKAGES_INDEX` 是**等值门**
+ *     ——包总入口闭包的外部包集合恒等于 `{diff, @sema-agent/sdk}`,多一个当场红;
+ *   · 同门 ③ 段拿 esbuild `--platform=browser` **真打一次包**。`@sema-agent/core` 的 barrel 值级
+ *     拉进 `node:crypto`(`engine/session/log-digest.js`)、`node:fs`/`node:path`
+ *     (`core/skills-directory.js`)…… 浏览器腿当场打不成。
+ * ⇒ 一个 value 级 re-export 会把**整台引擎**焊进每一个装 client-core 的端(web/desktop 首当其冲),
+ *   换来一只纯函数。本包的存在理由正是「三端共用的**客户端**运行时」,这条边不能连。
+ *
+ * 于是转出口取**同等效力的第二形**:
+ *   ① **类型面**逐形转出({@link EditedRuleTextPrecheck} / {@link EditedRuleTextPrechecker}),
+ *      三端从此对着同一份形写代码,谁都不用自己抄一份返回型;
+ *   ② **注入口**({@link installEditedRuleTextPrechecker}):Node 宿主(TUI / desktop 主进程 /
+ *      server 侧渲染)在启动时把 core 那只函数原样装进来 —— **原样装,不许包一层判断**;
+ *   ③ **读口**({@link precheckEditedRuleText}):没装 ⇒ 返 `undefined`(**诚实缺席**),
+ *      绝不返一个编出来的 `{ok:true}`。缺席时呈现面的正解是退「提交后才知道」的往返形
+ *      ——[5076] 施工要点③ 已经把这两段写成互不阻塞的两腿。
+ * 🔴 浏览器 lane(web)结构上装不了这只函数(引擎不在那一侧),它**本就该**留缺席走往返形;
+ *   本口的缺席语义因此不是「宿主忘了装」的同义词,别拿它去判部署形态。
+ *
+ * ## 🔴 两点语义预披露(core [5075],消费侧写文案前必读;[5076] 已落账为 #225 施工要点)
+ *   · `ok` = **可提交**,不是「confirm 必成」。记录级闸(binding 回声 / 记录 owner 与 state /
+ *     scope 继承 / 部署开关)**不在**预检覆盖面,由 `confirmRuleApproval` 对着记录重判。
+ *     ⇒ UI 文案只许写「可提交」,**绝不**写「将被批准」。
+ *   · `canonicalRule` 可能与输入**字节不同**(拼写归一)。它是真正会落库的那一形,所以内联反馈
+ *     应当显示 **canonical 形**,而不是把人的输入原样回显。
+ *
+ * ## 调用面契约(core 逐字,注入口不许替它软化)
+ *   · `text` 是**人**的输入 ⇒ 任何畸形拼写都是一个**答案**(refusal),永不抛;
+ *   · `command` 是**调用方**的上下文(卡所依据的被裁决命令)⇒ 缺席/非串是**调用方 bug**,
+ *     core 响亮抛(`config.invalid_argument`)。本包的读口**不吞这个抛**(见 {@link precheckEditedRuleText}
+ *     的 `@throws`):把它折成一个 refusal 会让人读到「你的规则不接受空命令」——把调用方的错
+ *     误归到人头上,正是 core 那段头注点名要避免的事。
+ *   · 卡上**压根没有被裁决命令**(老记录 / 店丢了这一列)⇒ 那是**记录级**拒绝,不该问本函数;
+ *     宿主此时的正解是**根本不给编辑框**。
+ */
+/**
+ * `text × command` 三步门(拼写归一 → 语法门 → coverage 闸)的判决 —— core 5.57.0
+ * `EditedRuleTextPrecheck` 的**逐形镜像**(结构等价,故 core 那只函数可直接装进
+ * {@link EditedRuleTextPrechecker} 而无需任何适配)。
+ *
+ * 🔴 `code` 的**在场规则**与提交面的 `edit_rejected.detail` 同源:验证器自己拒时**在场**,
+ *    coverage 闸拒时**缺席** —— 同一具函数体出来的同一批值。缺席不许被读成「没有理由」。
+ * 🔴 `code` 是**开集串**:core 的 `RuleRejectCode` 词表属主是引擎,本包**刻意不镜像那张枚举**
+ *    (镜像 = 引擎加员当天把一个合法值判没,#157 词表纪律的反面)。要分支就按串比,未知值原样呈现。
+ */
+export type EditedRuleTextPrecheck = {
+    ok: true;
+    /** 真正会落库的那一形(可能与输入字节不同 —— 拼写归一)。内联反馈显示**这一形**。 */
+    canonicalRule: string;
+} | {
+    ok: false;
+    /** 验证器自己拒时在场;coverage 闸拒时缺席(开集串,见类型注)。 */
+    code?: string;
+    /** 拒绝措辞(与 `edit_rejected.detail` 同词汇)。原样呈现,包边界零加工。 */
+    message: string;
+};
+/**
+ * 判官的形:`(text, command) => 判决`。**唯一合法的实参** = core 5.57.0 导出的
+ * `precheckEditedRuleText`,原样装,不许在外面包一层自己的判断
+ * ——包一层就是把「同一函数体」这条唯一的抗漂移保证亲手拆掉。
+ */
+export type EditedRuleTextPrechecker = (text: string, command: string) => EditedRuleTextPrecheck;
+/**
+ * 装/卸判官。返回**还原函数**(装口族统一姿势:还原到装之前那一只,不是无脑清空 —— 嵌套装载
+ * 时无脑清空会把外层那只一起抹掉)。
+ *
+ * Node 宿主的装法(**逐字**,别加工):
+ * ```ts
+ * import { precheckEditedRuleText } from '@sema-agent/core'
+ * installEditedRuleTextPrechecker(precheckEditedRuleText)
+ * ```
+ */
+export declare function installEditedRuleTextPrechecker(fn: EditedRuleTextPrechecker | null): () => void;
+/**
+ * 装没装(存在性读口哨兵:`boolean` 形 —— 见 `docs/INTEGRATION-CLIENTS.md` §5a 的三形分野)。
+ * 呈现面据它决定**给不给编辑框的内联反馈**;`false` 时编辑框本身仍然可用(走往返形)。
+ */
+export declare function hasEditedRuleTextPrechecker(): boolean;
+/**
+ * 预检一段编辑过的规则文本。**没装判官 ⇒ 返 `undefined`**(诚实缺席,不是 `{ok:true}`
+ * 也不是 `{ok:false}` —— 两者都是在替一只不在场的判官发言)。
+ *
+ * @throws core 判官对**调用方 bug**(`command` 缺席/非串/不可渲染)的响亮拒**原样上抛**
+ *         ——本包不吞它:吞掉会让一个调用方错误变成一句对人的判决(见模块头注「调用面契约」)。
+ */
+export declare function precheckEditedRuleText(text: string, command: string): EditedRuleTextPrecheck | undefined;
+/** 测试钩:卸口。 */
+export declare function _resetEditedRuleTextPrecheckerForTest(): void;

package/dist/hitl/editedRuleTextPrecheck.js

@@ -0,0 +1,91 @@
+/**
+ * editedRuleTextPrecheck.ts — 编辑臂的「边打字边校验」判官**转出口**(#225 / [5076] 自领件,0.42.0)。
+ *
+ * ## 这一格要解决的问题
+ * 卡上的规则编辑框想在人还在打字的时候就说「这条能不能提交」。唯一合法的判官是引擎自己那只 ——
+ * core 5.57.0 导出的纯函数 `precheckEditedRuleText(text, command)`,它与 `confirmRuleApproval` 的
+ * fresh-edit 臂**跑同一个函数体**(`checkEditedRuleText`),所以预检面与真裁判**结构性不可分歧**。
+ * 在边界上复读一遍 `parseAllowRuleText` 是**装第二个更严的判官**:`Bash(adb *)` 这类肌肉记忆形
+ * 会被它当场误杀,而编辑面本来先跑拼写归一(`normalizeEditedSpelling`)再接受
+ * ——[5071] 定界②的原话,core [5075] 复核确认。
+ *
+ * ## 🔴 为什么是**端口注入**而不是 `export { precheckEditedRuleText } from '@sema-agent/core'`
+ * [5076] 的自领件原话是「re-export + 类型面」。**逐字照做在本包里是不可能的**,而且不是口味问题,
+ * 是本仓门族的硬约束(0.42.0 施工时实测,证据两条):
+ *   · `scripts/run-client-core-portability-test.mjs` 的 `EXPECTED_PACKAGES_INDEX` 是**等值门**
+ *     ——包总入口闭包的外部包集合恒等于 `{diff, @sema-agent/sdk}`,多一个当场红;
+ *   · 同门 ③ 段拿 esbuild `--platform=browser` **真打一次包**。`@sema-agent/core` 的 barrel 值级
+ *     拉进 `node:crypto`(`engine/session/log-digest.js`)、`node:fs`/`node:path`
+ *     (`core/skills-directory.js`)…… 浏览器腿当场打不成。
+ * ⇒ 一个 value 级 re-export 会把**整台引擎**焊进每一个装 client-core 的端(web/desktop 首当其冲),
+ *   换来一只纯函数。本包的存在理由正是「三端共用的**客户端**运行时」,这条边不能连。
+ *
+ * 于是转出口取**同等效力的第二形**:
+ *   ① **类型面**逐形转出({@link EditedRuleTextPrecheck} / {@link EditedRuleTextPrechecker}),
+ *      三端从此对着同一份形写代码,谁都不用自己抄一份返回型;
+ *   ② **注入口**({@link installEditedRuleTextPrechecker}):Node 宿主(TUI / desktop 主进程 /
+ *      server 侧渲染)在启动时把 core 那只函数原样装进来 —— **原样装,不许包一层判断**;
+ *   ③ **读口**({@link precheckEditedRuleText}):没装 ⇒ 返 `undefined`(**诚实缺席**),
+ *      绝不返一个编出来的 `{ok:true}`。缺席时呈现面的正解是退「提交后才知道」的往返形
+ *      ——[5076] 施工要点③ 已经把这两段写成互不阻塞的两腿。
+ * 🔴 浏览器 lane(web)结构上装不了这只函数(引擎不在那一侧),它**本就该**留缺席走往返形;
+ *   本口的缺席语义因此不是「宿主忘了装」的同义词,别拿它去判部署形态。
+ *
+ * ## 🔴 两点语义预披露(core [5075],消费侧写文案前必读;[5076] 已落账为 #225 施工要点)
+ *   · `ok` = **可提交**,不是「confirm 必成」。记录级闸(binding 回声 / 记录 owner 与 state /
+ *     scope 继承 / 部署开关)**不在**预检覆盖面,由 `confirmRuleApproval` 对着记录重判。
+ *     ⇒ UI 文案只许写「可提交」,**绝不**写「将被批准」。
+ *   · `canonicalRule` 可能与输入**字节不同**(拼写归一)。它是真正会落库的那一形,所以内联反馈
+ *     应当显示 **canonical 形**,而不是把人的输入原样回显。
+ *
+ * ## 调用面契约(core 逐字,注入口不许替它软化)
+ *   · `text` 是**人**的输入 ⇒ 任何畸形拼写都是一个**答案**(refusal),永不抛;
+ *   · `command` 是**调用方**的上下文(卡所依据的被裁决命令)⇒ 缺席/非串是**调用方 bug**,
+ *     core 响亮抛(`config.invalid_argument`)。本包的读口**不吞这个抛**(见 {@link precheckEditedRuleText}
+ *     的 `@throws`):把它折成一个 refusal 会让人读到「你的规则不接受空命令」——把调用方的错
+ *     误归到人头上,正是 core 那段头注点名要避免的事。
+ *   · 卡上**压根没有被裁决命令**(老记录 / 店丢了这一列)⇒ 那是**记录级**拒绝,不该问本函数;
+ *     宿主此时的正解是**根本不给编辑框**。
+ */
+let installed = null;
+/**
+ * 装/卸判官。返回**还原函数**(装口族统一姿势:还原到装之前那一只,不是无脑清空 —— 嵌套装载
+ * 时无脑清空会把外层那只一起抹掉)。
+ *
+ * Node 宿主的装法(**逐字**,别加工):
+ * ```ts
+ * import { precheckEditedRuleText } from '@sema-agent/core'
+ * installEditedRuleTextPrechecker(precheckEditedRuleText)
+ * ```
+ */
+export function installEditedRuleTextPrechecker(fn) {
+    const prev = installed;
+    installed = fn;
+    return () => {
+        installed = prev;
+    };
+}
+/**
+ * 装没装(存在性读口哨兵:`boolean` 形 —— 见 `docs/INTEGRATION-CLIENTS.md` §5a 的三形分野)。
+ * 呈现面据它决定**给不给编辑框的内联反馈**;`false` 时编辑框本身仍然可用(走往返形)。
+ */
+export function hasEditedRuleTextPrechecker() {
+    return installed !== null;
+}
+/**
+ * 预检一段编辑过的规则文本。**没装判官 ⇒ 返 `undefined`**(诚实缺席,不是 `{ok:true}`
+ * 也不是 `{ok:false}` —— 两者都是在替一只不在场的判官发言)。
+ *
+ * @throws core 判官对**调用方 bug**(`command` 缺席/非串/不可渲染)的响亮拒**原样上抛**
+ *         ——本包不吞它:吞掉会让一个调用方错误变成一句对人的判决(见模块头注「调用面契约」)。
+ */
+export function precheckEditedRuleText(text, command) {
+    const fn = installed;
+    if (fn === null)
+        return undefined;
+    return fn(text, command);
+}
+/** 测试钩:卸口。 */
+export function _resetEditedRuleTextPrecheckerForTest() {
+    installed = null;
+}

package/dist/hitl/hitlBridge.d.ts

@@ -308,9 +308,23 @@ export declare class HitlBridge {
      *
      *  - `approve` → `{decision:"approve", boundCallId, boundInputHash}`; `updatedInput` rides along for
      *    approve-with-edit (applied AFTER the binding check — the hash still binds the ORIGINAL input).
-     *  - `deny`    → `{decision:"deny", reason}`. CANCEL a suspended run by DENYING, never by `runs.cancel`
-     *    (which 409s on a suspended run — contract/04 §2.4); the deny-and-abort `interrupt:true` EFFECT is
-     *    "the run ends after the deny", carried by the backend, not a wire flag.
+     *  - `deny`    → `{decision:"deny", reason}`.
+     *
+     * 🔴 **§2.4「DENY-abort」撤稿(0.42.0;server [4833] 明请,契约成文 `4631a0f` 随 7.39 出)**。
+     *    本段原文写的是:「CANCEL a suspended run by DENYING, never by `runs.cancel` (**which 409s on a
+     *    suspended run** — contract/04 §2.4); the deny-and-abort `interrupt:true` EFFECT is *the run ends
+     *    after the deny*」。**三句话里有两句已被上游证伪,逐条**:
+     *      · **「deny 用来 cancel 一条 run」** —— `ASSISTANT-WIRE-CONTRACT.md` §4a 逐字反过来说:
+     *        **DENY is a TOOL-level answer, NEVER a run kill**;客户端不得把用户的拒绝译成 cancel。
+     *        两个动词的 wire 判别式是 `cancelled`(真取消)vs `gate.batch_halted`(裸拒的兄弟结算)。
+     *      · **「`runs.cancel` 对 suspended run 回 409」** —— 自 server [868] 起**就地取消**:
+     *        `runs.js` 的 cancel 腿对 SUSPENDED/needs_review 先结算 pending checkpoint(CAS expire)再
+     *        终态化,`cancelSuspended` 有实体,409 只剩 `conflict.approval_settled` 一条
+     *        (本仓 `docs/fresh-scan-client-core-2026-08-08.md` B型-5 已按真字节证伪,当时未跟修注释)。
+     *      · **仍然成立的那一句**:deny 之后 run 是否结束由**后端编排**决定,不是 wire 上的旗标
+     *        (裸拒 ⇒ `gate.batch_halted` + `haltedOnUserRejection`;带留言拒 ⇒ run 续跑)。
+     *    ⇒ 本方法的**行为一字未改**(它本来走的就是 §4a 说的那条 TOOL 级 decide 通路);改的是这段
+     *      引用错权威、并把一条早已失效的 409 断言当理由的散文。
      *
      * The resumed run continues its SAME durable stream. A binding mismatch (409) is re-raised as a
      * `HitlSafetyError('binding_mismatch')` — the caller re-presents, NEVER auto-retries.

package/dist/hitl/hitlBridge.js

@@ -415,9 +415,23 @@ export class HitlBridge {
      *
      *  - `approve` → `{decision:"approve", boundCallId, boundInputHash}`; `updatedInput` rides along for
      *    approve-with-edit (applied AFTER the binding check — the hash still binds the ORIGINAL input).
-     *  - `deny`    → `{decision:"deny", reason}`. CANCEL a suspended run by DENYING, never by `runs.cancel`
-     *    (which 409s on a suspended run — contract/04 §2.4); the deny-and-abort `interrupt:true` EFFECT is
-     *    "the run ends after the deny", carried by the backend, not a wire flag.
+     *  - `deny`    → `{decision:"deny", reason}`.
+     *
+     * 🔴 **§2.4「DENY-abort」撤稿(0.42.0;server [4833] 明请,契约成文 `4631a0f` 随 7.39 出)**。
+     *    本段原文写的是:「CANCEL a suspended run by DENYING, never by `runs.cancel` (**which 409s on a
+     *    suspended run** — contract/04 §2.4); the deny-and-abort `interrupt:true` EFFECT is *the run ends
+     *    after the deny*」。**三句话里有两句已被上游证伪,逐条**:
+     *      · **「deny 用来 cancel 一条 run」** —— `ASSISTANT-WIRE-CONTRACT.md` §4a 逐字反过来说:
+     *        **DENY is a TOOL-level answer, NEVER a run kill**;客户端不得把用户的拒绝译成 cancel。
+     *        两个动词的 wire 判别式是 `cancelled`(真取消)vs `gate.batch_halted`(裸拒的兄弟结算)。
+     *      · **「`runs.cancel` 对 suspended run 回 409」** —— 自 server [868] 起**就地取消**:
+     *        `runs.js` 的 cancel 腿对 SUSPENDED/needs_review 先结算 pending checkpoint(CAS expire)再
+     *        终态化,`cancelSuspended` 有实体,409 只剩 `conflict.approval_settled` 一条
+     *        (本仓 `docs/fresh-scan-client-core-2026-08-08.md` B型-5 已按真字节证伪,当时未跟修注释)。
+     *      · **仍然成立的那一句**:deny 之后 run 是否结束由**后端编排**决定,不是 wire 上的旗标
+     *        (裸拒 ⇒ `gate.batch_halted` + `haltedOnUserRejection`;带留言拒 ⇒ run 续跑)。
+     *    ⇒ 本方法的**行为一字未改**(它本来走的就是 §4a 说的那条 TOOL 级 decide 通路);改的是这段
+     *      引用错权威、并把一条早已失效的 409 断言当理由的散文。
      *
      * The resumed run continues its SAME durable stream. A binding mismatch (409) is re-raised as a
      * `HitlSafetyError('binding_mismatch')` — the caller re-presents, NEVER auto-retries.
@@ -621,7 +635,9 @@ export function makeHitlCanUseTool(bridge, prompt) {
         const decision = forceDecision ??
             (await prompt({ toolName: tool.name, input, toolUseID, gate }));
         if (decision.behavior === 'deny') {
-            // Deny → cancel-by-deny (contract/04 §2.4). The deny message rides `reason`.
+            // Deny → 一次 **TOOL 级**的 deny 应答(server `ASSISTANT-WIRE-CONTRACT.md` §4a;0.42.0 撤稿:
+            // 原文写的是「cancel-by-deny (contract/04 §2.4)」,而 §4a 逐字反对把拒绝读成 run kill ——
+            // 详见 `decideTool` 头注的撤稿段)。The deny message rides `reason`.
             // 0.28.0 发版扫描 F1(P2):message 逐字嵌原始命令(壳侧 bashPermissions 无上限)——必须与
             // 卡腿同门经窄化器截到 4096,否则 server 413 丢的是整次 deny(run 留 suspended)。
             await bridge.decideTool({ decision: 'deny', reason: denyReasonForWire(decision.message, `canUseTool ${toolUseID}`) ?? DEFAULT_DENY_REASON }, toolUseID);

package/dist/hitl/hitlHostSurface.d.ts

@@ -31,9 +31,32 @@ export declare function _resetHitlHostSurfaceForTest(): void;
 /** 内部读点(计 miss)。`askGateWire.ts` 的 `surfaceClassifierDeny` 路径与本文件的
  *  `surfaceCancelDenyWarn` 共用它。 */
 export declare function surfaceForCurrentSession(): HitlHostSurface | null;
-/** cancel-by-deny 的后台 settle 预算。decide 是 SYNC 驱动的(引擎跑到下一 park/终态才返,实测
- *  4-5s+),但 DENY-abort 语义上引擎收到即终结 run;2s 内连收都没收到 ⇒ 按丢失警示(晚到成功
- *  只是多一行良性 warn,比锁死无线索诚实)。 */
+/**
+ * 中断-deny 的后台 settle 观察预算。
+ *
+ * ══ 🔴 §2.4「DENY-abort」撤稿 + 本常量的论证前提重审(0.42.0;server [4833] 明请)═══════════
+ *
+ * **本段 0.28.0 原文写的是**:「decide 是 SYNC 驱动的(引擎跑到下一 park/终态才返,实测 4-5s+),
+ * 但 **DENY-abort 语义上引擎收到即终结 run**;2s 内连收都没收到 ⇒ 按丢失警示」。
+ * 那句加粗的前提**已被上游撤稿**,来源是 server 自己的契约成文(`4631a0f`,随 7.39 出;
+ * `ASSISTANT-WIRE-CONTRACT.md` §4a):**DENY 是 TOOL 级的应答,永远不是 run kill**;客户端不得
+ * 把「拒绝」译成「取消」;两个动词的 wire 判别式是 `cancelled` vs `gate.batch_halted`。
+ * ⇒ 「引擎收到 deny 即终结 run」这条**不成立**:deny 只结算**这一只 ask**,run 按自己的编排继续
+ *   (裸拒 ⇒ `gate.batch_halted` 兄弟 coded 结算 + `haltedOnUserRejection`;带留言拒 ⇒ run 续跑)。
+ *
+ * **重审结论(本批只改论证,不改数值 —— 理由写全)**:
+ *   · 旧论证「2s 没结算 = deny 大概率丢了,因为收到就该终结」**作废**;
+ *   · 但本常量守的那件事**换一个理由仍然成立**:它是一个**观察上限**,给「decide 永不返回」这种
+ *     形态一条出声的路 —— 没有它,一次真的丢失就只剩静默;
+ *   · **数值不在本批动**:动它是行为面改动,而判据(多久算「没回来」)只有拿真实 decide 往返分布
+ *     说了算,那份实测在**消费端**(壳中断路径)而不在包里;且下游 `sema-cli` 的
+ *     `src/sema/hitlCancelDeny.test.ts` 按现值锁着行为,单边改会当场把消费端打红。
+ *   · **如实登记的残余**(接入档 §6e/§7 同批记):预算到点就发的那行 warn 措辞是
+ *     {@link CANCEL_DENY_WARN_TEXT}（「the session may stay locked」),而在新契约下「decide 慢」
+ *     与「deny 丢了」这两件事在 2s 这个刻度上**不可分** —— 晚到的成功不会撤回那行 warn(只有 10s
+ *     自清)。要根治得做成两档(软档只记 debug、硬档才上屏),那是**跨仓一批**:包侧改时序、壳侧
+ *     同批换判据与用例。本批不做单边改动。
+ */
 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";
@@ -66,6 +89,13 @@ export declare function surfaceRememberNotApplied(): void;
 export declare function surfaceEditNotForwarded(): void;
 /**
  * 中断 deny 的有界观察(壳侧单测 `hitlCancelDeny.test.ts` 的被测面;REF-CC-023 起两条决断腿共用)。
+ *
+ * 🔴 **命名撤稿(0.42.0)**:函数名与日志里的「cancel-by-deny」是**历史词**,保留只为不打断下游
+ * 按名锚的用例。它描述的动作在现行契约(server `ASSISTANT-WIRE-CONTRACT.md` §4a)下的准确说法是
+ * 「**中断时把这只挂着的 ask 用一个 TOOL 级 deny 结算掉**,好让 run 不停在 suspended 上」——
+ * **不是**「用 deny 去 cancel 一条 run」。方向也别读反:这里是把**用户的中断**结算成一次 deny,
+ * 而 §4a 禁的是反向的那件事(把**用户的拒绝**译成 cancel),两者不是同一件事。
+ *
  * 铁律:不 await 进 abort 返回路径(用户立即拿回控制);这里只管后台 settle 的«观察»:
  *   - 2s 内 settle 成功 ⇒ 零上屏(SEMA_DEBUG 记成功);
  *   - 失败/超时 ⇒ 上屏一行 warn + SEMA_DEBUG 记原因(deny 丢失 = run 卡 suspended,下一条消息

package/dist/hitl/hitlHostSurface.js

@@ -61,9 +61,32 @@ export function surfaceForCurrentSession() {
     return hostSurface;
 }
 // ── 件3(中断事故修复批 G,2026-07-15)—— 中断 deny 的有界观察 ─────────────────────────────────
-/** cancel-by-deny 的后台 settle 预算。decide 是 SYNC 驱动的(引擎跑到下一 park/终态才返,实测
- *  4-5s+),但 DENY-abort 语义上引擎收到即终结 run;2s 内连收都没收到 ⇒ 按丢失警示(晚到成功
- *  只是多一行良性 warn,比锁死无线索诚实)。 */
+/**
+ * 中断-deny 的后台 settle 观察预算。
+ *
+ * ══ 🔴 §2.4「DENY-abort」撤稿 + 本常量的论证前提重审(0.42.0;server [4833] 明请)═══════════
+ *
+ * **本段 0.28.0 原文写的是**:「decide 是 SYNC 驱动的(引擎跑到下一 park/终态才返,实测 4-5s+),
+ * 但 **DENY-abort 语义上引擎收到即终结 run**;2s 内连收都没收到 ⇒ 按丢失警示」。
+ * 那句加粗的前提**已被上游撤稿**,来源是 server 自己的契约成文(`4631a0f`,随 7.39 出;
+ * `ASSISTANT-WIRE-CONTRACT.md` §4a):**DENY 是 TOOL 级的应答,永远不是 run kill**;客户端不得
+ * 把「拒绝」译成「取消」;两个动词的 wire 判别式是 `cancelled` vs `gate.batch_halted`。
+ * ⇒ 「引擎收到 deny 即终结 run」这条**不成立**:deny 只结算**这一只 ask**,run 按自己的编排继续
+ *   (裸拒 ⇒ `gate.batch_halted` 兄弟 coded 结算 + `haltedOnUserRejection`;带留言拒 ⇒ run 续跑)。
+ *
+ * **重审结论(本批只改论证,不改数值 —— 理由写全)**:
+ *   · 旧论证「2s 没结算 = deny 大概率丢了,因为收到就该终结」**作废**;
+ *   · 但本常量守的那件事**换一个理由仍然成立**:它是一个**观察上限**,给「decide 永不返回」这种
+ *     形态一条出声的路 —— 没有它,一次真的丢失就只剩静默;
+ *   · **数值不在本批动**:动它是行为面改动,而判据(多久算「没回来」)只有拿真实 decide 往返分布
+ *     说了算,那份实测在**消费端**(壳中断路径)而不在包里;且下游 `sema-cli` 的
+ *     `src/sema/hitlCancelDeny.test.ts` 按现值锁着行为,单边改会当场把消费端打红。
+ *   · **如实登记的残余**(接入档 §6e/§7 同批记):预算到点就发的那行 warn 措辞是
+ *     {@link CANCEL_DENY_WARN_TEXT}（「the session may stay locked」),而在新契约下「decide 慢」
+ *     与「deny 丢了」这两件事在 2s 这个刻度上**不可分** —— 晚到的成功不会撤回那行 warn(只有 10s
+ *     自清)。要根治得做成两档(软档只记 debug、硬档才上屏),那是**跨仓一批**:包侧改时序、壳侧
+ *     同批换判据与用例。本批不做单边改动。
+ */
 export const CANCEL_DENY_BUDGET_MS = 2000;
 /** warn 行文案(测试锁字面)。 */
 export const CANCEL_DENY_WARN_TEXT = 'could not cancel the pending question — the session may stay locked; the run may need engine-side recovery';
@@ -161,6 +184,13 @@ function isNoPendingError(e) {
 }
 /**
  * 中断 deny 的有界观察(壳侧单测 `hitlCancelDeny.test.ts` 的被测面;REF-CC-023 起两条决断腿共用)。
+ *
+ * 🔴 **命名撤稿(0.42.0)**:函数名与日志里的「cancel-by-deny」是**历史词**,保留只为不打断下游
+ * 按名锚的用例。它描述的动作在现行契约(server `ASSISTANT-WIRE-CONTRACT.md` §4a)下的准确说法是
+ * 「**中断时把这只挂着的 ask 用一个 TOOL 级 deny 结算掉**,好让 run 不停在 suspended 上」——
+ * **不是**「用 deny 去 cancel 一条 run」。方向也别读反:这里是把**用户的中断**结算成一次 deny,
+ * 而 §4a 禁的是反向的那件事(把**用户的拒绝**译成 cancel),两者不是同一件事。
+ *
  * 铁律:不 await 进 abort 返回路径(用户立即拿回控制);这里只管后台 settle 的«观察»:
  *   - 2s 内 settle 成功 ⇒ 零上屏(SEMA_DEBUG 记成功);
  *   - 失败/超时 ⇒ 上屏一行 warn + SEMA_DEBUG 记原因(deny 丢失 = run 卡 suspended,下一条消息

package/dist/hitl/parkResolver.js

@@ -154,12 +154,24 @@ parkGatedCallId) {
     });
     const bridge = new HitlBridge(deps.client, taskId);
     if (answer === null) {
-        // turn 被中断(Esc/Ctrl+C):cancel-by-deny(contract/04 §2.4 —— suspended run 不 runs.cancel)。
+        // turn 被中断(Esc/Ctrl+C):把这只挂着的 ask 用一次 **TOOL 级 deny** 结算掉,好让 run 不停在
+        // suspended 上(server `ASSISTANT-WIRE-CONTRACT.md` §4a)。
+        // 🔴 **0.42.0 撤稿**:原文写的是「cancel-by-deny(contract/04 §2.4 —— suspended run 不
+        //    runs.cancel)」。那条引用的两个前提都已作废 —— §4a 逐字说 DENY 是 tool 级应答**永远不是**
+        //    run kill;而「suspended run 不能 runs.cancel」自 server [868] 起就不成立(就地取消已实装,
+        //    本仓 fresh-scan B型-5 按真字节证伪)。这里选 deny 不是因为 cancel 不可用,是因为**这一刻
+        //    要处理的就是一只挂着的 ask**:先把它结算掉,run 才走得下去。下方那句「引擎侧解锁腿到货前」
+        //    同批订正:那条腿早就到货了,本臂保留的理由变成「结算 ask 是这一步的正解」,不再是权宜。
         // 件3(中断事故修复批 G,2026-07-15,症状1 壳侧配套):此前 .catch(()=>{}) 全吞 = deny 丢失时
         // run 永卡 suspended,session 锁死,用户下一条消息撞 409「active run」还全无线索。改为有界观察
         // (observeCancelByDeny,2s 预算):abort 仍立即返回用户控制(不 await,交互时序不变),后台
-        // settle 失败/超时上屏一行 warn + SEMA_DEBUG 记失败原因。引擎侧解锁腿([866] server:cancel
-        // suspended 改语义 + reapSuspended TTL)到货前,这是壳能做的最诚实半场。
+        // settle 失败/超时上屏一行 warn + SEMA_DEBUG 记失败原因。
+        // 🔴 **0.42.0 订正**:本段原文以「引擎侧解锁腿([866] server:cancel suspended 改语义 +
+        //    reapSuspended TTL)**到货前**,这是壳能做的最诚实半场」收尾 —— 那条腿早已到货
+        //    (server [868] 起 suspended run 就地取消 + `reapSuspended` 实体在,fresh-scan B型-5 已按
+        //    真字节证伪)。本臂**不是**在等一条不存在的上游腿:它保留的理由是「这一刻要处理的就是一只
+        //    挂着的 ask,先结算它 run 才走得下去」。观察器的预算论证前提见 `CANCEL_DENY_BUDGET_MS` 头注
+        //    的重审段(同批 §2.4 撤稿件)。
         observeCancelByDeny(bridge.decideTool({ decision: 'deny', reason: 'Interrupted by user' }, gatedCallId, undefined, pending), taskId);
         return { kind: 'aborted', gatedCallId };
     }

package/dist/hitl/toolApprovalWire.d.ts

@@ -130,8 +130,27 @@ export interface ApprovalCardAllowDecision {
     allowSession: boolean;
     updatedInput?: unknown;
     /** #225 件1:卡上选中的持久规则候选**原文**({@link ApprovalCardRequest.ruleSuggestions} 之一);
-     *  缺席/空串 = 本次不兑付。表外文本会在编排层被丢键留痕(server 亦拒 rule_not_offered)。 */
+     *  缺席/空串 = 本次不兑付。表外文本会在编排层被丢键留痕(server 亦拒 rule_not_offered)。
+     *  ⚠️ 0.42.0 起本位有一个**兄弟位** {@link persistRuleEdited} —— 带上它就是「这段文本是人手改的
+     *  自由文本」,此时本位**不再**要求是候选之一(见该位注)。本位自身的类型与字节一字未动。 */
     persistRule?: string;
+    /**
+     * #225 编辑臂(0.42.0;server #340 `respondFreeFormRules`,[5071] wire 形):{@link persistRule}
+     * 里那段文本是**人在卡上手打/改过的自由文本**,不是帧候选表里的原文。
+     *
+     * 🔴 **缺席 ≠ false**:缺席 = 既有候选臂(表内核对照旧、语义与 0.41.0 逐字节相同);
+     *    `true` = 编辑臂。刻意只收 `true` 一个值(机读位是二值的,「在场但不是 true」没有语义)。
+     * 🔴 **它不是放行凭据**,是**出身声明**:带上它只会让编排层放弃「必须是候选之一」那道表核
+     *    (见 {@link surfaceToolApprovalFrameAndRespond} 的兑付段),真正的判官仍在引擎侧
+     *    (core `confirmRuleApproval` 同函数体)。客户端**绝不**在这里替引擎预判文本合不合法 ——
+     *    在边界复读解析器就是装第二个更严的判官,`Bash(adb *)` 这类肌肉记忆形会被当场误杀
+     *    ([5071] 定界②,core [5075] 复核确认)。要「边打字边校验」请用
+     *    {@link import('./editedRuleTextPrecheck.js').precheckEditedRuleText} 的注入口 —— 那是**引擎
+     *    自己那只**判官,不是第二份。
+     * 🔴 **能力位在场才发**:`true` 而 {@link ToolApprovalFrameLaneOpts.respondFreeFormRulesCapable}
+     *    未确认 ⇒ 编排层**整条丢 persistRule**(决断照送),见该位注。
+     */
+    persistRuleEdited?: true;
 }
 /**
  * deny 决断臂(命名形,typeshape B4 口径;0.28.0 因 `reason` 位抽名,与 0.26.0
@@ -598,8 +617,22 @@ export type ToolApprovalRespondDecision = 'allow' | 'allow_session' | 'deny';
 export interface RespondToolApprovalOpts {
     signal?: AbortSignal;
     updatedInput?: unknown;
-    /** #225 件1:兑付键 —— 帧候选之一的**原文**(编排层已做表内核对与 deny 剥除)。 */
+    /** #225 件1:兑付键 —— 帧候选之一的**原文**(编排层已做表内核对与 deny 剥除)。
+     *  ⚠️ 带 {@link persistRuleEdited} 时表核已让位,本位是人手改的自由文本(类型不变)。 */
     persistRule?: string;
+    /**
+     * #225 编辑臂(0.42.0;server #340,[5071]):{@link persistRule} 是**自由文本**而非候选原文。
+     *
+     * 🔴 **注入面的映射义务**(本包只到这一格,wire 体由宿主/SDK 铸):server 的 respond 体形是
+     *    `persistRule: { rule, edited: true }`。本包刻意保持**扁平兄弟位**(`persistRule: string`
+     *    字节不变 + 一个可选布尔),由注入面把两位合成那个嵌套形:
+     *      `persistRule !== undefined ? { rule: persistRule, ...(persistRuleEdited === true ? { edited: true } : {}) } : undefined`
+     *    改成嵌套形会是既有 `persistRule: string` 消费者的 BREAKING,而这一批的纲领是 additive。
+     * 🔴 **缺席 = 候选臂**(server 侧 `rule_not_offered` 语义一字不变);老 server 收到带 `edited`
+     *    的体会诚实降级为 `rule_not_offered`,这正是 [5071] 选这个键名而不是顶层新键的理由
+     *    (顶层新键在老 server 上是静默 200 什么都不落,坏于诚实降级)。
+     */
+    persistRuleEdited?: true;
     /** #229(server ≥7.15.0):回决备注 —— 与 durable 腿 `AskDecisionBody.note` **同词同源同一列**
      *  (`decision_note`,≤2048)。任何 decision 都可带(deny 的「为什么拒」正是审计面上最值钱的
      *  一条);真落行与否看 ack 的 {@link surfaceToolApprovalFrameAndRespond} 消费的 `noteRecorded`。
@@ -629,7 +662,79 @@ export interface ToolApprovalFrameOutcome {
     decision: ToolApprovalRespondDecision | 'unresolved';
     /** server 的 200 ack。**缺席 = 未知**(注入面回 void / 旧 server / respond 失败),绝不当成 false。 */
     ack?: ToolApprovalRespondAck;
+    /**
+     * #225 件5(0.42.0):respond **抛错**那一支的原文交还位。
+     *
+     * 🔴 修的是一条真断链:此前本函数的 catch 只写一行 `debug` 然后返 `{decision:'unresolved'}`,
+     *    于是 server 的响亮 400(`persistRule.rule` 空/超长、`edited` 非布尔、顶层 `scope`、
+     *    `edit-rejected` 的拒句 …… [5071] G4/G5/G6)在**包边界上被吞掉** —— 宿主的错误反馈面
+     *    无论怎么写都拿不到那句话,人在卡上改了规则被拒,屏上什么都不会说。
+     * 🔴 **不改 `decision` 的语义**:`'unresolved'` 仍是 `'unresolved'`(respond 没落定 = 引擎按
+     *    TTL/abort 自决,这一位的含义一字未动);本位是**附加**的诊断面,不是新的决断态。
+     * 🔴 **缺席 = 没有拒绝原文可交**(respond 成功 / 抛的东西上**三位皆读不出**),绝不造一句。
+     *    在场时**三位都可能缺席其二** —— 有 `status` 没文本(应答体为空)、有文本没 `status`
+     *    (传输层失败)都是真实形。
+     */
+    respondRefusal?: ToolApprovalRespondRefusal;
 }
+/**
+ * #225 件5:respond 抛错的**结构化原文**(不是新的决断态,见
+ * {@link ToolApprovalFrameOutcome.respondRefusal})。
+ *
+ * 三位**各自独立**防御读、各自缺席不铸:`status` 只认有限数、`errorCode` 只认非空串、
+ * `message` 只认真读得出来的文本(取值序与 try 保护见 {@link readToolApprovalRespondRefusal})。
+ * 🔴 **三位皆缺席时整只不铸**(异源复审 [medium] 采纳,0.42.0):此前 `message` 是必填、读不出时
+ *    无条件退 `String(err)`,于是 `throw {}` 会得到一句 `"[object Object]"` —— 那不是 server 说的话,
+ *    是本层编的([honest-absence-not-fabricated-zero])。
+ * 🔴 **原样交还,零加工**:不 trim、不截断、不改写、不按识别表过滤。server 的拒句是给人看的
+ *    指路文本([5071] 三条 400 拒句各自成文),包边界任何一次改写都会让宿主呈的不再是引擎说的那句;
+ *    长度夹取与呈现归端(与 `message`/`approver` 同族口径)。
+ * 🔴 **UNTRUSTED-for-display**:它是 HTTP 应答体上的文本,只渲染,绝不回喂模型/工具入参。
+ */
+interface ToolApprovalRespondRefusalFields {
+    /** HTTP 状态(在场 = 引擎真应答了;缺席 = 传输层失败/注入面自抛,不许反推成 0)。 */
+    status?: number;
+    /** 机读码(开集,原样;缺席 = 应答没带码)。 */
+    errorCode?: string;
+    /**
+     * 拒句原文(server 的响亮拒文案)。
+     * 🔴 **缺席 = 这个抛出物上读不出任何可用文本**(异源复审 [medium] 采纳,0.42.0)——
+     *    此前本位是必填、读不出时无条件铸 `String(err)`,于是 `throw {}` 会得到一句
+     *    `"[object Object]"`、`throw null` 得到 `"null"`:那**不是** server 说的话,是本层编的,
+     *    与本形头注承诺的「读不出原文就缺席」直接冲突([honest-absence-not-fabricated-zero])。
+     */
+    message?: string;
+}
+/**
+ * 🔴 **「在场即至少有一位」写进类型**(异源复审 [medium] 采纳,0.42.0):三位全 optional 的
+ * interface 在类型上允许 `{}`,而实现明确承诺「三位皆缺席时整只返 `undefined`」——
+ * 消费端于是既不能依赖「对象在场 = 至少有一条诊断信息」,也没法穷举安全渲染。
+ * 用**三选一联合**把那条运行期不变量抬到编译期:`{}` 从此不可赋值。
+ */
+export type ToolApprovalRespondRefusal = (ToolApprovalRespondRefusalFields & {
+    status: number;
+}) | (ToolApprovalRespondRefusalFields & {
+    errorCode: string;
+}) | (ToolApprovalRespondRefusalFields & {
+    message: string;
+});
+/**
+ * 从 respond 抛出来的东西上读 {@link ToolApprovalRespondRefusal}。**永不抛、永不造**。
+ *
+ * 键位口径与 {@link import('../wireErrorTriage.js').classifyTurnWireError} 同源([2055] 死键
+ * 纪律:只认活键 `errorCode`,退役的 `code` 槽不做兼容)。
+ *
+ * @returns 三位**全缺席**时返回 `undefined` —— 一个三位皆空的 refusal 对象是「有拒句」的假象。
+ *
+ * 🔴 **文本取值序**(异源复审 [medium] 修):`err.message` 非空串 > 抛出物本身是非空串 >
+ *    受保护的 `String(err)`,且**只接受**真有内容的结果 —— `[object Object]` / `null` /
+ *    `undefined` 三种占位串一律当作「读不出」。
+ * 🔴 **`String(err)` 用 try 包住**:抛出物可以自带 `Symbol.toPrimitive` / `toString` 钩子并在里面
+ *    抛错。本函数的唯一调用点在 `surfaceToolApprovalFrameAndRespond` 的 catch 里,那里的契约是
+ *    「respond 失败 ⇒ 返回 unresolved」;让一个不可信的转换钩子把这条收敛路径变成 reject,
+ *    等于给注入面开了一个「让整次审批消费抛出去」的口。
+ */
+export declare function readToolApprovalRespondRefusal(err: unknown): ToolApprovalRespondRefusal | undefined;
 /** 结构性识别流上的 tool_approval 帧(named SSE frame,payload.type === 帧名)。
  *  ⚠️ 口径更正(2026-08-08):此处原写「非 AgentEvent arm」—— SDK #185a 起这两个帧**是**
  *  `AgentEvent` 的臂了(durable 腿也回放),所以结构识别与 union 收窄两条路都成立;本函数仍按
@@ -644,6 +749,16 @@ export interface ToolApprovalFrameLaneOpts {
      * 缺席/false ⇒ 不发(fail-closed 到「不发」侧;决断本身照常送达,现状字节不变)。
      */
     approvalDecisionNoteCapable?: boolean;
+    /**
+     * server 能力位 `capabilities.respondFreeFormRules` 的读数(宿主从自己的 caps 缓存供给;
+     * server ≥7.44,#340 [5071] 恒真版本位)。
+     * 🔴 形与判据**逐字照** {@link approvalDecisionNoteCapable} 既有形(同一条 SDK 6.16 成文纪律:
+     *    **位缺席就别发**)—— 老 server 对未知请求键静默忽略且照回 200,「这台不认识自由文本臂」与
+     *    「记上了」在响应上不可分,发了只造「规则已存」的错觉。
+     * 缺席/false ⇒ 编辑臂的 `persistRule` **整条不发**(fail-closed 到「不发」侧;决断本身照常送达,
+     * 现状字节不变,老引擎零受迫)。候选臂**不受本位影响**(它是 0.25.0 起就有的既有通道)。
+     */
+    respondFreeFormRulesCapable?: boolean;
     /**
      * 这条帧是不是**当下**从 live 流上收到的(异源对抗复审 P1 采纳;壳孪生帧族同名闸的
      * 本包席位 —— 壳 `approvalStreamWire` 头注逐字:「账本重放的历史帧带的是铸帧时刻的旧余量,
@@ -656,3 +771,4 @@ export interface ToolApprovalFrameLaneOpts {
     windowIsCurrent?: boolean;
 }
 export declare function surfaceToolApprovalFrameAndRespond(frame: ToolApprovalFrame, respond: RespondToolApprovalFn, streamArgs: unknown | undefined, signal?: AbortSignal, lane?: ToolApprovalFrameLaneOpts): Promise<ToolApprovalFrameOutcome>;
+export {};