@sema-agent/client-core 0.5.0 → 0.7.0

package/dist/clientSlice.d.ts

@@ -0,0 +1,169 @@
+/**
+ * clientSlice.ts — **verb 门面接口定型**(B4,设计稿 §8-1 裁决:「要,但只定接口不定实现」)。
+ *
+ * ## 为什么要有这一层
+ *
+ * §6.1.4 解包 CC 桌面端量到 **854 条 IPC 通道**(`ns_$_Service_$_method`),其中会话相关的
+ * `LocalSessions` 一族就有 212 个 verb。那一层客观存在而且很大 —— **不定接口,每端会各长一套**,
+ * 于是 HITL 权威登记、通知直结这些「必须只有一个落点」的东西会被重写三遍。
+ *
+ * ## 但它**只是接口**
+ *
+ * 🔴 本文件不导出任何 IPC / HTTP / SDK 实现,一行运行时代码都没有(编译产物只有类型)。
+ * 依据公理一:CC 的皮肤形状不进 wire ⇒ **IPC 的形状同样不该进 wire**。谁来实现:
+ *   · TUI  = 直接把 `@sema-agent/sdk` 的 AgentClient 方法接上;
+ *   · web  = BFF 转发(逐请求注入 principal);
+ *   · 桌面 = 主进程 IPC(CC 同款 `ns_$_Service_$_method` 形)。
+ *
+ * ## 判据:什么进这个接口
+ *
+ * **会话运行时自己会调的 verb 才进**。纯 UI 触发、端各自决定的动作(开面板、切主题、选文件)
+ * 不进 —— 那些是端的事。今天这张表按 cli 现役会话链路归纳,`additive` 演进(只增不改),
+ * 与 `CHROME_ARMS` 一样做成可断言的数据出口。
+ */
+/** 一个 verb 的登记项(覆盖率断言用;与 `CHROME_ARMS` 同形)。 */
+export interface ClientVerbSpec {
+    /** `ClientSliceLike` 上的方法名。 */
+    verb: string;
+    /** 缺它会让**已发生的行为丢失**(而不是少个装饰)⇒ required。 */
+    required: boolean;
+    duty: string;
+}
+/**
+ * 会话运行时需要宿主提供的 verb 集合(**结构型**:实现方不必 implements,形状对上即可)。
+ *
+ * 全部返回 Promise —— 三端里有两端是跨进程/跨网络的,同步形会逼 web/桌面造假。
+ */
+export interface ClientSliceLike {
+    /** 发起一个 turn,拿到 wire 帧流(喂给 `adapt()`)。 */
+    streamTask(req: unknown, opts?: {
+        signal?: {
+            readonly aborted: boolean;
+        };
+    }): AsyncIterable<unknown>;
+    /** 取消在跑的 run(Esc / `-p` 的信号兜底)。 */
+    cancelRun(runId: string): Promise<void>;
+    /** 工具审批决断。`boundCallId` / `boundInputHash` **必须原样回显**,一个字节不改。 */
+    respondApproval(input: {
+        approvalId: string;
+        decision: 'allow' | 'deny';
+        boundCallId: string;
+        boundInputHash: string;
+    }): Promise<void>;
+    /** AskUserQuestion 应答。 */
+    respondQuestion(input: {
+        questionId: string;
+        answer: unknown;
+    }): Promise<void>;
+    /** plan-review 决断(`done{status:"needs_review"}` + gate `plan_review` 的 resume 腿)。 */
+    respondPlanReview(input: {
+        taskId: string;
+        approved: boolean;
+        feedback?: string;
+    }): Promise<void>;
+    /** 后台子代的实时转录尾巴(查看态)。 */
+    tailSubagent(taskId: string): AsyncIterable<unknown>;
+    /** 给在跑的子代插话(steer)。 */
+    steerSubagent(input: {
+        taskId: string;
+        text: string;
+    }): Promise<void>;
+    /** 唤醒已停机的保留子代(design/144 `retainSubagentSessions` 的兑现面)。 */
+    wakeSubagent(input: {
+        taskId: string;
+        message: string;
+    }): Promise<void>;
+    /** fleet 行帧流(常开;后台子代唯一在场的 lane)。 */
+    streamFleet(): AsyncIterable<unknown>;
+    /** 列会话(resume 选单)。 */
+    listSessions(input?: {
+        limit?: number;
+    }): Promise<unknown>;
+    /** 读一个会话的转录(桌面与 TUI 共享 `~/.claude/projects/**` 的先例,§8-11)。 */
+    readSession(sessionId: string): Promise<unknown>;
+    /** 引擎 caps(壳侧所有 `engineCapTrue` 门的数据源)。 */
+    capabilities(): Promise<unknown>;
+    /** 健康探测(🔴 语义差见 `probeHealth` 记账:SDK 要求 `status==='ok'`,壳现实现只要 `res.ok`)。 */
+    probeHealth(): Promise<{
+        ok: boolean;
+        version?: string;
+    }>;
+}
+/**
+ * verb 覆盖率断言出口(§8-1 的另一半)。
+ *
+ * 宿主自检遍历本表,对 `required:true` 的逐条断言"我实现了"。不实现 ≠ 报错,是**那个面在该端是哑的**
+ * —— 与 `CHROME_ARMS` 同一套纪律:把义务做成数据,而不是散落在注释里。
+ */
+export declare const CLIENT_VERBS: readonly [{
+    readonly verb: "streamTask";
+    readonly required: true;
+    readonly duty: "发起 turn 并回 wire 帧流(会话运行时的入口)";
+}, {
+    readonly verb: "cancelRun";
+    readonly required: true;
+    readonly duty: "取消在跑的 run(不实现 = Esc 只停渲染,引擎照跑)";
+}, {
+    readonly verb: "respondApproval";
+    readonly required: true;
+    readonly duty: "工具审批;两元组 verbatim 回显(安全不变量)";
+}, {
+    readonly verb: "respondQuestion";
+    readonly required: true;
+    readonly duty: "AskUserQuestion 应答(不实现 = 问了没法答,turn 挂死)";
+}, {
+    readonly verb: "respondPlanReview";
+    readonly required: false;
+    readonly duty: "plan-review 决断(fail-soft:不实现只是少一张审批卡)";
+}, {
+    readonly verb: "tailSubagent";
+    readonly required: false;
+    readonly duty: "后台子代查看态实时转录";
+}, {
+    readonly verb: "steerSubagent";
+    readonly required: false;
+    readonly duty: "给在跑的子代插话";
+}, {
+    readonly verb: "wakeSubagent";
+    readonly required: false;
+    readonly duty: "唤醒保留子代(SendMessage 语义)";
+}, {
+    readonly verb: "streamFleet";
+    readonly required: false;
+    readonly duty: "fleet 行帧流(后台子代面板行的唯一来源)";
+}, {
+    readonly verb: "listSessions";
+    readonly required: false;
+    readonly duty: "resume 选单";
+}, {
+    readonly verb: "readSession";
+    readonly required: false;
+    readonly duty: "读历史转录";
+}, {
+    readonly verb: "capabilities";
+    readonly required: true;
+    readonly duty: "引擎 caps(所有能力门的数据源;不实现 = 门全判假)";
+}, {
+    readonly verb: "probeHealth";
+    readonly required: false;
+    readonly duty: "健康探测";
+}];
+type _MissingFromTable = Exclude<keyof ClientSliceLike, (typeof CLIENT_VERBS)[number]['verb']>;
+type _ExtraInTable = Exclude<(typeof CLIENT_VERBS)[number]['verb'], keyof ClientSliceLike>;
+type _MustBeNever<T extends never> = T;
+export type _VerbTableClosure = [_MustBeNever<_MissingFromTable>, _MustBeNever<_ExtraInTable>];
+/**
+ * 🔴 `probeHealth` 的**行为差记账**(B4,设计稿 §3 B4 第四件明确要求先保旧行为)。
+ *
+ * 壳里两处手拼 `/health`(`S/limitsWire.ts:225`、`S/detachWire.ts:82`)判的是 **`res.ok`**
+ * (HTTP 2xx 即算活);SDK 的 `probeHealth` 额外要求 **`body.status === 'ok'`**。
+ * 差异面:引擎起来了但自报 degraded(2xx + `status!=='ok'`)时 —— 手拼判**活**,SDK 判**死**。
+ *
+ * B4 的处置:**先保旧行为**(不换,两处仍判 `res.ok`),差异记在这里候裁。
+ * 换的话是行为改动,要按宪法三问单独立项:
+ *   · 谁需要:degraded 引擎上 `--max-*` 版本门与 detach 头版本门本就该保守拒发 ⇒ SDK 语义更对;
+ *   · 谁受害:自报 degraded 但功能其实在线的引擎,`-p` 会少发 detach 头(断连即杀 run)⇒ 真回归;
+ *   · 补偿:换之前先量一次"degraded 但可用"在真部署里出不出现。
+ */
+export declare const PROBE_HEALTH_DIVERGENCE: string;
+export {};

