@sema-agent/client-core 0.77.1 → 0.78.0

package/dist/headlessPermissionModeWire.d.ts

@@ -1,89 +1,13 @@
-/**
- * src/sema/headlessPermissionModeWire.ts — SEMA_HEADLESS_PERMISSION_MODE 部署旋钮
- * (clay 拍板 2026-07-16:TB/bench 场景 headless `-p` 统一垫 bypassPermissions,对齐 CC bench 实跑的
- * --dangerously-skip-permissions 姿势;落地形态 = 环境变量部署旋钮,产品缺省语义不动)。
- *
- * gap-check 现状(2026-07-16,db3c72f):
- *   · `--permission-mode <mode>` CLI flag 存在(main.tsx:1042,choices = PERMISSION_MODES + 'manual'),
- *     `--dangerously-skip-permissions` 亦在;但两者在 headless `-p` 车道【都不进 TaskRequest】——
- *     seamQueryEngine.ask 自建请求从不 stamp permissionMode(交互 REPL 走 seamQuery →
- *     permissionWireCaps.permissionModeField,print/headless 从不 stamp = server absent-mode)。
- *   · 即:今天 `-p` 的权限面全靠 server 对 absent-mode 的缺省解释([830]① server 1.191 五模式解释层,
- *     absent 不挂门)。core [885] 残余建议:显式垫,防未来缺省变化让 TB 静默变盘。
- *
- * 语义(件2 拍板逐字):
- *   优先级:CLI flag 显式值 > SEMA_HEADLESS_PERMISSION_MODE env > 现状 absent-mode(env 是缺省态的
- *   垫层,flag 恒赢——flag 在场时 env 完全不看,即使 flag 值不在 wire 词表内)。
- *   值域 = 壳既有 wire permissionMode 词表(permissionWireCaps.PermissionMode:default / plan /
- *   acceptEdits / bypassPermissions / auto——分类器批3 [907] server 五模式表,server ≥1.209 认
- *   "auto")。非法 env 值 ⇒ 一次性 warn + 回落现状,绝不 fail 启动。
- *   stamp 规则([2713] 最小刀改形,2026-08-05;双复审补 dontAsk 归一同日):
- *     · flag 来源:显式表态一律显式 stamp——wire 五词直 stamp,`default` 走 stampDefault 显式垫
- *       (旧形 default 不 stamp ⇒ server 侧 `settings.permissions.defaultMode` 恒缺席 ⇒
- *       `deriveSettingsPolicy` 早退返回 `{}` ⇒ **按模式派生的那套门一个不铸**,print 车道 ask 门
- *       断链根因。⚠️ 本模块只对**这一个量**负责:body 里有没有 `permissionMode`。[2713] 写的
- *       「applyTaskSettings 整跳」是那条链的简写,它成不成立还要看 body.settings 里有没有别的
- *       parsed 字段 —— 那是 server 的控制流,会随 server 改版漂,别在本注释里复述第二遍,要查就去
- *       读 server task-settings.ts);壳内部词(`manual`=CC default 别名、`dontAsk`=壳侧最严
- *       「ask⇒deny」模式)经 SHELL_INTERNAL_MODE_TO_WIRE 归一到 wire 词 `default` 后 stamp
- *       (方向纪律与三条残余记账见该常量 doc);归一表外的值仍不 stamp = 回落部署基线。
- *       ⚠️ 版本界(逐值核过 server CHANGELOG 与 cli scripts/lib/engine-pin.mjs,2026-08-05):
- *       `shellGate` 与 fs 写 ask 门曾同吃这道断链;server #153([2713] 分单②)把
- *       MANUAL_MODE_SHELL_GATE 升到 `applyRuntimeGovernance` 无条件施加,该修**发在 server 7.1.0**,
- *       而当日 `ENGINE_PIN = '7.0.0'` —— **发货引擎上两门仍同断**,本 stamp 两门都决定。等 pin 抬到
- *       ≥7.1.0,shellGate 就与本字段在不在场无关,本 stamp 只再决定 fs 写 ask 门。
- *       别把这段读成「现在只剩 fsWrite」,也别读成「shellGate 永远归我管」——它是随 pin 移动的界。
- *     · env 来源:五词全部显式 stamp(含 `default`——env 是"显式垫层"旋钮,设了就是要显式语义,
- *       不再依赖 server absent-mode 缺省解释;server 1.191 对显式 "default" 走 manual ask 门解释)。
- *   车道纪律:`resolveHeadlessPermissionMode`(本模块的 stamp 决策口)只被 seamQueryEngine.ask
- *   (headless `-p`)调用;交互 REPL(seamQuery)一根毛不动——单测的 lane proof 锚的正是**这个符号
- *   名**,不是模块名。⚠️ 「本模块只被 seamQueryEngine import」是**错的**(旧注释遗留,双复审查出):
- *   `interactiveToolsWire.ts:45` 也 import 本模块的 `permissionModeFromArgv`(REF-CC-dup-10 收编,
- *   两个 headless 旋钮共用同一份 argv 读法)——那是纯 argv 解析器,不碰 stamp 决策,车道纪律不破。
- */
 import { type PermissionMode, type PermissionModeField } from './permissionWireCaps.js';
 import { type EnvLike } from './hostEnv.js';
-/** 部署旋钮 env 键名(settings.json env 块 → 1a-envseed → process.env 同车道)。 */
 export declare const HEADLESS_PERMISSION_MODE_ENV = "SEMA_HEADLESS_PERMISSION_MODE";
 export declare const HEADLESS_PERMISSION_WIRE_MODES: readonly PermissionMode[];
-/**
- * 归一表的**唯一取值口**(#164 [2760]② wire 面三面同拍,2026-08-06):壳内部模式词 → wire 词;
- * 表外词与 undefined 恒等透传(未表态不制造表态)。两个消费方共用同一张表(单表纪律,禁抄写):
- *   · headless flag 支(本模块 resolveHeadlessPermissionMode);
- *   · 壳交互车道(seamQuery 在 permissionModeField stamp 前归一——修前交互车道 `dontAsk` 落
- *     permissionModeField 表外支不 stamp ⇒ 引擎侧 absent-mode 一个门不铸,与底栏「don't ask on」
- *     指示相反;归一后 stamp `default` ⇒ 引擎铸 ask 门,ask 到壳后由壳侧 dontAsk 决策臂
- *     (ask⇒deny)落地,与 CC 单进程语义对位)。
- * 方向纪律与三条残余记账见上方表 doc,本函数不另立口径。
- */
 export declare function normalizeShellPermissionModeForWire(mode: string | undefined): string | undefined;
 export type HeadlessPermissionResolution = {
-    /** 直接展开进 TaskRequest 的字段({} = 不 stamp,现状 absent-mode)。 */
     fields: PermissionModeField;
     source: 'flag' | 'env' | 'default' | 'absent';
-    /** 非法 env 值的告警文案(调用层一次性打 stderr)。 */
     warning?: string;
 };