package/dist/clientSlice.js

@@ -0,0 +1,62 @@
+/**
+ * clientSlice.ts — **verb 门面接口定型**(B4,设计稿 §8-1 裁决:「要,但只定接口不定实现」)。
+ *
+ * ## 为什么要有这一层
+ *
+ * §6.1.4 解包 CC 桌面端量到 **854 条 IPC 通道**(`ns_$_Service_$_method`),其中会话相关的
+ * `LocalSessions` 一族就有 212 个 verb。那一层客观存在而且很大 —— **不定接口,每端会各长一套**,
+ * 于是 HITL 权威登记、通知直结这些「必须只有一个落点」的东西会被重写三遍。
+ *
+ * ## 但它**只是接口**
+ *
+ * 🔴 本文件不导出任何 IPC / HTTP / SDK 实现,一行运行时代码都没有(编译产物只有类型)。
+ * 依据公理一:CC 的皮肤形状不进 wire ⇒ **IPC 的形状同样不该进 wire**。谁来实现:
+ *   · TUI  = 直接把 `@sema-agent/sdk` 的 AgentClient 方法接上;
+ *   · web  = BFF 转发(逐请求注入 principal);
+ *   · 桌面 = 主进程 IPC(CC 同款 `ns_$_Service_$_method` 形)。
+ *
+ * ## 判据:什么进这个接口
+ *
+ * **会话运行时自己会调的 verb 才进**。纯 UI 触发、端各自决定的动作(开面板、切主题、选文件)
+ * 不进 —— 那些是端的事。今天这张表按 cli 现役会话链路归纳,`additive` 演进(只增不改),
+ * 与 `CHROME_ARMS` 一样做成可断言的数据出口。
+ */
+/**
+ * verb 覆盖率断言出口(§8-1 的另一半)。
+ *
+ * 宿主自检遍历本表,对 `required:true` 的逐条断言"我实现了"。不实现 ≠ 报错,是**那个面在该端是哑的**
+ * —— 与 `CHROME_ARMS` 同一套纪律:把义务做成数据,而不是散落在注释里。
+ */
+// 🔴 **不要**给这个 const 加 `: readonly ClientVerbSpec[]` 注解 —— 注解会把 `verb` 拓宽成 `string`,
+// 下面那道编译期双向闭合门就变成恒真的空转(B4 首写时正是这么写的,加注解后 `Exclude` 恒为 `string`
+// ⇒ 门当场红且删表项也红,红得毫无判别力)。用 `as const satisfies` 既约束形状又保住字面量类型。
+export const CLIENT_VERBS = [
+    { verb: 'streamTask', required: true, duty: '发起 turn 并回 wire 帧流(会话运行时的入口)' },
+    { verb: 'cancelRun', required: true, duty: '取消在跑的 run(不实现 = Esc 只停渲染,引擎照跑)' },
+    { verb: 'respondApproval', required: true, duty: '工具审批;两元组 verbatim 回显(安全不变量)' },
+    { verb: 'respondQuestion', required: true, duty: 'AskUserQuestion 应答(不实现 = 问了没法答,turn 挂死)' },
+    { verb: 'respondPlanReview', required: false, duty: 'plan-review 决断(fail-soft:不实现只是少一张审批卡)' },
+    { verb: 'tailSubagent', required: false, duty: '后台子代查看态实时转录' },
+    { verb: 'steerSubagent', required: false, duty: '给在跑的子代插话' },
+    { verb: 'wakeSubagent', required: false, duty: '唤醒保留子代(SendMessage 语义)' },
+    { verb: 'streamFleet', required: false, duty: 'fleet 行帧流(后台子代面板行的唯一来源)' },
+    { verb: 'listSessions', required: false, duty: 'resume 选单' },
+    { verb: 'readSession', required: false, duty: '读历史转录' },
+    { verb: 'capabilities', required: true, duty: '引擎 caps(所有能力门的数据源;不实现 = 门全判假)' },
+    { verb: 'probeHealth', required: false, duty: '健康探测' },
+];
+/**
+ * 🔴 `probeHealth` 的**行为差记账**(B4,设计稿 §3 B4 第四件明确要求先保旧行为)。
+ *
+ * 壳里两处手拼 `/health`(`S/limitsWire.ts:225`、`S/detachWire.ts:82`)判的是 **`res.ok`**
+ * (HTTP 2xx 即算活);SDK 的 `probeHealth` 额外要求 **`body.status === 'ok'`**。
+ * 差异面:引擎起来了但自报 degraded(2xx + `status!=='ok'`)时 —— 手拼判**活**,SDK 判**死**。
+ *
+ * B4 的处置:**先保旧行为**(不换,两处仍判 `res.ok`),差异记在这里候裁。
+ * 换的话是行为改动,要按宪法三问单独立项:
+ *   · 谁需要:degraded 引擎上 `--max-*` 版本门与 detach 头版本门本就该保守拒发 ⇒ SDK 语义更对;
+ *   · 谁受害:自报 degraded 但功能其实在线的引擎,`-p` 会少发 detach 头(断连即杀 run)⇒ 真回归;
+ *   · 补偿:换之前先量一次"degraded 但可用"在真部署里出不出现。
+ */
+export const PROBE_HEALTH_DIVERGENCE = 'probeHealth: SDK 要求 status==="ok",壳侧 limitsWire:225 / detachWire:82 手拼只要 res.ok。' +
+    'B4 保旧行为(res.ok),差异候裁 —— 换成 SDK 语义会让"自报 degraded 但可用"的引擎少发 detach 头。';

package/dist/diff/patch.d.ts

@@ -0,0 +1,29 @@
+/**
+ * src/diff/patch.ts — T20:**diff hunks 在客户端算**(core 已裁定归客户端,零上游依赖)。
+ *
+ * 为什么必须进本包:core 明确「引擎发 originalFile(客户端永远重建不出来的那一半),hunks 由客户端
+ * 算」—— 那么每个端(TUI/web/桌面)各算一遍就是三份实现三种 hunk;进包之后是**一份**。
+ * 搬自 cli `src/utils/diff.ts:81 getPatchFromContents` + `src/utils/file.ts:137
+ * convertLeadingTabsToSpaces`,**逐字**(含 & / $ 转义 token 与 CONTEXT_LINES/TIMEOUT 常量),
+ * 只丢掉宿主侧的 analytics / LOC 计数副作用(那两条在 cli 里也不在本函数内)。
+ *
+ * 🔴 唯一的运行时依赖 `diff`(jsdiff 9,零传递依赖、纯 JS、浏览器可用)—— 本包第一个 runtime dep。
+ * 判据:它不是「顺手拉进来的 hub」,而是 T20 这条能力**本身**;不引它就只能把能力退回各端。
+ * portability 门的 ALLOWED_PACKAGES 因此显式登记 `diff` 一条(登记 = 可审计,不是放行一切)。
+ */
+import { type StructuredPatchHunk } from 'diff';
+export declare const CONTEXT_LINES = 3;
+export declare const DIFF_TIMEOUT_MS = 5000;
+/**
+ * 渲染前把**行首** tab 折成两空格 —— CC 自己的 Edit 卡在 structuredPatch 之前做同一件事
+ * (FileEditTool/utils.ts),不做的话 tab 缩进文件两边算出来的 hunk 对不上。
+ */
+export declare function convertLeadingTabsToSpaces(content: string): string;
+export declare function getPatchFromContents({ filePath, oldContent, newContent, ignoreWhitespace, singleHunk, }: {
+    filePath: string;
+    oldContent: string;
+    newContent: string;
+    ignoreWhitespace?: boolean;
+    singleHunk?: boolean;
+}): StructuredPatchHunk[];
+export type { StructuredPatchHunk };