-/**
- * argv 里的 `--permission-mode <v>` / `--permission-mode=<v>`(后者/后出现者赢,commander 同语义)与
- * `--dangerously-skip-permissions`(= bypassPermissions;`--permission-mode` 在场时让位)。
- * 返回 undefined = flag 车道未显式表态。
- *
- * REF-CC-143(dup-07)收编:`--permission-mode` 的取值改吃共用 lastFlagValue(argvFlagValue.ts,
- * `onMissingValue:'latch-previous'`)——旧手写循环对「某一次 occurrence 缺值」的处置是跳过这一次、
- * 锁存(latch)住之前已经取到的合法值,不是把整个旗塌缩成「从没写过」(`--permission-mode plan
- * --permission-mode` 的旧行为是 `mode==='plan'`,不是 `undefined`)。共用叶的缺省策略
- * (`'invalidate'`,sandboxWire/scenarioWire 用)会把这个情形塌缩成「有旗无值」,与本函数原有语义
- * 不符,所以本调用点显式传 `'latch-previous'` 保住旧行为——这才是任务书说的「各调用方保持自己现有
- * 对缺值的处置」(wave1 回炉修复,blocker:此前误用了共用叶的 invalidate 缺省,详见 commit 记账)。
- * `--dangerously-skip-permissions` 的存在性判别不属于「取某旗最后值」这个不变量,单独一个小循环即
- * 可,零重复。
- */
 export declare function permissionModeFromArgv(argv: readonly string[]): string | undefined;
-/**
- * 解析 headless `-p` 的 permissionMode stamp。纯函数除告警 latch(同值只警一次)。
- * 调用方(seamQueryEngine.ask)live-gated:mock/pty 车道永不经过这里。
- */
 export declare function resolveHeadlessPermissionMode(argv: readonly string[], env?: EnvLike): HeadlessPermissionResolution;
-/** 测试钩子:重置一次性告警 latch。 */
 export declare function _resetHeadlessPermissionModeWireForTest(): void;

package/dist/headlessPermissionModeWire.js

@@ -1,152 +1,20 @@
-/**
- * src/sema/headlessPermissionModeWire.ts — SEMA_HEADLESS_PERMISSION_MODE 部署旋钮
- * (clay 拍板 2026-07-16:TB/bench 场景 headless `-p` 统一垫 bypassPermissions,对齐 CC bench 实跑的
- * --dangerously-skip-permissions 姿势;落地形态 = 环境变量部署旋钮,产品缺省语义不动)。
- *
- * gap-check 现状(2026-07-16,db3c72f):
- *   · `--permission-mode <mode>` CLI flag 存在(main.tsx:1042,choices = PERMISSION_MODES + 'manual'),
- *     `--dangerously-skip-permissions` 亦在;但两者在 headless `-p` 车道【都不进 TaskRequest】——
- *     seamQueryEngine.ask 自建请求从不 stamp permissionMode(交互 REPL 走 seamQuery →
- *     permissionWireCaps.permissionModeField,print/headless 从不 stamp = server absent-mode)。
- *   · 即:今天 `-p` 的权限面全靠 server 对 absent-mode 的缺省解释([830]① server 1.191 五模式解释层,
- *     absent 不挂门)。core [885] 残余建议:显式垫,防未来缺省变化让 TB 静默变盘。
- *
- * 语义(件2 拍板逐字):
- *   优先级:CLI flag 显式值 > SEMA_HEADLESS_PERMISSION_MODE env > 现状 absent-mode(env 是缺省态的
- *   垫层,flag 恒赢——flag 在场时 env 完全不看,即使 flag 值不在 wire 词表内)。
- *   值域 = 壳既有 wire permissionMode 词表(permissionWireCaps.PermissionMode:default / plan /
- *   acceptEdits / bypassPermissions / auto——分类器批3 [907] server 五模式表,server ≥1.209 认
- *   "auto")。非法 env 值 ⇒ 一次性 warn + 回落现状,绝不 fail 启动。
- *   stamp 规则([2713] 最小刀改形,2026-08-05;双复审补 dontAsk 归一同日):
- *     · flag 来源:显式表态一律显式 stamp——wire 五词直 stamp,`default` 走 stampDefault 显式垫
- *       (旧形 default 不 stamp ⇒ server 侧 `settings.permissions.defaultMode` 恒缺席 ⇒
- *       `deriveSettingsPolicy` 早退返回 `{}` ⇒ **按模式派生的那套门一个不铸**,print 车道 ask 门
- *       断链根因。⚠️ 本模块只对**这一个量**负责:body 里有没有 `permissionMode`。[2713] 写的
- *       「applyTaskSettings 整跳」是那条链的简写,它成不成立还要看 body.settings 里有没有别的
- *       parsed 字段 —— 那是 server 的控制流,会随 server 改版漂,别在本注释里复述第二遍,要查就去
- *       读 server task-settings.ts);壳内部词(`manual`=CC default 别名、`dontAsk`=壳侧最严
- *       「ask⇒deny」模式)经 SHELL_INTERNAL_MODE_TO_WIRE 归一到 wire 词 `default` 后 stamp
- *       (方向纪律与三条残余记账见该常量 doc);归一表外的值仍不 stamp = 回落部署基线。
- *       ⚠️ 版本界(逐值核过 server CHANGELOG 与 cli scripts/lib/engine-pin.mjs,2026-08-05):
- *       `shellGate` 与 fs 写 ask 门曾同吃这道断链;server #153([2713] 分单②)把
- *       MANUAL_MODE_SHELL_GATE 升到 `applyRuntimeGovernance` 无条件施加,该修**发在 server 7.1.0**,
- *       而当日 `ENGINE_PIN = '7.0.0'` —— **发货引擎上两门仍同断**,本 stamp 两门都决定。等 pin 抬到
- *       ≥7.1.0,shellGate 就与本字段在不在场无关,本 stamp 只再决定 fs 写 ask 门。
- *       别把这段读成「现在只剩 fsWrite」,也别读成「shellGate 永远归我管」——它是随 pin 移动的界。
- *     · env 来源:五词全部显式 stamp(含 `default`——env 是"显式垫层"旋钮,设了就是要显式语义,
- *       不再依赖 server absent-mode 缺省解释;server 1.191 对显式 "default" 走 manual ask 门解释)。
- *   车道纪律:`resolveHeadlessPermissionMode`(本模块的 stamp 决策口)只被 seamQueryEngine.ask
- *   (headless `-p`)调用;交互 REPL(seamQuery)一根毛不动——单测的 lane proof 锚的正是**这个符号
- *   名**,不是模块名。⚠️ 「本模块只被 seamQueryEngine import」是**错的**(旧注释遗留,双复审查出):
- *   `interactiveToolsWire.ts:45` 也 import 本模块的 `permissionModeFromArgv`(REF-CC-dup-10 收编,
- *   两个 headless 旋钮共用同一份 argv 读法)——那是纯 argv 解析器,不碰 stamp 决策,车道纪律不破。
- */
 import { permissionModeField } from './permissionWireCaps.js';
 import { hostEnv } from './hostEnv.js';
 import { lastFlagValue } from './argvFlagValue.js';