package/dist/diff/patch.js

@@ -0,0 +1,45 @@
+/**
+ * src/diff/patch.ts — T20:**diff hunks 在客户端算**(core 已裁定归客户端,零上游依赖)。
+ *
+ * 为什么必须进本包:core 明确「引擎发 originalFile(客户端永远重建不出来的那一半),hunks 由客户端
+ * 算」—— 那么每个端(TUI/web/桌面)各算一遍就是三份实现三种 hunk;进包之后是**一份**。
+ * 搬自 cli `src/utils/diff.ts:81 getPatchFromContents` + `src/utils/file.ts:137
+ * convertLeadingTabsToSpaces`,**逐字**(含 & / $ 转义 token 与 CONTEXT_LINES/TIMEOUT 常量),
+ * 只丢掉宿主侧的 analytics / LOC 计数副作用(那两条在 cli 里也不在本函数内)。
+ *
+ * 🔴 唯一的运行时依赖 `diff`(jsdiff 9,零传递依赖、纯 JS、浏览器可用)—— 本包第一个 runtime dep。
+ * 判据:它不是「顺手拉进来的 hub」,而是 T20 这条能力**本身**;不引它就只能把能力退回各端。
+ * portability 门的 ALLOWED_PACKAGES 因此显式登记 `diff` 一条(登记 = 可审计,不是放行一切)。
+ */
+import { structuredPatch } from 'diff';
+export const CONTEXT_LINES = 3;
+export const DIFF_TIMEOUT_MS = 5_000;
+// cli 原注:`&` 会让 diff 库犯迷糊,先换成 token、算完再换回来。`$` 同理(替换模式转义位)。
+const AMPERSAND_TOKEN = '<<:AMPERSAND_TOKEN:>>';
+const DOLLAR_TOKEN = '<<:DOLLAR_TOKEN:>>';
+function escapeForDiff(s) {
+    return s.replaceAll('&', AMPERSAND_TOKEN).replaceAll('$', DOLLAR_TOKEN);
+}
+function unescapeFromDiff(s) {
+    return s.replaceAll(AMPERSAND_TOKEN, '&').replaceAll(DOLLAR_TOKEN, '$');
+}
+/**
+ * 渲染前把**行首** tab 折成两空格 —— CC 自己的 Edit 卡在 structuredPatch 之前做同一件事
+ * (FileEditTool/utils.ts),不做的话 tab 缩进文件两边算出来的 hunk 对不上。
+ */
+export function convertLeadingTabsToSpaces(content) {
+    // 无 tab 的常见情形直接短路(/gm 正则会逐行扫)。
+    if (!content.includes('\t'))
+        return content;
+    return content.replace(/^\t+/gm, _ => '  '.repeat(_.length));
+}
+export function getPatchFromContents({ filePath, oldContent, newContent, ignoreWhitespace = false, singleHunk = false, }) {
+    const result = structuredPatch(filePath, filePath, escapeForDiff(oldContent), escapeForDiff(newContent), undefined, undefined, {
+        ignoreWhitespace,
+        context: singleHunk ? 100_000 : CONTEXT_LINES,
+        timeout: DIFF_TIMEOUT_MS,
+    });
+    if (!result)
+        return [];
+    return result.hunks.map(_ => ({ ..._, lines: _.lines.map(unescapeFromDiff) }));
+}

package/dist/engineSessionParam.d.ts

@@ -0,0 +1,7 @@
+/** 当前会话的 session 参数值;undefined = 两源都缺席(动态 import 未落地的头几毫秒)——
+ *  调用方此时不带参(legacy 面软拍放行;强制面 404 自回落,下次重试自然带上)。 */
+export declare function engineSessionParam(): string | undefined;
+/** spread 便捷形:`{ ...engineSessionParamSpread() }` → `{ session: '<sid>' }` 或 `{}`。 */
+export declare function engineSessionParamSpread(): {
+    session?: string;
+};

package/dist/engineSessionParam.js