-/** 部署旋钮 env 键名(settings.json env 块 → 1a-envseed → process.env 同车道)。 */
 export const HEADLESS_PERMISSION_MODE_ENV = 'SEMA_HEADLESS_PERMISSION_MODE';
-/** wire 词表(permissionWireCaps.PermissionMode 的运行时镜像;大小写敏感——与 CC flag choices 一致)。
- *  'auto'(分类器批3,[907]):server ≥1.209 五模式表认;老 server coerce 未知词 → "default" 只紧不松。 */
 const HEADLESS_PERMISSION_WIRE_MODE_TUPLE = ['default', 'plan', 'acceptEdits', 'bypassPermissions', 'auto'];
-/**
- * 🔴 [2006] B-CC-2(2026-07-29):`readonly PermissionMode[]` 的注解只保证「元素合法」,**从不保证
- * 穷举** —— server 五模式表加第六个词、`PermissionMode` 跟了而这张运行时镜像没跟 ⇒ 编译期全绿,
- * 而那个词从 env 旋钮走进来会被判非法、一次性 warn 后**静默回落**(部署以为设了、实际没设)。
- * 补「类型 → 常量」那半边;之前的看守只有 `length > 0 && includes('plan')`(对这个方向零判别力)。
- * `Covers`(REF-CC-145/dup-12,P3 wave1 卡C-argv)改吃共用叶 typePins.ts——四份逐字重复钉之一。
- */
 const _headlessPermissionModePins = [true, true];
 void _headlessPermissionModePins;
 export const HEADLESS_PERMISSION_WIRE_MODES = HEADLESS_PERMISSION_WIRE_MODE_TUPLE;
-/**
- * 壳内部模式词 → wire 词的归一表(**壳内映射,勿改 server 五词表**)。大小写敏感,与 commander
- * `--permission-mode` 的 choices 同口径;表外词照原样交给 permissionModeField 双支自处置。
- *
- * · `manual` = CC 2.1.207 对内部 `default` 的**输入别名**(壳 `normalizePermissionModeAlias`
- *   同一张表:`mode === 'manual' ? 'default' : mode`,枚举本身不含 manual 成员)。
- * · `dontAsk` = 壳侧**最严**模式:`permissions.ts` 把 `behavior==='ask'` 整个改判成 `'deny'`
- *   (DONT_ASK_REJECT_MESSAGE),且它在 `INTERNAL_PERMISSION_MODES` 里 ⇒ `--permission-mode dontAsk`
- *   是合法 CLI 取值、`-p` 车道真可达。wire 五词没有对应词;**不归一的后果是方向错的**——落
- *   permissionModeField 表外支 ⇒ 不 stamp ⇒ server `deriveSettingsPolicy` 因 `!perms` 返回 `{}`
- *   ⇒ **客户端表态派生的门一个都不铸**(部署基线 approvalRequire 与 runtime governance 仍在,
- *   不是「什么都不拦」;但按模式该有的那道门没了),观测上与最松的 `bypassPermissions` 同形
- *   —— 用户要最严、拿到的是最松那一档的形。归一到 `default`(fs 写 ask 门)。
- *   🔴 **这是近似投影,不是等价映射;别把它读成「已经修好了」**,三条残余按坐标记账:
- *     ① `default` 不是 wire 词表里最严的词(`plan` 才是 handsReadOnly 只读手)。选它是因为 `plan`
- *        会连带改变工作流形态(present_plan + 只读手),把「别问我、直接拒」翻成「进规划模式」是
- *        另一种谎报。`default` 是**不改工作流形态的前提下最接近**的落点。
- *     ② `dontAsk` 要的是即刻 deny,`default` 是 ask/park —— 有活体审批面时那条 ask **可以被批准**,
- *        而 dontAsk 语义禁止这条路径。所以「只紧不松」这句话的比较基准**只能是不 stamp 那个落点**
- *        (归一前:该模式的门一个不铸),不是 dontAsk 本义 —— 相对 dontAsk 本义它是松的。要精确
- *        投影必须 server 词表补一个 deny 语义的 wire 词(另票)。
- *     ③ 非 host lane(e2b/k8s/ssh)上 server 的 `fsWriteGate` wiring 恒为 undefined
- *        (resolve-spec `hostSemanticsLane ? … : undefined`),`deriveSettingsPolicy` 的 default 臂
- *        只剩 workflow ask 政策 ⇒ **Write/Edit 在沙箱 lane 上仍不挂门**。
- *        ⚠️ 别写成「壳侧关不掉」——那是过度声称。壳侧**有**一条路:`settings.permissions.ask:
- *        ['Write','Edit','NotebookEdit']` 走 `createAskListPolicy`,那条政策是**名字键控、与 lane
- *        无关**的(task-settings.ts:494-495,不吃 fsWriteGate wiring)。**这条路真的能关掉这个洞**,
- *        本批刻意不走,理由如下(前两条曾被写错、双复审驳回,这里是订正后的版本):
- *        (a) 代价 = **host lane 上 fs 门自己的放行腿被盖掉**。名字键控 ask 与其它政策 deny/ask
- *            恒赢地折叠,所以 ask-list 一挂,host lane 上现在被 scratchpad 豁免/acceptDirs 放行的
- *            写也变成 ask —— 丢的是精度。
- *            (⚠️ 这条只说到这里就够了。两次复审都栽在替这个「没走的选项」推演更细的后果上:
- *            先写成「两 lane 更不一致」被驳,再写成「两 lane 都凡写必问」又被驳——敏感路径 deny 腿
- *            在 host 上仍然 deny,两 lane 并不同形。真要选这条路,后果得当场重新取证,别信这段。)
- *        (b) 代价 = 在 headless 上「凡写必问」而**没有应答者**(#165 = -p 车道无客户端审批面)⇒
- *            沙箱 lane 的每一次 Write 都停在门上 —— 停成 park 还是直接 deny 由部署定(park 要
- *            `durableApproval` 与 checkpoint 存储**两个都在**,缺一就不是 park;精确条件在 server
- *            approval.ts 的 durable 政策 doc 里,本注释不复述以免漂)。两种都是行为面大改,要过
- *            宪法三问,不是复审顺手能落的。
- *            (⚠️ 也不要写成「server 修了这层补偿自然作废」—— 已核实为假:server #153/7.1.0 只把
- *            `MANUAL_MODE_SHELL_GATE` 升到 governance 层,**非 host lane 的 fsWriteGate 仍不建**,
- *            [2713] 那条 @server 分单到今天没兑现,所以这层补偿不会因为 #153 而自动过时。)
- *        (c) 越过「壳带意图、service 解释」的分层——壳替 server 决定了拦哪几个工具名。
- *        ⇒ 记账在此,决定权在仓主(要不要用 ask-list 换掉精度、并同时推 #165);本表只负责
- *          「让 server 有表态可读」。
- * ⚠️ 判据方向(比较基准写死,别读成别的):本表允许的落点 = **相对「不 stamp」严格更紧或等紧**。
- * 加词前先问「这个词 stamp 出去之后,server 铸出来的门比不 stamp 时更紧吗」——更松就不许进表
- * (宁可不 stamp 回落部署基线,也不许客户端表态制造放行)。
- * 注意这**不是**「落点 ≥ 壳内语义」:`dontAsk → default` 就不满足后者(见上方残余②),它满足的是
- * 前者。写判据时用错基准会把这张表读成「已经等价了」。
- * **刻意用 Map 而不是对象字面量**(与 adapt/arms.ts ARMS 表同一条纪律):键来自原始 argv,是开集;
- * 对象表上 `tbl['__proto__']`/`tbl['constructor']` 会顺着原型链取回一个**非字符串**值,把它当
- * `PermissionMode` 往下传是类型谎报(tsc 因 `Record<string,…>` 的索引签名全盲)。Map 无原型链取值。
- */
 const SHELL_INTERNAL_MODE_TO_WIRE = new Map([
     ['manual', 'default'],
     ['dontAsk', 'default'],
 ]);
-/**
- * 归一表的**唯一取值口**(#164 [2760]② wire 面三面同拍,2026-08-06):壳内部模式词 → wire 词;
- * 表外词与 undefined 恒等透传(未表态不制造表态)。两个消费方共用同一张表(单表纪律,禁抄写):
- *   · headless flag 支(本模块 resolveHeadlessPermissionMode);
- *   · 壳交互车道(seamQuery 在 permissionModeField stamp 前归一——修前交互车道 `dontAsk` 落
- *     permissionModeField 表外支不 stamp ⇒ 引擎侧 absent-mode 一个门不铸,与底栏「don't ask on」
- *     指示相反;归一后 stamp `default` ⇒ 引擎铸 ask 门,ask 到壳后由壳侧 dontAsk 决策臂
- *     (ask⇒deny)落地,与 CC 单进程语义对位)。
- * 方向纪律与三条残余记账见上方表 doc,本函数不另立口径。
- */
 export function normalizeShellPermissionModeForWire(mode) {
     if (mode === undefined)
         return undefined;
     return SHELL_INTERNAL_MODE_TO_WIRE.get(mode) ?? mode;
 }
-/**
- * argv 里的 `--permission-mode <v>` / `--permission-mode=<v>`(后者/后出现者赢,commander 同语义)与
- * `--dangerously-skip-permissions`(= bypassPermissions;`--permission-mode` 在场时让位)。
- * 返回 undefined = flag 车道未显式表态。
- *
- * REF-CC-143(dup-07)收编:`--permission-mode` 的取值改吃共用 lastFlagValue(argvFlagValue.ts,
- * `onMissingValue:'latch-previous'`)——旧手写循环对「某一次 occurrence 缺值」的处置是跳过这一次、
- * 锁存(latch)住之前已经取到的合法值,不是把整个旗塌缩成「从没写过」(`--permission-mode plan
- * --permission-mode` 的旧行为是 `mode==='plan'`,不是 `undefined`)。共用叶的缺省策略
- * (`'invalidate'`,sandboxWire/scenarioWire 用)会把这个情形塌缩成「有旗无值」,与本函数原有语义
- * 不符,所以本调用点显式传 `'latch-previous'` 保住旧行为——这才是任务书说的「各调用方保持自己现有
- * 对缺值的处置」(wave1 回炉修复,blocker:此前误用了共用叶的 invalidate 缺省,详见 commit 记账)。
- * `--dangerously-skip-permissions` 的存在性判别不属于「取某旗最后值」这个不变量,单独一个小循环即
- * 可,零重复。
- */
 export function permissionModeFromArgv(argv) {
     const flag = lastFlagValue(argv, '--permission-mode', 'latch-previous');
     if (flag.present && flag.raw !== undefined)
@@ -154,50 +22,29 @@ export function permissionModeFromArgv(argv) {
     for (let i = 0; i < argv.length; i++) {
         const a = argv[i];
         if (a === '--')
-            break; // POSIX 约定:-- 之后不是 flag
+            break;
         if (a === '--dangerously-skip-permissions')
             return 'bypassPermissions';
     }
     return undefined;
 }
-// 一次性告警 latch(-p 是 one-shot 进程;测试钩子可重置)
 let warnedInvalidEnv = false;
-/**
- * 解析 headless `-p` 的 permissionMode stamp。纯函数除告警 latch(同值只警一次)。
- * 调用方(seamQueryEngine.ask)live-gated:mock/pty 车道永不经过这里。
- */
 export function resolveHeadlessPermissionMode(argv, env = hostEnv()) {
-    // 1) CLI flag 恒赢:flag 在场(含 wire 词表外的壳内部模式)⇒ env 完全不看。
     const flagMode = permissionModeFromArgv(argv);
     if (flagMode !== undefined) {
-        // [2713] 最小刀:flag 显式表态 ⇒ 显式 stamp(含 default——旧形 flag=default 不 stamp 让 server
-        // deriveSettingsPolicy 因 settings.permissions 缺席返回 {},按模式派生的门不铸)。壳内部词经 SHELL_INTERNAL_MODE_TO_WIRE
-        // 归一到 wire 词(manual/dontAsk → default;归一表的方向纪律见该常量 doc),勿改 server 词表;
-        // 表外词(未来新增的壳内部模式)经 permissionModeField 双支仍不 stamp = 回落部署基线。
         const normalized = normalizeShellPermissionModeForWire(flagMode);
         return { fields: permissionModeField(normalized, { stampDefault: true }), source: 'flag' };
     }
-    // 2) env 垫层。
     const raw = env[HEADLESS_PERMISSION_MODE_ENV]?.trim();
     if (raw === undefined || raw === '') {
-        // 3) 缺省垫(2026-08-11 裁定,headless 权限缺省收窄):flag/env 双缺席不再走 absent-mode
-        //    (server 7.12.0 起模式翻译表对缺席=键不写=无门,headless 缺省会**无门直落**——与
-        //    对标实现「headless 门照挂照报」相反)。缺省显式 stamp "default" ⇒ 翻译表挂 classify 档,
-        //    写形过分类器、读形白名单放行。旧 server(≤7.11.0)对显式 default 走 manual ask 门解释,
-        //    同向收紧,version-safe。要旧「无门」行为的部署用显式
-        //    `SEMA_HEADLESS_PERMISSION_MODE=bypassPermissions` 表态(缺省绝不宽)。
-        //    source='default' 与 'absent' 分词:absent 只剩「wire 词表外值回落」一支已不存在——保留
-        //    枚举员是为了消费端(日志/围栏)对旧值的开集容纳,本函数不再产它。
         return { fields: permissionModeField('default', { stampDefault: true }), source: 'default' };
     }
     if (HEADLESS_PERMISSION_WIRE_MODES.includes(raw)) {
-        // env 是显式垫层:五词全 stamp(含 default——stampDefault 显式垫,不依赖 absent-mode 缺省解释)。
         return {
             fields: permissionModeField(raw, { stampDefault: true }),
             source: 'env',
         };
     }
-    // 4) 非法 env 值:一次性 warn + 回落缺省垫(绝不 fail,也绝不因坏值放宽成无门)。
     const resolution = {
         fields: permissionModeField('default', { stampDefault: true }),
         source: 'default',
@@ -208,7 +55,6 @@ export function resolveHeadlessPermissionMode(argv, env = hostEnv()) {
     }
     return resolution;
 }
-/** 测试钩子:重置一次性告警 latch。 */
 export function _resetHeadlessPermissionModeWireForTest() {
     warnedInvalidEnv = false;
 }

package/dist/headlessReconnectWire.d.ts

@@ -1,70 +1,5 @@
-/**
- * src/sema/headlessReconnectWire.ts — 重连腿 M2 · R1 换车道续收(design/HEADLESS-RECONNECT-DESIGN.md
- * §3 R1 + §6 M2,2026-07-16)。M1(detachWire 头 + 信号 cancel 兜底,2545900)已发运;本模块把
- * engine-alive-idle 判死升级为「先重连、耗尽才判死」——但只在 headless `-p` detach 车道。
- *
- * 触发点(design §3,四条同时成立才进重连分支):
- *   ① tasks/stream 以 SseIdleError 收场(流静默超 grace)——其它失败形态(engine-down/restarted/
- *      4xx/断连 reset)原样穿透,现行路径一字不动;
- *   ② headless `-p` ∧ detach 头已随首次 POST 发出——本 wrapper 只在 liveClient.tasks.stream 的
- *      opts.headers 携带 x-detach-on-disconnect: 'true' 时套上(唯一 set 头的调用方 =
- *      seamQueryEngine.ask;交互 REPL(seamQuery)与 headless-bg worker 都不传 headers ⇒ 源码级
- *      证明这两条车道一根毛不动,断连=取消语义保持,铁律 5);
- *   ③ durableTaskId 已捕获(X-Task-Id 早捕获,liveClient onResponse)——没有 id 无从换道,原样抛;
- *   ④ 每次重连前置 probeEngineAlive(批 D /health 探针复用)——引擎死了绝不空等,原样抛走
- *      现行 engine-down 判死。
- *
- * 铁律对表:
- *   · signal.aborted 恒先行(铁律 3,seamQuery.ts:1073 契约):重试环每一轮入口先查 aborted,
- *     用户中止绝不进重连分支(连探活都不做);续收中途 aborted → 干净 return(镜像 SDK parseSse
- *     的 abort 语义),上游 print.ts 的 SIGINT 处置(M1 cancel 兜底)全权接管。
- *   · 有界(铁律 5/任务 §4):每 run 最多 HEADLESS_RECONNECT_MAX=2 次壳级重连;耗尽 → 重抛
- *     【原始】SseIdleError(对象恒原件,后续 diagnoseSseIdleTear 打 engine-alive-idle 标 →
- *     seamQueryEngine 现行诚实判死文案,字节不变)。
- *   · 15min STREAM_MAX_DURATION 硬顶(任务 §3):runs.events 车道被 cap 断开时,SDK sse.js
- *     parseSse 自带 Last-Event-ID 立即重连(frame.id 锁存 → 重开带 lastEventId;无进展 5 连败
- *     才放弃)——cap 重连发生在【同一次】openEvents 调用内部,计入同一次重连预算(不额外扣),
- *     铁律 4「不动 SDK」同时满足:runs.events 消费面已有,本模块零 SDK 改动。
- *   · 与 headless-bg 有界重发腿(bgTearResends)互斥:重发腿在 seamQuery.query(REPL 形 worker),
- *     其触发词表本就只含 restarted/engine-down(seamQuery.ts:1143),engine-alive-idle 从不重发;
- *     本重连腿只在 -p detach 车道。两腿车道 + 词表双重不相交,结构性互斥。
- *
- * ── R1 去重锚选型(任务书要求写明选型与理由)────────────────────────────────────────────────
- * runs.events 车道:server streamRunEvents 把账本 seq 写成 SSE `id:` 行(formatEvent id: ev.seq),
- * SDK sse.js 把 frame.id 回贴到 ev.id ⇒ 每个续收帧带单调递增数字 seq。锚 = lastSeenSeq:
- *   a) 跨壳级 attempt 续传:第二次 openEvents 传 Last-Event-ID=lastSeenSeq(server 从其后回放);
- *   b) 防双投:丢弃 seq ≤ lastSeenSeq 的重放帧(server 从头回放/416 回卷都兜住)。
- * 首次换道(tasks/stream → runs.events):tasks/stream 帧无 id(SDK tasks.js 不回贴 frame.id,
- * server sync 腿也不写 id: 行)⇒ 无从定位,只能从起点(不带 Last-Event-ID)拉。防双投依据 =
- * server 实证(1.205/1.209 dist 逐行核对):sync /v1/tasks/stream 腿【不】逐事件落账(runs.js 的
- * appendEvent 只在 async runs 腿与 resume 腿;sync 腿只 createRun + setTerminal(finalResult))⇒
- * sync 腿 run 的账本在终局前恒空,从起点拉不存在「重放已消费帧」面;将来 server 若开始 sync 腿
- * 落账,守卫 = ①终帧唯一(本 wrapper 首终帧即 return + adapter runStream 首终帧 return + 批 B
- * 双帧守卫「恰一条 result」)②seq 锚(首帧起锁存,attempt 间绝不回放)③gap-check 记账:换道前
- * 已消费的 delta 与账本聚合 text 事件无逐字节对齐关系,真正的精确锚需要 server 给 tasks/stream
- * 帧发 id(引擎侧诉求,走协作板,非壳侧可解)。
- *
- * ── 账本空(现役 server sync 腿)时的续收降级(R1b)────────────────────────────────────────
- * 同一实证的另一面:detach 后 run 后台跑完,账本无事件行,runs.events 只会心跳保活直到 run row
- * 落终局,然后无终帧地收流(SDK 无进展 5 连败抛错)。此时 run 的终局【已在】run row 里
- * (GET /v1/runs/:id → RunRecord.result = TaskResult,含完整最终文本)——续收环的 catch 里查
- * run row:已终局 → 合成终帧(done{result} / failed)喂回同一消费管线,turn 以 rc=0 正常收尾,
- * 最终答案全量保真(-p 的 result 面 = done.result.result 字符串,非增量拼接);未终局(还在跑/
- * suspended)→ 计预算继续重试,耗尽才判死。中途 delta 的全帧保真(R1a 环)在账本有事件行时
- * (resume 腿 run / 将来 sync 腿落账的 server)自动生效——两形态由同一环处理,帧结构差异
- * (text/reasoning 聚合事件 vs *_delta)由 adapter eventToSdkMessage 既有 case 'text'/'reasoning'
- * 消费面兜住。
- */
 import type { AgentEvent } from '@sema-agent/sdk';
-/** 每 run 壳级重连预算(design 铁律 5)。cap/416 的 SDK 内部续传不计入(同一次 openEvents)。
- *  选值:design/HEADLESS-RECONNECT-DESIGN.md §2 铁律 5 只钉了「有界」与这个数,未留更细的推导
- *  —— 诚实记账,不倒推一个当时没写下来的公式。可核实的取值依据是本环自身的形状(REF-CC-148
- *  普查记账):每次尝试是两次真网络往返(重试环里的 `probe(deps.baseUrl)` + `deps.openEvents(…)`)
- *  且两次尝试之间**零退避**,预算越大,在一个真死引擎上耗尽这个环、落到诚实判死文案之前的墙钟代价就越高
- *  ——2 是「给瞬时抖动一次重试余地」与「死引擎上不过度拖延判死」之间的保守取值,不是精算结果;
- *  若上游把撕裂形态改成更常见的可重连态,这个数可能需要上调(域词表-19 已留此账)。 */
 export declare const HEADLESS_RECONNECT_MAX = 2;
-/** GET /v1/runs/:id 的 run row 终局子集(SDK RunRecord;字段防御性读)。 */
 export interface RunRowLike {
     status?: string;
     result?: unknown;
@@ -72,31 +7,12 @@ export interface RunRowLike {
     error?: string;
 }
 export interface HeadlessReconnectDeps {
-    /** 引擎 baseUrl(探活用;凭证不经本模块——openEvents/getRun 闭包自带)。 */
     baseUrl: string;
-    /** X-Task-Id 早捕获读数(liveClient onResponse 闭包);null = 未捕获 ⇒ 不换道。 */
     getTaskId: () => string | null;
-    /** runs.events 换道开流(liveClient 闭包 → client.runs.events;lastEventId = 去重锚续传)。 */
     openEvents: (taskId: string, lastEventId?: string) => AsyncGenerator<AgentEvent>;
-    /** run row 终局读数(R1b 降级捞终局;失败返回 null,永不抛)。 */
     getRun: (taskId: string) => Promise<RunRowLike | null>;
     signal?: AbortSignal;
-    /** 测试注入位;缺省 = 批 D probeEngineAlive(/health,2s 预算)。 */
     probeAlive?: (baseUrl: string) => Promise<boolean>;
 }
-/** run row → 合成终帧(R1b)。带 result 对象的引擎终态(全词表)合成 done{result}——与
- *  tasks/stream 终帧字节同构,adapter terminalToSdkResult 全枚举分流([909]B1)原样生效
- *  (timeout→error_max_turns、blocked→error_during_execution、park→[884]A1 臂);裸 failed
- *  (无 result)合成 failed 事件。running / 无 result 的 park(可能还会被 approvals 解锁)null
- *  —— 计预算继续重试,耗尽才判死。 */
 export declare function terminalEventFromRunRow(row: RunRowLike | null): AgentEvent | null;
-/**
- * withHeadlessR1Reconnect(live, deps) — the M2 R1 lane-switch wrapper.
- *
- * 位置:liveClient.tasks.stream 管线【最内层】(demux/HITL 桥/captureSessionId/normalizeToolNames/
- * diagnoseSseIdleTear 之内)——续收帧与合成终帧流经与 live 帧完全相同的下游包装(工具名规整、
- * sessionId 捕获、HITL 桥、批 B 守卫),零特殊路径。重连成功 → 生成器以终帧正常 return ⇒
- * diagnoseSseIdleTear/tearVerdict 永不介入,turn 正常收尾;耗尽/不可换道 → 重抛原始 SseIdleError,
- * 外层打标 + 现行判死文案,字节不变。
- */
 export declare function withHeadlessR1Reconnect(live: AsyncGenerator<AgentEvent>, deps: HeadlessReconnectDeps): AsyncGenerator<AgentEvent>;

package/dist/headlessReconnectWire.js

@@ -1,26 +1,11 @@
 import { isSseIdleError, probeEngineAlive } from './sseIdleTriage.js';
 import { hostEnv } from './hostEnv.js';
-/** 每 run 壳级重连预算(design 铁律 5)。cap/416 的 SDK 内部续传不计入(同一次 openEvents)。
- *  选值:design/HEADLESS-RECONNECT-DESIGN.md §2 铁律 5 只钉了「有界」与这个数,未留更细的推导
- *  —— 诚实记账,不倒推一个当时没写下来的公式。可核实的取值依据是本环自身的形状(REF-CC-148
- *  普查记账):每次尝试是两次真网络往返(重试环里的 `probe(deps.baseUrl)` + `deps.openEvents(…)`)
- *  且两次尝试之间**零退避**,预算越大,在一个真死引擎上耗尽这个环、落到诚实判死文案之前的墙钟代价就越高
- *  ——2 是「给瞬时抖动一次重试余地」与「死引擎上不过度拖延判死」之间的保守取值,不是精算结果;
- *  若上游把撕裂形态改成更常见的可重连态,这个数可能需要上调(域词表-19 已留此账)。 */
 export const HEADLESS_RECONNECT_MAX = 2;
-/** SEMA_DEBUG 探针(headless `-p` 车道 Ink 未挂载,stderr 可用;绝不带凭证/帧内容)。 */
 function debugLog(msg) {
     if (hostEnv().SEMA_DEBUG) {
-        // eslint-disable-next-line no-console
         console.error(`[sema] headless reconnect: ${msg}`);
     }
 }
-/** 引擎终态词表全集(core 1.298 TaskStatus;server runs.js setTerminal(taskId, safe.status, …)
- *  把引擎 status【原样】写进 run row ⇒ row.status 可以是全部 6 词,不只 completed/failed)。
- *  🔴 **run 行自己的 `status` 列 engine 7.64.0 没动**(BREAKING 帖逐字:变的是引擎结果 blob,
- *  行的列照旧说五词,只是数据源改成从因由投影一次)⇒ 本表原样有效,不随 `TaskResult` 形变。
- *  [909]B3 复核发现的真缺口:此前只认 completed/failed,timeout/blocked 终局的 run row 永不
- *  合成终帧 → 续收环重试到预算耗尽 → 假判死(终局明明就在 row 里)。 */
 const RUN_ROW_TERMINAL_STATUSES = new Set([
     'completed',
     'failed',
@@ -29,23 +14,11 @@ const RUN_ROW_TERMINAL_STATUSES = new Set([
     'suspended',
     'needs_review',
 ]);
-/** run row → 合成终帧(R1b)。带 result 对象的引擎终态(全词表)合成 done{result}——与
- *  tasks/stream 终帧字节同构,adapter terminalToSdkResult 全枚举分流([909]B1)原样生效
- *  (timeout→error_max_turns、blocked→error_during_execution、park→[884]A1 臂);裸 failed
- *  (无 result)合成 failed 事件。running / 无 result 的 park(可能还会被 approvals 解锁)null
- *  —— 计预算继续重试,耗尽才判死。 */
 export function terminalEventFromRunRow(row) {
     if (!row || typeof row.status !== 'string')
         return null;
     if (RUN_ROW_TERMINAL_STATUSES.has(row.status)) {
         if (row.result && typeof row.result === 'object') {
-            // sync 腿 setTerminal 存的就是终帧的 TaskResult —— 与 tasks/stream 终帧 done{result} 字节同构,
-            // terminalToSdkResult 文案线原样生效。
-            // 🔴 **这是一条读盘面**(0.60.0 起要点名):`GET /v1/runs/:id` 的 `result` 是存储 blob 的**逐字
-            //    透传**,server **不补** `terminal` ⇒ 一台跨 engine 7.64.0 升级过的部署上,升级**之前**落盘
-            //    的那些行读出来仍是**扁平**形(退役的八个平面键)。两代字节由 `runTerminal.readRunTerminal`
-            //    的判别位 `"terminal" in result` 各归各位,所以本函数**照旧原样透传、一个键都不补**:补一个
-            //    `terminal` 出来就是替停产的写者重新裁定一次形状(server 自己也刻意不做)。
             return { type: 'done', result: row.result };
         }
         if (row.status === 'failed') {
@@ -58,15 +31,6 @@ export function terminalEventFromRunRow(row) {
     }
     return null;
 }
-/**
- * withHeadlessR1Reconnect(live, deps) — the M2 R1 lane-switch wrapper.
- *
- * 位置:liveClient.tasks.stream 管线【最内层】(demux/HITL 桥/captureSessionId/normalizeToolNames/
- * diagnoseSseIdleTear 之内)——续收帧与合成终帧流经与 live 帧完全相同的下游包装(工具名规整、
- * sessionId 捕获、HITL 桥、批 B 守卫),零特殊路径。重连成功 → 生成器以终帧正常 return ⇒
- * diagnoseSseIdleTear/tearVerdict 永不介入,turn 正常收尾;耗尽/不可换道 → 重抛原始 SseIdleError,
- * 外层打标 + 现行判死文案,字节不变。
- */
 export async function* withHeadlessR1Reconnect(live, deps) {
     let originalTearErr;
     try {
@@ -74,85 +38,68 @@ export async function* withHeadlessR1Reconnect(live, deps) {
             yield ev;
             const t = ev?.type;
             if (t === 'done' || t === 'failed')
-                return; // 终帧已到 —— 首终帧即收官(批 B 双帧守卫同侧)
+                return;
         }
-        return; // 流干净收尾(mock 车道/abort return)——无终帧也不由本腿补,现行行为不变
+        return;
     }
     catch (e) {
         originalTearErr = e;
     }
-    // ── 重试环:每轮入口按铁律顺序分诊,非命中一律重抛【原始】错误(现行失败路径字节不变)──
     let attempts = 0;
-    let lastSeenSeq; // R1 去重锚(runs.events SSE id = 账本 seq;见模块头选型)
+    let lastSeenSeq;
     const probe = deps.probeAlive ?? probeEngineAlive;
-    // REF-CC-148(域词表-19):originalTearErr 在环内从不被重写(它是进入本重试环前唯一捕获的
-    // 错误对象),所以这个判型是**环不变式**——算一次即可,不必逐轮重算。
-    // wave1 回炉复审(复审 blocker):求值时机必须排在铁律 3(用户中止恒先行)**之后**才对 main
-    // 逐字——main 是「每轮入口先查 aborted,再判型」,若把判型提到循环顶(环外、抢在第一轮的
-    // aborted 检查之前),当 originalTearErr 是一个 `.name` getter 会抛的畸形错误对象、且入环时
-    // signal 已经 aborted 时,新顺序会先让 isSseIdleError 抛出**那个畸形对象的二次异常**,盖过
-    // 本该抛出的 originalTearErr,违反铁律 3。改法:惰性 memo——用 `undefined` 起始态占位「尚未算
-    // 过」(合法返回值只有 true/false),真正求值仍只发生一次,但**排在每轮的 aborted 检查之后**,
-    // 与 main 的求值顺序逐字一致,「只判一次」的不变量原样保留。
     let isRecoverableTear;
     for (;;) {
         if (deps.signal?.aborted)
-            throw originalTearErr; // 铁律 3:用户中止恒先行,绝不进重连分支
+            throw originalTearErr;
         if (isRecoverableTear === undefined)
             isRecoverableTear = isSseIdleError(originalTearErr);
         if (!isRecoverableTear)
-            throw originalTearErr; // 只救 engine-alive-idle 的静默撕裂形
+            throw originalTearErr;
         const taskId = deps.getTaskId();
         if (!taskId)
-            throw originalTearErr; // X-Task-Id 未捕获(首轮早期窗)——无从换道,接受
+            throw originalTearErr;
         if (attempts >= HEADLESS_RECONNECT_MAX) {
             debugLog(`budget exhausted (${attempts}/${HEADLESS_RECONNECT_MAX}) — falling to the honest death path`);
-            throw originalTearErr; // 耗尽 → 现行 engine-alive-idle 判死(文案已诚实,M1)
+            throw originalTearErr;
         }
         attempts++;
         if (!(await probe(deps.baseUrl)))
-            throw originalTearErr; // 铁律 5:引擎死 → 现行 engine-down 路径
+            throw originalTearErr;
         debugLog(`attempt ${attempts}/${HEADLESS_RECONNECT_MAX} — switching to runs.events(${taskId}${lastSeenSeq !== undefined ? `, Last-Event-ID ${lastSeenSeq}` : ''})`);
         try {
             const cont = deps.openEvents(taskId, lastSeenSeq !== undefined ? String(lastSeenSeq) : undefined);
             for await (const ev of cont) {
                 if (deps.signal?.aborted)
-                    return; // 中止 → 干净收流(print.ts SIGINT 处置 + M1 cancel 兜底接管)
+                    return;
                 const rec = ev;
                 const t = rec?.type;
                 if (t === undefined)
-                    continue; // 心跳帧(data:{})——车道保活杂音,不进消费管线
+                    continue;
                 if (t === 'error') {
-                    // STREAM_MAX_DURATION cap 帧(server streamSseLog):SDK parseSse 已锁存 Last-Event-ID
-                    // 并自动重开(同一次 openEvents 内部,计入同一次预算)——本帧是车道协议杂音,不下发。
                     debugLog(`runs.events lane frame type=error code=${String(rec?.errorCode ?? rec?.code ?? '')} — SDK resumes with Last-Event-ID internally`);
                     continue;
                 }
                 const seq = typeof rec?.id === 'string' && /^\d+$/.test(rec.id) ? Number(rec.id) : undefined;
                 if (seq !== undefined) {
                     if (lastSeenSeq !== undefined && seq <= lastSeenSeq)
-                        continue; // 重放帧 → seq 锚去重(防双投)
+                        continue;
                     lastSeenSeq = seq;
                 }
-                // 终帧日志必须在 yield 之前:下游(adapter runStream)拿到首终帧即 return 弃养本生成器,
-                // yield 之后的语句不再执行(受控腿 leg 1 实测)。return 语义不受影响(弃养即收官)。
                 if (t === 'done' || t === 'failed')
-                    debugLog(`resumed to terminal (${String(t)}) after ${attempts} reconnect(s)`); // 判死解除
+                    debugLog(`resumed to terminal (${String(t)}) after ${attempts} reconnect(s)`);
                 yield ev;
                 if (t === 'done' || t === 'failed')
                     return;
             }
-            // 无终帧收流(SDK 只在 signal.aborted 时干净 return;防御分支)——按撕裂再走一轮预算
             if (deps.signal?.aborted)
                 return;
             debugLog('runs.events continuation ended without a terminal frame');
         }
         catch (contErr) {
-            // 续收环失败。现役 server sync 腿账本为空 ⇒ run 落终局后 SDK 以「无进展 5 连败」收场
-            // ——这不是死刑:终局已在 run row(R1b),查得到就合成终帧收官。
             debugLog(`runs.events continuation failed: ${contErr instanceof Error ? contErr.message : String(contErr)}`);
             if (deps.signal?.aborted)
-                throw originalTearErr; // 铁律 3:中止后不捞终局,交给上游中止处置
+                throw originalTearErr;
             const row = await deps.getRun(taskId).catch(() => null);
             const terminal = terminalEventFromRunRow(row);
             if (terminal) {
@@ -160,7 +107,6 @@ export async function* withHeadlessR1Reconnect(live, deps) {
                 yield terminal;
                 return;
             }
-            // run 还在跑 / suspended / row 读不到 —— 计预算继续重试(环顶做 aborted/预算/探活分诊)
         }
     }
 }