@@ -0,0 +1,35 @@
+/**
+ * engineSessionParam — durable run 面 `?session=` 参数的统一派生([1501]§三,server 1.246 起
+ * legacy 八面软拍纪律:带了且不匹配=404,没带=warn-once 放行,二拍将把「没带」也 404;新面
+ * A/B(taskOutput/taskStop)与 subagentOutput 则出生即强制)。
+ *
+ * 取值语义 = run 绑定的会话(本壳所有 durable 动词的目标 run 都是本会话自有 run,见扩散面复审
+ * 镜头二 W-A:寻址 id 逐跳自有,T13 不变量保证会话 id turn 内不漂移)。优先级与
+ * fleetClient.effectiveScopeSessionId() / engineSubagentOutput 同源:引擎捕获值
+ * (getLiveSessionId,首轮 done 回填的权威值)优先,未捕获时退壳 boot-time getSessionId()
+ * (SB-5:同命名空间,引擎首轮认养壳自报 id)。动态 import 姿势同两处先例,避免把
+ * bootstrap/state 重图拖进静态依赖。
+ *
+ * 🔴 [1501] 空串陷阱:`?session=`(空值)按「带了且不匹配」处理=404 —— 本 helper 恒不返回
+ * 空串:要么真值要么 undefined(调用方 spread 姿势 `...(s ? { session: s } : {})`)。
+ */
+import { getLiveSessionId } from './liveSessionStore.js';
+let shellSessionIdFn;
+void import('../bootstrap/state.js')
+    .then(m => {
+    shellSessionIdFn = m.getSessionId;
+})
+    .catch(() => {
+    // 极端环境缺模块:退化为只用 getLiveSessionId(),与 fleetClient/engineSubagentOutput 同款容错
+});
+/** 当前会话的 session 参数值;undefined = 两源都缺席(动态 import 未落地的头几毫秒)——
+ *  调用方此时不带参(legacy 面软拍放行;强制面 404 自回落,下次重试自然带上)。 */
+export function engineSessionParam() {
+    const sid = getLiveSessionId() ?? shellSessionIdFn?.();
+    return typeof sid === 'string' && sid.length > 0 ? sid : undefined;
+}
+/** spread 便捷形:`{ ...engineSessionParamSpread() }` → `{ session: '<sid>' }` 或 `{}`。 */
+export function engineSessionParamSpread() {
+    const s = engineSessionParam();
+    return s ? { session: s } : {};
+}

package/dist/engineWireSdk.d.ts

@@ -27,7 +27,31 @@ export type WireAuthToken = string | {
 };
 /** loopback 判定(engineTarget.isLoopbackEngineUrl 逐字镜像;解析失败=非 loopback)。 */
 export declare function isLoopbackWireUrl(url: string): boolean;
-/** #118 三态凭证解析(resolveLiveAuthToken 纯半场镜像)。 */
+/**
+ * §8-2 定谳的**唯一**凭证解析口(B4 收编)—— 11 处构造点的公共分母。
+ *
+ * 背景(设计稿 §8-2 + B4 实测):壳里今天是 **2 份三态解析**(`engineTarget.resolveLiveAuthToken`
+ * 产品半场 + 本包 `wireAuthTokenFor` 纯半场,后者头注自述是前者的「逐字镜像」⇒ 两份必然漂移)
+ * 外加 **11 处 `new AgentClient` 直造**,其中 7 处根本不走任何解析口,直接手写
+ * `token ?? { mode:'loopback-unauthed' }` —— 那一形**丢了 'anon' 那一态**:非 loopback 且无 token
+ * 时它给的是 loopback-unauthed(出站零 Authorization 头),而三态解析给 'anon'。对 fail-closed
+ * worker 两者都是 401,但对 **owner-gated 路由**不是同一回事,所以这是真分歧不是等价写法。
+ *
+ * 🔴 **env 缺省留在端上**:`resolveLiveAuthToken` 的第二参缺省是 `process.env.SEMA_LIVE_TOKEN`,
+ * 那一半**绝不进包**(本包零 `process.env` —— portability 门盯着)。壳侧 shim 保留缺省参即可:
+ * `resolveLiveAuthToken(u, t = process.env.SEMA_LIVE_TOKEN) => resolveWireAuth(u, t)`。
+ *
+ * 三态(#118):token 有 ⇒ 原样 Bearer;无 token ∧ loopback ⇒ `{mode:'loopback-unauthed'}`
+ * (出站零 Authorization 头,绝不伪造);无 token ∧ 非 loopback ⇒ `'anon'`(fail-closed 换诚实 401)。
+ * `baseUrl` 允许 undefined(= `resolveLiveAuthToken` 的签名超集,本地自 spawn 态)⇒ 'anon'。
+ */
+export declare function resolveWireAuth(baseUrl: string | undefined, token?: string): WireAuthToken;
+/**
+ * #118 三态凭证解析(旧名,B2 引入)。
+ * B4 起是 `resolveWireAuth` 的**别名**(baseUrl 必填的窄签名);两者行为逐字相同,保留是为了
+ * 壳侧既有 import 零改动 —— 不设代际让位([clean-cut-no-legacy-compat] 只约束**行为面**硬切,
+ * 同一函数的两个名字不是两套行为)。新代码一律用 `resolveWireAuth`。
+ */
 export declare function wireAuthTokenFor(baseUrl: string, token?: string): WireAuthToken;
 export type EngineWireClientConfig = {
     baseUrl: string;

package/dist/engineWireSdk.js

@@ -32,14 +32,40 @@ export function isLoopbackWireUrl(url) {
         return false;
     }
 }
-/** #118 三态凭证解析(resolveLiveAuthToken 纯半场镜像)。 */
-export function wireAuthTokenFor(baseUrl, token) {
+/**
+ * §8-2 定谳的**唯一**凭证解析口(B4 收编)—— 11 处构造点的公共分母。
+ *
+ * 背景(设计稿 §8-2 + B4 实测):壳里今天是 **2 份三态解析**(`engineTarget.resolveLiveAuthToken`
+ * 产品半场 + 本包 `wireAuthTokenFor` 纯半场,后者头注自述是前者的「逐字镜像」⇒ 两份必然漂移)
+ * 外加 **11 处 `new AgentClient` 直造**,其中 7 处根本不走任何解析口,直接手写
+ * `token ?? { mode:'loopback-unauthed' }` —— 那一形**丢了 'anon' 那一态**:非 loopback 且无 token
+ * 时它给的是 loopback-unauthed(出站零 Authorization 头),而三态解析给 'anon'。对 fail-closed
+ * worker 两者都是 401,但对 **owner-gated 路由**不是同一回事,所以这是真分歧不是等价写法。
+ *
+ * 🔴 **env 缺省留在端上**:`resolveLiveAuthToken` 的第二参缺省是 `process.env.SEMA_LIVE_TOKEN`,
+ * 那一半**绝不进包**(本包零 `process.env` —— portability 门盯着)。壳侧 shim 保留缺省参即可:
+ * `resolveLiveAuthToken(u, t = process.env.SEMA_LIVE_TOKEN) => resolveWireAuth(u, t)`。
+ *
+ * 三态(#118):token 有 ⇒ 原样 Bearer;无 token ∧ loopback ⇒ `{mode:'loopback-unauthed'}`
+ * (出站零 Authorization 头,绝不伪造);无 token ∧ 非 loopback ⇒ `'anon'`(fail-closed 换诚实 401)。
+ * `baseUrl` 允许 undefined(= `resolveLiveAuthToken` 的签名超集,本地自 spawn 态)⇒ 'anon'。
+ */
+export function resolveWireAuth(baseUrl, token) {
     if (token)
         return token;
-    if (isLoopbackWireUrl(baseUrl))
+    if (baseUrl !== undefined && isLoopbackWireUrl(baseUrl))
         return { mode: 'loopback-unauthed' };
     return 'anon';
 }
+/**
+ * #118 三态凭证解析(旧名,B2 引入)。
+ * B4 起是 `resolveWireAuth` 的**别名**(baseUrl 必填的窄签名);两者行为逐字相同,保留是为了
+ * 壳侧既有 import 零改动 —— 不设代际让位([clean-cut-no-legacy-compat] 只约束**行为面**硬切,
+ * 同一函数的两个名字不是两套行为)。新代码一律用 `resolveWireAuth`。
+ */
+export function wireAuthTokenFor(baseUrl, token) {
+    return resolveWireAuth(baseUrl, token);
+}
 /**
  * 构造一个引擎 wire 用 AgentClient。null = 构造失败(SDK fail-closed 拒绝——不该发生:
  * wireAuthTokenFor 恒给合法形;防御性 fail-soft,调用方按各自离线/探测失败路径处理)。
@@ -48,7 +74,7 @@ export function makeEngineWireClient(cfg) {
     try {
         return new AgentClient({
             baseUrl: cfg.baseUrl,
-            authToken: wireAuthTokenFor(cfg.baseUrl, cfg.token),
+            authToken: resolveWireAuth(cfg.baseUrl, cfg.token),
             principal: cfg.principal ?? 'anon:shell-live',
             ...(cfg.timeoutMs !== undefined ? { timeoutMs: cfg.timeoutMs } : {}),
             maxRetries: cfg.maxRetries ?? 0,

package/dist/finalVerifyWire.d.ts

@@ -0,0 +1,74 @@
+/**
+ * src/sema/finalVerifyWire.ts — headless `-p` finalVerification wire (TB2.0 反馈批 A · P1-1, 2026-07-15):
+ * stamp the ENGINE-EXISTING `TaskRequest.finalVerification` field on the headless `-p` path, DEFAULT ON.
+ *
+ * WHY: TB2.0 无人值守回归里 14/19 题 agent 自认完成判 0(写完不验/即兴自测即收尾)。引擎的
+ * finalVerification stop-gate(core runtask.js:1429-1493 —— 最多追加 2 条 '[final verification]'
+ * system-reminder,wroteThisRun && 非 structured-output && 未贴 maxTurns 才触发)+ server wire
+ * (http/server.js:3711 校验 / main.js:1383 转发)早已在线,壳侧从未 stamp——本模块补上这最后一段 wire。
+ *
+ * PRECEDENCE(off 优先,任何一条命中即不 stamp;否则默认 true):
+ *  a) `--no-final-verify` flag                         → off(一键回上游 2.1.207 严格对齐态:上游
+ *     `-p` 全文 0 处 final verification,默认开属超集;上游对应扩展点是 Stop hook)。
+ *  b) `SEMA_HEADLESS_FINAL_VERIFY` env('false'/'0')  → off。settings.json `env` 块 → 1a-envseed →
+ *     process.env,其它 wire 配置(SEMA_HEADLESS_SCENARIO 等)同一车道。
+ *  c) 用户配置了 Stop hook(settings hooks.Stop,经 hooksForWire 投影)→ off【对抗轮硬性 amendment】:
+ *     引擎 finalVerification 分支在 Stop hook 查询之前 return(runtask.js:1430-1443),默认开会把
+ *     用户 Stop hook 延迟至多 2 turn——对上游迁移来的 hook 用户是真行为变化,故有 Stop hook 即让位。
+ *  d) 都没有                                           → true(TB 默认态吃满终验闸杠杆)。
+ *
+ * LIVE-GATE:与 scenarioWire 同款——调用点(seamQueryEngine.ask)以 SEMA_LIVE_BASEURL 为门,
+ * mock/pty fixture 车道永不 stamp 该字段(离线投影字节等价)。
+ *
+ * 语义澄清(分诊报告):finalVerification 是同会话 stop-gate 追加,不是独立上下文 verifier;
+ * 纯读任务(wroteThisRun gate)与 structured-output 任务被 core 自身豁免,回归面天然收窄。
+ */
+import type { SemaSettings } from '@sema-agent/sdk';
+import { type EnvLike } from './hostEnv.js';
+/**
+ * B5:`hooksWireCaps` 的宿主耦合半场(settings 三层合并 + trust 门)还没搬,但这个**纯类型**
+ * 先落本包 —— 它就是 SDK 的 `settings.hooks`,与 hooksWireCaps 无耦合。
+ * 🔴 hooksWireCaps 后续进包时 **import 本条**,别再定义第二份(两份类型 = 漂移温床)。
+ */
+export type WireHooksConfig = NonNullable<SemaSettings['hooks']>;
+/** Settings-lane env knob(settings.json `env` 块 → 1a-envseed → process.env)。'false'/'0' = off。 */
+export declare const HEADLESS_FINAL_VERIFY_ENV = "SEMA_HEADLESS_FINAL_VERIFY";
+/**
+ * Parse `--no-final-verify` out of an argv slice(everything before a bare `--` — positionals are
+ * never flags,scenarioWire 同款纪律)。Boolean flag,无值形态,重复无害。
+ */
+export declare function parseNoFinalVerifyArgv(argv: string[]): boolean;
+/**
+ * The settings-lane off-switch:`SEMA_HEADLESS_FINAL_VERIFY` = 'false' or '0'(case-insensitive)
+ * disables the stamp。其它任何值(含空串/'true'/typo)= 默认态 on——fail-soft:一个 settings typo
+ * 只会落回默认开,绝不 brick 任何 run(scenarioWire 的 settings-lane 纪律)。
+ */
+export declare function headlessFinalVerifyDisabledByEnv(env?: EnvLike): boolean;
+/**
+ * 用户 Stop hook 在场判定:hooksForWire() 投影(policy→user→project→local 合并、trust/managed 门后)
+ * 里 `Stop` 事件带 ≥1 个 matcher 组即认定。判定输入用 wire 投影而非裸 settings——被 trust/
+ * disableAllHooks 门掉的 Stop hook 引擎侧同样不会 fire,不构成让位理由。
+ */
+export declare function hasUserStopHook(wireHooks: WireHooksConfig | undefined): boolean;
+/**
+ * Resolve the finalVerification stamp for a headless `-p` submit:默认 true;
+ * `--no-final-verify` flag / SEMA_HEADLESS_FINAL_VERIFY=false|0 / 用户 Stop hook 在场 → false。
+ * 调用点必须 live-gate(SEMA_LIVE_BASEURL)——mock/offline 形状不变。
+ */
+export declare function resolveHeadlessFinalVerify(argv: string[], env?: EnvLike, wireHooks?: WireHooksConfig): boolean;
+/**
+ * #106 裁 B(clay 2026-07-26):让位维持 + 诚实告知。detail 形暴露 off 原因供调用点分诊 ——
+ * flag/env 关闭是用户显式意愿(不聒噪);`stop-hook` 让位是用户**没显式要求**的关闭
+ * (Stop hook 可能来自 /goal 自注册或 settings hook),必须告知(修前静默,用户不知道自己
+ * 失去了终验)。方向注记:finalVerification 后续默认关(CC Stop hook 机制同,不叠超集)——
+ * 见记忆 final-verification-direction;届时本函数的默认臂翻转,detail 形不动。
+ */
+export declare function resolveHeadlessFinalVerifyDetail(argv: string[], env?: EnvLike, wireHooks?: WireHooksConfig): {
+    on: boolean;
+    offReason?: 'flag' | 'env' | 'stop-hook';
+};
+/**
+ * stop-hook 让位的告知文案(单一措辞源;stderr 一行)。措辞纪律与 hook_notice 同族:
+ * 「让位/接管」向,绝不写「守卫失效」向 —— 后者会让用户以为链路坏了。
+ */
+export declare const FINAL_VERIFY_YIELD_NOTICE = "final verification is off for this run \u2014 a Stop hook is active and takes over end-of-turn gating (it would otherwise be delayed by up to 2 turns)";

package/dist/finalVerifyWire.js

@@ -0,0 +1,63 @@
+import { hostEnv } from './hostEnv.js';
+/** Settings-lane env knob(settings.json `env` 块 → 1a-envseed → process.env)。'false'/'0' = off。 */
+export const HEADLESS_FINAL_VERIFY_ENV = 'SEMA_HEADLESS_FINAL_VERIFY';
+/**
+ * Parse `--no-final-verify` out of an argv slice(everything before a bare `--` — positionals are
+ * never flags,scenarioWire 同款纪律)。Boolean flag,无值形态,重复无害。
+ */
+export function parseNoFinalVerifyArgv(argv) {
+    for (const a of argv) {
+        if (a === '--')
+            break; // positionals — never flags
+        if (a === '--no-final-verify')
+            return true;
+    }
+    return false;
+}
+/**
+ * The settings-lane off-switch:`SEMA_HEADLESS_FINAL_VERIFY` = 'false' or '0'(case-insensitive)
+ * disables the stamp。其它任何值(含空串/'true'/typo)= 默认态 on——fail-soft:一个 settings typo
+ * 只会落回默认开,绝不 brick 任何 run(scenarioWire 的 settings-lane 纪律)。
+ */
+export function headlessFinalVerifyDisabledByEnv(env = hostEnv()) {
+    const v = env[HEADLESS_FINAL_VERIFY_ENV]?.trim().toLowerCase();
+    return v === 'false' || v === '0';
+}
+/**
+ * 用户 Stop hook 在场判定:hooksForWire() 投影(policy→user→project→local 合并、trust/managed 门后)
+ * 里 `Stop` 事件带 ≥1 个 matcher 组即认定。判定输入用 wire 投影而非裸 settings——被 trust/
+ * disableAllHooks 门掉的 Stop hook 引擎侧同样不会 fire,不构成让位理由。
+ */
+export function hasUserStopHook(wireHooks) {
+    const groups = wireHooks?.['Stop'];
+    return Array.isArray(groups) && groups.length > 0;
+}
+/**
+ * Resolve the finalVerification stamp for a headless `-p` submit:默认 true;
+ * `--no-final-verify` flag / SEMA_HEADLESS_FINAL_VERIFY=false|0 / 用户 Stop hook 在场 → false。
+ * 调用点必须 live-gate(SEMA_LIVE_BASEURL)——mock/offline 形状不变。
+ */
+export function resolveHeadlessFinalVerify(argv, env = hostEnv(), wireHooks) {
+    return resolveHeadlessFinalVerifyDetail(argv, env, wireHooks).on;
+}
+/**
+ * #106 裁 B(clay 2026-07-26):让位维持 + 诚实告知。detail 形暴露 off 原因供调用点分诊 ——
+ * flag/env 关闭是用户显式意愿(不聒噪);`stop-hook` 让位是用户**没显式要求**的关闭
+ * (Stop hook 可能来自 /goal 自注册或 settings hook),必须告知(修前静默,用户不知道自己
+ * 失去了终验)。方向注记:finalVerification 后续默认关(CC Stop hook 机制同,不叠超集)——
+ * 见记忆 final-verification-direction;届时本函数的默认臂翻转,detail 形不动。
+ */
+export function resolveHeadlessFinalVerifyDetail(argv, env = hostEnv(), wireHooks) {
+    if (parseNoFinalVerifyArgv(argv))
+        return { on: false, offReason: 'flag' };
+    if (headlessFinalVerifyDisabledByEnv(env))
+        return { on: false, offReason: 'env' };
+    if (hasUserStopHook(wireHooks))
+        return { on: false, offReason: 'stop-hook' };
+    return { on: true };
+}
+/**
+ * stop-hook 让位的告知文案(单一措辞源;stderr 一行)。措辞纪律与 hook_notice 同族:
+ * 「让位/接管」向,绝不写「守卫失效」向 —— 后者会让用户以为链路坏了。
+ */
+export const FINAL_VERIFY_YIELD_NOTICE = 'final verification is off for this run — a Stop hook is active and takes over end-of-turn gating (it would otherwise be delayed by up to 2 turns)';

package/dist/headlessPermissionModeWire.d.ts

@@ -0,0 +1,55 @@
+/**
+ * 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 规则:
+ *     · flag 来源:非 default 的 wire 词直接 stamp(auto 自分类器批3 起入表);`default` 不 stamp
+ *       (= 今天 flag 的实际效果,零行为变化);wire 词表外的 flag 值(dontAsk/manual…是壳内部
+ *       模式,server 不认)不 stamp。
+ *     · env 来源:五词全部显式 stamp(含 `default`——env 是"显式垫层"旋钮,设了就是要显式语义,
+ *       不再依赖 server absent-mode 缺省解释;server 1.191 对显式 "default" 走 manual ask 门解释)。
+ *   车道纪律:本模块只被 seamQueryEngine.ask(headless `-p`)import;交互 REPL(seamQuery)一根毛
+ *   不动——单测有 source-level lane proof(detachWire 同款)。
+ */
+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";
+/** wire 词表(permissionWireCaps.PermissionMode 的运行时镜像;大小写敏感——与 CC flag choices 一致)。
+ *  'auto'(分类器批3,[907]):server ≥1.209 五模式表认;老 server coerce 未知词 → "default" 只紧不松。 */
+export declare const HEADLESS_PERMISSION_WIRE_MODES: readonly PermissionMode[];
+export type HeadlessPermissionResolution = {
+    /** 直接展开进 TaskRequest 的字段({} = 不 stamp,现状 absent-mode)。 */
+    fields: PermissionModeField;
+    source: 'flag' | 'env' | 'absent';
+    /** 非法 env 值的告警文案(调用层一次性打 stderr)。 */
+    warning?: string;
+};
+/**
+ * argv 里的 `--permission-mode <v>` / `--permission-mode=<v>`(后者/后出现者赢,commander 同语义)与
+ * `--dangerously-skip-permissions`(= bypassPermissions;`--permission-mode` 在场时让位)。
+ * 返回 undefined = flag 车道未显式表态。
+ */
+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;