@sema-agent/client-core 0.53.0 → 0.55.0

package/dist/toolResult.js

@@ -117,6 +117,14 @@ export const STRUCTURED_DETAIL_TYPES = new Set([
     // 病根仍是对账物代际差:门锚本仓 devDep core,devDep 停 5.20.0 时该词还没铸 ⇒ 门恒绿。
     // 修 = devDep 升 ^5.43.0(门当场翻红显出漂移)+ 补词,与 A-004.5 那批同一条路。
     'read_path_denied',
+    // ── core 7.3.0 跟车一词(B-003 批,2026-09-05;engine-vocab ⑤ 段对 7.3.1 实装物直证)──────────
+    // 🔴 **不是本批点名的件,是抬对账物时族扫捞出来的存量漏词**([same-shape-residue-constitution]):
+    //    本批为了让 G2-b 对 `waiting_first_token` 有判别力,把 devDep core 从 ^7.1.0 抬到 ~7.3.0;
+    //    门当场翻红,红文逐字:「core 7.3.1:43 项 / 本包 42 项;漏:list-agents」。
+    //    `list-agents` = ListAgents 工具的结构化卡(core `dist/agents/list-agents-tool.js` 铸点,
+    //    并已登记在 `dist/core/runner/tool-output-projection.js:67` 的 `CC_DETAIL_TYPES` 里)。
+    //    病根与 5.20 / 5.43 两次逐字同族:词漏了不会响,只会让那一类卡**永远退回正则解模型面文本**。
+    'list-agents',
 ]);
 // 🔴 同批**删三词**(core 5.10.0 BREAKING「幽灵卡」清仓):`multiedit` / `memory-saved` /
 //    `memory-recall` —— 全树零铸点(MultiEdit/批量重放铸的是 `type:"edit"` 带 `edits[]`;core

package/docs/INTEGRATION-CLIENTS.md

@@ -15,15 +15,15 @@
 
 ## §0 版本锚与重扫纪律
 
-### 0a. 版本锚(2026-09-04)
+### 0a. 版本锚(2026-09-05)
 
 | 项 | 值 | 真源 |
 |---|---|---|
-| 本包 | `@sema-agent/client-core` **0.53.0**(工作树**未发**;npm 最新 = **0.52.0**。L-93 那一批进 `CHANGELOG.md` 的 `## 0.53.0(未发布)` 段,冻结账已按两阶段协议插 `pending` 行) | `package.json` `version` |
+| 本包 | `@sema-agent/client-core` **0.55.0**(工作树**未发**;npm 最新 = **0.54.0**。B-003 `waiting_first_token` 那一批进 `CHANGELOG.md` 的 `## 0.55.0(2026-09-05)` 段,冻结账已按两阶段协议插 `pending` 行) | `package.json` `version` |
 | peer:wire 契约 | `@sema-agent/sdk` **>=7.4.0**(value-level,非 type-only;0.48.0 抬版,四条硬理由见 `CHANGELOG.md` 0.48.0 段末的地板影响面账) | `package.json` `peerDependencies` |
 | peer:会话词汇表 | `@sema-agent/agent-types` **>=0.2.0**(type-only,零运行时) | 同上 |
 | runtime dep | `diff` ^9.0.0(**唯一**一条;portability 门按**等值**钉死) | `package.json` `dependencies` |
-| 公开导出面 | **805** 个运行期符号(+ 41 个测试钩;= 工作树当下的值 —— 已发的 `0.51.0` 是 **803**,再加 L-69⑨ 两件未发 additive 导出;`0.49.0` 是 **795**,再加 S-81 五件未发 additive 导出;`0.48.0` 是 **794**,npm `0.47.0` 是 **790**,`0.46.0` 是 **787**,`0.44.0` 是 **783**,`0.43.1`/`0.43.0` 是 **776**,`0.42.0` 是 **771**,`0.41.0` 是 **767**,`0.39.0` 是 **766**,`0.38.0` 是 **764**;`0.37.0` 是 **753**,见 `CHANGELOG.md`) | `scripts/public-export-baseline.json` 的 `count` / `testHookCount` —— **别手抄进别处,以该文件为准** |
+| 公开导出面 | **815** 个运行期符号(+ 41 个测试钩;= 工作树当下的值 = 已发 `0.54.0`(design/385 十件 additive 含 `AUTHORITY_ENVELOPE_TAGS`);`0.52.0` 是 **805**(L-69⑨ 两件);`0.51.0` 是 **803**;`0.50.0` 是 **800**(S-81 五件);`0.49.0` 是 **795**;`0.48.0` 是 **794**;npm `0.47.0` 是 **790**,`0.46.0` 是 **787**,`0.44.0` 是 **783**,`0.43.1`/`0.43.0` 是 **776**,`0.42.0` 是 **771**,`0.41.0` 是 **767**,`0.39.0` 是 **766**,`0.38.0` 是 **764**;`0.37.0` 是 **753**,见 `CHANGELOG.md`) | `scripts/public-export-baseline.json` 的 `count` / `testHookCount` —— **别手抄进别处,以该文件为准** |
 | 常驻门 | 以 `scripts/gates-manifest.json` 的 `suites` 长度为准(**本档不抄这个数**) | `scripts/gates-manifest.json`;`npm test` 的名单等值门与它逐名对账 |
 | 沿革档 | 0.29.0 起建 `CHANGELOG.md`;更早批次记账在 `src/index.ts` 文件头 + `docs/REFACTOR-LEDGER.md` | — |
 
@@ -31,13 +31,11 @@
 (`readSessionMemoryStatus` / `classifyMemoryStatusFailure` / `readCaptureOptOut` / `readLastCapture`)
 在旧版上按名 import 会**在 ESM 实例化当场炸**(具名导出不存在)—— 提货前先抬依赖。
 装 ≤`0.48.0` 的端同理:`0.49.0` 的 `projectCrashConverged`(L-38,§12)在旧版上不存在。
-⚠️ **工作树里还有一批比 `0.49.0` 更晚的未发 additive 导出**(S-81,见 §13):
-`classifySelfOrchestrationRefusal` / `stripSelfOrchestrationIntent` / `projectWorkflowsGate` /
-`SELF_ORCHESTRATION_RETRY_WITHOUT` / `CAPABILITY_SELF_ORCHESTRATION_REQUIRED`
-(+ **四个** type-only 形 `SelfOrchestrationRefusal` / `SelfOrchestrationDenialReason` /
-`WorkflowsGateProjection` / `WorkflowsGateUnknownDenial`)。它们随下一个版本段发出;
-在此之前按名 import 会在 ESM 实例化当场炸 —— 提货前先抬依赖。
-(L-38 的 `projectCrashConverged` 已随 `0.49.0` 发出,不再是未发件。)
+装 ≤`0.49.0` 的端同理:`0.50.0` 的 S-81 五件(`classifySelfOrchestrationRefusal` / `stripSelfOrchestrationIntent` /
+`projectWorkflowsGate` / `SELF_ORCHESTRATION_RETRY_WITHOUT` / `CAPABILITY_SELF_ORCHESTRATION_REQUIRED`
++ **四个** type-only 形 `SelfOrchestrationRefusal` / `SelfOrchestrationDenialReason` / `WorkflowsGateProjection` / `WorkflowsGateUnknownDenial`,§13)、
+装 ≤`0.53.0` 的端同理:`0.54.0` 的 design/385 十件(§17)—— 在旧版上按名 import 会在 ESM 实例化当场炸,提货前先抬依赖。
+(「未发」告示按「发出即退场」约定退场:本档只列**已发版本**的下限,不再预告工作树里的未发件。)
 🔴 **0.48.0 还抬了 peer 地板**(`@sema-agent/sdk >=7.4.0`),这是本版**唯一**的非 additive 面:
 端装 <7.4.0 的 SDK 会看到 peer 警告(运行期不因此变化)。同一条对 0.47.0 那 **3 个 additive 导出**
 成立(`planInteractiveHalt` / `RUN_LEVEL_STOP_ERROR_CODES` / `readDecideCurrentPending`)。同一条对 0.38.0 那 11 个
@@ -106,14 +104,14 @@ SDK 核对「本包 import 的每个值级符号仍然导出」「`TaskStats.cos
   `--platform=browser` **真打包**看守,不是靠约定。
 - 宿主能力一律**经端口注入**(`installHost({...})`,见 §5),库自己**绝不** `require('fs')`、
   绝不 `process.env` 直读(env 走 `hostEnv()`)、绝不全局 `fetch`(目录线上腿走注入的 `CatalogFetchJson`)。
-- 闭包棘轮(零松量,逐块记账在各上限常量头注):内核 7 文件 / A 层 23 / index 119。
+- 闭包棘轮(零松量,逐块记账在各上限常量头注):内核 7 文件 / A 层 24 / index 142(0.54.0 `peerFrames.ts` 入 A 层与 index 各 +1)。
 - **实现锚**:`scripts/run-client-core-portability-test.mjs`、`src/hostEnv.ts`、`src/host.ts`。
 
 ---
 
 ## §2 公共导出面地图(按域)
 
-> 全集真源 = `scripts/public-export-baseline.json` 的 `names`(**805** 项)。
+> 全集真源 = `scripts/public-export-baseline.json` 的 `names`(**815** 项)。
 > 本节**不逐名抄**,只给「域 → 承重导出 → 用途 → 实现锚」。承重导出 = 一个端为了让这个域干活
 > **必须**直接调到的那几个符号;其余是它们的类型、变体与辅助位。
 > 单一入口:`import { … } from '@sema-agent/client-core'`(`exports` 只有 `.` 一个;
@@ -123,7 +121,7 @@ SDK 核对「本包 import 的每个值级符号仍然导出」「`TaskStats.cos
 
 `public-export-baseline.json` 由 **`dist/index.js` 的运行期导出**生成(生成口径自述见
 `scripts/run-client-core-typeshape-test.mjs`,双向精确集合门在 `scripts/run-public-surface-test.mjs`)。
-实测:805 项 **100% 是运行期导出,零 type-only**。
+实测:815 项 **100% 是运行期导出,零 type-only**。
 
 **推论(端必须知道)**:
 - barrel 导出的**类型**面比 707 大得多,且**不被这道门看守** —— `AdapterContext` / `SeamEvent` /
@@ -137,12 +135,12 @@ SDK 核对「本包 import 的每个值级符号仍然导出」「`TaskStats.cos
   `WorkflowsGateUnknownDenial` 四形**不在**基线里,`src/selfOrchestrationDenial.ts` 对基线贡献
   **4** 项运行期导出(三个函数 + `SELF_ORCHESTRATION_RETRY_WITHOUT`)。
 
-805 项的内部构成(帮助端估读表大小):**238** 项是 `SCREAMING_SNAKE` 常量数据表/词汇表
+815 项的内部构成(帮助端估读表大小):**244** 项是 `SCREAMING_SNAKE` 常量数据表/词汇表
 (矩阵、键集、env 名、锚串)而非可调用物;**5** 项是 PascalCase 运行期值
 (`ControlRouter` / `ControlSafetyError` / `HitlBridge` / `HitlSafetyError` / `DecideTransportRetryExhaustedError`);
 **41** 项是 `*For(sessionKey, …)` 的 per-session 变体(§6;其中 `engineNamespaceKeyFor` 是命名巧合 —— 参数是 baseUrl 不是 sessionKey,见域 14)。
 
-### 2b. 域图(16 域,逐域计数之和 = 805)
+### 2b. 域图(16 域,逐域计数之和 = 815)
 
 | # | 域 | 名数 | 承重导出 | 用途 | 实现锚 |
 |---|---|---|---|---|---|
@@ -152,7 +150,7 @@ SDK 核对「本包 import 的每个值级符号仍然导出」「`TaskStats.cos
 | 4 | **子代 wire + 面板侧信道台账** | 84 | `tailEngineSubagent` · `installSubagentActivitySink` · `installSubagentTailMetaSink`(#280 件2:tail meta 帧发布口,`contentFrames` 判别位载体)· `stopEngineTask` + `classifyTaskStopConflict` · `fetchEngineSubagentReport` · `steerEngineSubagent`(0.32.0 未发布 #280 件A:additive 第三参 `childTaskId` —— 端有行上下文时**应当**传,传了就走「台账优先 / 缺席即诚实缺席 + `noteBgOwnerAbsence` 留痕」的 Q3 口径,与 tail·taskOutput·subagentOutput 三腿同姿势、与孪生 resume 腿共用同一个 `resolveOwnerRunId` 判据;**不传**则逐字维持旧行为=回落在飞 run)· `resumeSettledSubagent` + `resolveSubagentResumeContext` + `resolveOwnerRunId` + `classifySubagentResumeFailure` + `subagentResumeAvailable`(#242 批 2 A-028.7:resume 判定半场上收,与 steer 孪生同居;取址三态 = 台账有行用行值 / 指名了行但台账缺席则**诚实缺席绝不回落在飞 run** / 没指名行才回落。出路文案归端)· `recordSubagentOwnerFromProgress` + `getBgParentRunOwner`(A-028.6:「子代 → 宿主 run」**单表**,宿主 run 必须由持 stream-local 值的调用方显式传入,包内绝不从 `activeEngineRunId()` 推断)· `noteBgOwnerAbsence`(#242 批 3 [4000] Q3=B:tail/taskOutput·taskStop/subagentOutput 三腿台账缺席即诚实缺席**绝不回落在飞 run**,缺席 warn 留痕每 (腿,taskId) 一条)· `clearBgTerminalFacts`(#242 批 3 扫码修:复活=新周期,旧周期终态事实作废——fleetLedger 复活两腿按尾段清账,factsAccepted 方向核不再拿上周期终态当先例)· `auditRetainWithoutWake`([4000] Q5:引擎宣示 `subagentResume` + 本端在付 `retainSubagentSessions` + 端未实现 `wakeSubagent` ⇒ 响亮一条;`CLIENT_VERBS.wakeSubagent` 维持 fail-soft)· `subscribeSubagentContent` · `subscribeEngineAgentPanel` · `publishQuestionFrame` / `respondToQuestion` | 驱动与观测委派子代;经 module 级台账喂活体 agent/task 面板。全部**能力位 gate**(§5b) | `src/subagent/*.ts`、`src/subagentContentStore.ts`、`src/engineAgentPanelStore.ts`、`src/engineInlineTaskStats.ts`、`src/engineToolLabelStore.ts`、`src/liveQuestionStore.ts` |
 | 5 | **fleet 投影** | 46 | `createFleetLedger` · `projectTasks` · `projectWorkflows` · `projectFleetAgentRows` · `readEngineActiveBgTasks` · `FLEET_TASK_VIEW_KEYS` · `escapeDisplayControlChars`(不可见字符可见化,行标签/描述消毒的共享底座)· `wireCycleSeq` / `wireRetiredBy`(0.38.0 提货补投的 #261 §2 两位:代际号 = SendMessage 复活即 +1,**缺席 ≠ 第一代**;`retiredBy` 在场 = 这条终态是对账腿从 durable run 行投影出来的、**不是**发布方亲报 —— 幽灵行与正常收尾唯一的 wire 判据。两位都只在场才落键) | 老 `fleetClient` 那一刀的成品:**帧体归库、连接归端** —— 端持 SSE 连接,库做行投影 + 保留台账 | `src/fleet/fleetProjection.ts`、`src/fleet/fleetLedger.ts`、`src/fleetAgentPanelProjection.ts`、`src/fleetTaskDesc.ts` |
 | 6 | **请求装配(上行唯一构造口)** | 8 | `buildTaskRequest` · `REQUEST_FIELD_MATRIX` · `unregisteredRequestKeys` · `applyLiveRequestDefaults` · `taskNotificationToPrintFrame` | 两条车道(`interactive`/`print`)出站请求的**唯一**构造器;`unregisteredRequestKeys` 是可执行门 —— 端偷带一个未登记键上 wire 就红 | `src/request/taskRequest.ts`、`src/request/printNotification.ts` |
-| 7 | **通知与 outstanding 台账** | 41 | `installNotificationQueuePort` · `normalizeTaskNotification` · `taskNotificationDedupKeyFromWire` · `registerOutstandingBgTask` / `registerOutstandingWorkflowRun` · `notificationQueuePortMisses` · `subscribeOutstandingWorkflows` · `outstandingDeliverableWorkflowCount` | `task_notification` 归一 + 去重 + 投递进宿主命令队列的**一把闸**;`outstandingDeliverableWorkflowCount()` 是 headless `-p` 的**退出门** | `src/notifications.ts`(11 个 module 台账) |
+| 7 | **通知与 outstanding 台账** | 51 | `installNotificationQueuePort` · `normalizeTaskNotification` · `taskNotificationDedupKeyFromWire` · `registerOutstandingBgTask` / `registerOutstandingWorkflowRun` · `notificationQueuePortMisses` · `subscribeOutstandingWorkflows` · `outstandingDeliverableWorkflowCount` | `task_notification` 归一 + 去重 + 投递进宿主命令队列的**一把闸**;`outstandingDeliverableWorkflowCount()` 是 headless `-p` 的**退出门** · `classifyPeerNotification` / `renderPeerFrameTranscriptText` / `parsePeerFrameText` / `peerFrameDisplayName` + 三张闭集表(design/385,0.54.0:同一条 `task_notification` 车道上三条**引擎注入帧**的类型化投影 —— 判别位=载体在场而非 summary 文本,详见 §17) | `src/notifications.ts`(11 个 module 台账) |
 | 8 | **工具结果卡** | 25 | `structuredToToolUseResult` · `readAsyncLaunchedAgentReceipt` · `wireOutputToBody` · `parseModelFacingBash` · `getPatchFromContents` · `toolEndResultToUserFrame` · `flattenToolOutput` | 铸端要渲的 `tool_result` 卡体,含客户端 diff hunk(唯一 runtime dep 的用处) | `src/toolResult.ts`、`src/printToolResultFrame.ts`、`src/diff/patch.ts` |
 | 9 | **能力/旋钮 wire 门族** | 91 | `projectAgentsForWire` / `awaitTaskAgentsWire` · `hooksForWire` · `mcpConfigsToSpecs` · `ultracodeForRequest` · `resolveWebSearch` + `buildWebSearchEnv` · `attachmentsForRequest` · `projectEffectiveBody` · `classifySelfOrchestrationRefusal` / `stripSelfOrchestrationIntent` / `projectWorkflowsGate` / `SELF_ORCHESTRATION_RETRY_WITHOUT`(S-81,server 7.57.0:上面两条 stamp 腿的**背面** —— 半配置多租户形态下 server 把带 `selfOrchestration` / `settings.ultracode` 的提交 501 拒掉,判型/去键/caps 闸三处都是判定不是文案,详见 §13) | 逐功能的「引擎有没有这个能力 + 这个字段怎么上 wire」投影器,由 `buildTaskRequest` 组装。🔴 `hooksForWire()` 是 **fail-closed**:无 `SettingsPort` ⇒ 返回 `undefined`(信任门,不是取值) | 17 个 `src/*WireCaps.ts` + `src/scratchpadWireCaps.ts`、`src/hooksWireCaps.ts`、`src/goalStopHook.ts`、`src/websearch/searchProviderPresets.ts`、`src/selfOrchestrationDenial.ts`(S-81 拒绝判定层) |
 | 10 | **headless / 部署旋钮 wire** | 61 | `parseSandboxArgv` / `sandboxRequestFields` · `parseLimitsArgv` / `limitsForPrint` · `resolveHeadlessFinalVerify` · `resolveHeadlessPermissionMode` · `resolveHeadlessInteractiveTools` · `armDetachCancel` + `detachCancelArm` + `isDetachArmed` · `withHeadlessR1Reconnect` | `-p`/headless 车道的 env+argv 旋钮。🔴 `detachWire` 是**拆**的补偿:判定与 cancel-arm 台账在库,信号路径的裸 fetch 留宿主(`detachCancelArm()` 是取件口) | `src/sandboxWire.ts`、`scenarioWire.ts`、`finalVerifyWire.ts`、`limitsWire.ts`、`interactiveToolsWire.ts`、`headlessPermissionModeWire.ts`、`headlessReconnectWire.ts`、`detachWire.ts` |
@@ -2592,3 +2590,205 @@ interface ActiveRunSelfHealDeps {
 `offerStaleParkChoice` / `staleParkArm` / `cancelAndConfirmRelease` / 五个新 kind 的文案臂)。
 **常驻门**:`scripts/run-selfheal-reopen-test.mjs`(G11 段,含「该位缺席 ⇒ 逐字旧结局且零 cancel」负控)、
 `scripts/run-terminal-identity-copy-test.mjs`(G2 段:新 kind 的注入形与处置分类)。
+
+
+## §17 🆕 design/385 三条引擎注入车道的类型化投影(0.54.0;cli L-61② / L-87 5a①5a②)
+
+### 17a. 修的是哪一形
+
+引擎把三类**根本不是同一种东西**的载荷塞进同一条 `task_notification` 车道,而 core 对这三类
+**不套** `<task-notification>` 壳(`core/task-notification.ts::renderTaskNotificationXml` 头三个分支
+按这个顺序判):
+
+| 载体键(`TaskNotificationPayload` 上) | 出处 | 模型面 |
+|---|---|---|
+| `agentMessage: {from, body}` | §1.4 d1 —— 同进程子代 `SendMessage("main")` 的 uplink | `<agent-message from="…">` + peer 纪律块 |
+| `crossSessionMessage: CrossSessionEnvelopeFields & {body}` | §4.1 —— 另一个会话的消息,从本会话自己的信箱 drain 出来 | `<cross-session-message from="…" from-session="…" from-name="…" from-mode="…">` + 跨会话纪律块 |
+| `crossSessionNotice: {kind, text}` | §4.4/§5.2 —— **本会话自己发出去**那条消息的回执 / `notify_when_idle` 的 idle 通知 | 一行纯文本(`[Cross-session delivery notice] …` / `[Cross-session idle notice] …`) |
+
+端此前照 `task_notification` 泛化卡渲 ⇒ 屏上是「后台任务完成」,而模型读到的是一条同事发来的话。
+
+### 17b. 端该怎么用(三步,端零字符串判定)
+
+```ts
+import { classifyPeerNotification, parsePeerFrameText, peerFrameDisplayName } from '@sema-agent/client-core'
+
+// ① 帧面(适配器内部已接;宿主自建管线才需要):原始 wire 载荷 → 投影 | null
+const frame = classifyPeerNotification(rawTaskNotificationPayload)
+
+// ② 文本面(端的消息组件只拿得到文本):转录行 → 投影 | null
+const projected = parsePeerFrameText(messageText)
+if (projected?.lane === 'agent_message') renderAgentMessageCard(peerFrameDisplayName(projected), projected.body)
+if (projected?.lane === 'cross_session_message') renderCollapsedPeerRow(peerFrameDisplayName(projected), projected.body)
+// ③ 通知车道没有标签,按普通文本行渲 —— 这就是 CC 形(无卡、无折叠、一行)
+```
+
+### 17c. 五条判定纪律(端不许自己重判)
+
+- 🔴 **判别位 = 类型化载体的在场,永远不是 `summary` 文本**。三条载体只有引擎的注入腿铸得出
+  (`ExternalNotificationInput` 是 `TaskNotificationPayload` 的**真子集** —— 外部 `notify()` 一个都
+  穿不上);而 `summary`/`result` 是任何一条通知都填的字段。判据落到文本上 ⇒ 任何一个后台任务
+  只要把 `<agent-message from="…">` 写进自己的 summary 就能在用户屏上冒充一条同事消息。
+- 🔴 **fail-closed 分两档**。必填位坏(`from` 空 / `body` 非串 / notice `kind` 不在闭集)⇒ 整帧返
+  `null` = 退泛化卡(诚实降级:用户仍看得见这条通知,只是没有专用形)。可选位坏(`fromMode` 写了
+  闭集外的词)⇒ **只丢那一位**:少一句注 vs 把一条同事消息从用户眼前拿走,不是同一个量级。
+- 🔴 **`_sema_provenance` 必须在场,且 `kind` 与载体车道相符**。缺席 / 读不出(非对象、访问器)/
+  矛盾,三形一律退泛化卡。**这一条 0.54.0 定稿时翻过一次面**:首版是「只否决不认证、缺席放行」,
+  理由「要求在场会让另两条车道在老引擎上恒死」被对抗复审证伪 —— 老引擎上那两条车道**连载体键都
+  没有**,判定根本走不到;而 core 契约明写 provenance「present exactly when the carrier is」,在跑的
+  7.2.0 就是同一处同时铸两者。要求在场对真载荷零代价,对畸形 / 半截注入 / 版本漂移则关上一道门。
+  🔴 判据是**四条等式 + 在场**:`kind` 与车道相符,且 `from`/`taskId`/`seq` 三位**必须在场**并分别
+  等于载体的 `from`、载荷的 `task_id`、载荷的 `seq`(core 的 `SemaProvenance` 把这三位全声明为必填,
+  三个铸点也都同址写下 ⇒「两侧都缺」不是合法兼容形,而是半截载荷)。只核 `kind` 拦得住半截载荷,拦不住**同 kind 的伪造** —— 载体署一个可信名字、
+  provenance 三位全对不上,屏上照样出现一条署着那个名字的消息。后三条**各有铸点直证**(uplink 腿与
+  跨会话 drain 腿都在同一个对象字面量里同值写下这几位),铸点一改由 cli 侧 wire 锚的同址探针当场
+  喊红 ⇒ 「等式失效」不会退化成一条静默死掉的车道。
+  ⚠️ 端若自建管线要注意:载荷那一边是 **snake** `task_id`、provenance 那一边是 **camel** `taskId`
+  —— 同一个量两个拼法,写混了等式恒不成立。
+- 🔴 **分支序**:三车道判定必须在「完成卡已入队」这类**完成通知专用**早退**之前**做。子代续跑时
+  复用同一个 taskId,它的合法 `agentMessage` 帧会在那种早退上被整条丢掉(零输出、去重账已记 ⇒
+  重放也补不回来)。**同因第二件**:peer 帧也不该写「这个 run 的完成已经被引擎注入过」那本跨通道账
+  —— 一条同事**消息**不是完成事件(三条 peer 铸点的 `status` 都是 `"event"`),写脏了它,子代自己
+  真正的空闲期完成通知随后会被补发通道整条丢掉。本包 0.54.0 的 `taskNotificationArm` 已按此两条修;
+  端若自建投影管线同理。
+  文本面同理:`parsePeerFrameText` 的 `ok` 只等于「形是规范的」,**不等于**「这条真是引擎注入的」
+  —— 文本面不存在身份权威(core §4.2 三层规则同一句话)。端拿它做**呈现**分派,不许拿它做任何
+  授权判断。
+- 🔴 **`parsePeerFrameText` 的三条硬边界**(端若自建管线必须同样成立):信封整串锚定;正文里出现
+  **未拆火**的同名标签 ⇒ 整条退 `null`(贪婪匹配会把「两封拼一起」读成一封、把「信封 + 尾随文本」
+  读成一封而尾随文本静默消失);拆火编码是**单射**(`unescape(escape(x)) === x` 对一切 x 成立,
+  连正文里原本就有的反斜杠一起数)—— core 的 `escapeEnvelopeTag` 是**单向**消毒、没有这条义务,
+  照抄过来会让 `<\agent-message>` 这类合法代码文本在往返之后变成一个真标签。
+- 🔴 **优先序照抄 core 的渲染腿**(agentMessage → crossSessionMessage → crossSessionNotice)。多载体
+  同在是矛盾载荷,但模型那一面**已经按 core 的顺序读过了**;端另立一套「矛盾就退泛化」会让屏上
+  那张卡与模型读到的帧对不上。
+- 🔴 **通知车道刻意不进 `parsePeerFrameText`**。它的转录行是一行没有标签的散文,要认它只能去锚
+  `[Cross-session …]` 前缀 —— 用户随手打一行同样的字就会被认成引擎通知。按普通文本行渲本来就是
+  CC 形。
+
+### 17d. 零行为差的边界
+
+三条载体一个都不在场的载荷(= 上游到货前的**全部**载荷)走的分支与 0.53.0 **逐字节等价**:
+`taskNotificationArm` 只换了转录行那一行的**文本来源**,去重键 / `bgshell_settle` / 面板 settle /
+module 台账一个都没动(它们判的是「哪个 task 的哪个状态」,与这条通知在模型面穿哪件外衣无关,
+跟着换会把三条独立的账搅成一本)。
+
+🔴 **边界的另一半(发包扫描 [high] 纠偏)**:载体**在场**时,`taskNotificationArm` 对**所有**宿主(含没接 `parsePeerFrameText`
+的老宿主 desktop/web-client)都把转录行文本换成信封形(`<agent-message …>…</agent-message>` / `<cross-session-message …>` /
+通知纯行),不再是 `<task-notification>` XML。这是**有意的**——那一行本来就是模型读到的帧,老宿主把它当普通 user 文本行渲
+正是 CC 形(CC 的 `<agent-message>` 就是一条 user 文本)。所以「零行为差」只对**载体缺席**的载荷成立;载体在场的老宿主差异=
+「泛化完成卡 → 一行原文」,不是回退。
+
+### 17e. 上游供给的诚实边界(本版新增的已知局限)
+
+`crossSessionMessage` / `crossSessionNotice` 两条载体在 **core 7.2.0** —— 即 cli `ENGINE_PIN 7.57.0`
+内嵌的那一版 —— 上**零铸点**(直证:`node_modules/@sema-agent/core/dist/**` 两词零命中)。本批是
+**消费半场先落地**,上游到货前这两条车道恒不触发。`agentMessage` 一条今天就到得了
+(core 7.2.0 `dist/agents/send-message-tool.js` 的 uplink 腿直证 `_sema_provenance: { kind: "agent_message" …`)。
+两个标签字面量已由 cli 侧的 wire 锚契约门(登记表里的 A-K24 条)对 core 真字节看着。
+
+**cli / web / desktop 认领**:cli 侧接点(消息组件三形)在本批同车;web / desktop **无需动作**
+(不调新导出 ⇒ 逐字节零行为差,只是这三条车道在它们那儿仍渲泛化卡)。
+**实现锚**:`src/peerFrames.ts`(`classifyPeerNotification` / `renderPeerFrameTranscriptText` /
+`parsePeerFrameText` / `peerFrameDisplayName` / 三张闭集表)、`src/adapt/arms.ts` 的通知臂。
+**常驻门**:`scripts/run-peer-frame-projection-test.mjs`(71 checks,含适配器级的两条台账回归)。
+
+## §18 🆕 `waiting_first_token` —— 等第一个 token 的相(0.55.0;core 7.3.0 #530 / server ≥7.58;cli B-003 / L-108①)
+
+### 18a. 修的是哪一形
+
+`BrainStatusPhase` 是**闭集**,而消费端对它有 `switch`。core 7.3.0 加了第七相
+`waiting_first_token`(首 token 看门狗已武装、第一个字还没到;等满 `WAITING_FIRST_TOKEN_AFTER_MS`
+= 30s 起每 30s 一帧,携 `elapsedMs` / `timeoutMs`;铸点 `core/dist/brain/stream-engine.js`
+的 `emitWaitFrame`)。0.54.0 及以前本包不认得它 ⇒ 落 `mapBrainStatusToRetry` 的 `default:` 臂
+被投成 `{kind:'error'}`。用户端两个面:
+
+| 引擎 | 用户看到 | 事实 |
+|---|---|---|
+| 7.57.0(core 7.2.0) | 什么都没有 | 相不存在 |
+| 7.58.0(core 7.3.1) | 一条**错误色**的 `API error` 行 | 模型已连上,正在生成前的静默;**一次尝试都没失败过** |
+
+病形 = 「上游闭集加员落 default 臂 ⇒ 新状态被渲成**最像的旧状态**」,与 #3004 修的 `recovered`
+(重试**成功**被渲成 `API error`)逐字同族。
+
+### 18b. 端该怎么用
+
+```ts
+import { mapBrainStatusToRetry, type RetryStatus } from '@sema-agent/client-core'
+
+const st = mapBrainStatusToRetry(brainStatusPayload, Date.now())
+if (st === null) return null                     // recovered:摘掉覆盖层
+if (st.kind === 'waiting') {                     // 🆕 0.55.0
+  // 非错误色。elapsedMs 缺席 ⇒ 不渲秒数(绝不折 0);timeoutMs 缺席 ⇒ 不渲「/ Ns」。
+  return renderWaitingRow({ elapsedMs: st.elapsedMs, timeoutMs: st.timeoutMs })
+}
+if (st.kind === 'stalled') return renderStalledRow(st)   // reconnecting:网络面
+return renderErrorRow(st)                                // 其余:重试/限流/熔断/放弃
+```
+
+三条**必须**照做的纪律:
+
+1. **不得拿 `deadline` 渲倒计时**。本相不带 `retryIn*`(core:它不宣告等待,它**观测**等待),
+   `deadline` 恒 = 映射时刻的 `nowMs`,是**兼容位**(见 18c),不是一个真的截止点。
+2. **不得拿 `timeoutMs` 当倒计时源**。它是这次等待的**天花板**(渲「45s of 120s」的分母),
+   拿它当「还要等多久」会渲出一个从不递减的数。
+3. **缺席禁折 0**。两位都可能缺席(旧 server 不发 / 未来相位铺开),缺席 = 不知道,不渲。
+
+### 18c. 🔴 老宿主:**结构形免动,穷尽形必须加一条 case**
+
+`waiting` 臂刻意是 `error` 臂的**结构超集**:它带 `deadline` / `attempt` / `maxRetries` /
+`errClass` / `retryAtMs` / `errorStatus` / `error{formatted:''}`,`terminal` 恒缺席。于是一个还没加
+`kind === 'waiting'` 分支的端,其 `if (kind==='stalled') … else …` 的 else 臂读到的一切与 0.54.0
+**逐位相同**,渲出的行也逐字节相同。
+
+**为什么不用「更干净」的瘦臂**:少了 `error` 这一位,结构形老宿主的 `status.error.rateLimits` 就是
+一次 TypeError —— 渲染路径裸抛 = 整屏崩,把「一行渲错」升级成「一屏全没」。加员制造崩渲是不可接受
+的代价;让未跟车的端**保持原样**才是加员的诚实形。
+
+🔴 **但结构超集救不了穷尽形消费者,这一条必须说清楚,不许含混成「无需动作」**(异源对抗复审
+[medium] 采纳):`switch (status.kind) { case 'stalled': …; case 'error': …; default: assertNever(status) }`
+这一形破的是**判别值**本身,不是形状 —— 补多少结构位都没用。后果两面:重新编译时报
+「`waiting` 不可赋给 `never`」(编译错,响亮,好);**已经编译好**的老产物拿到新 kind 会在
+default 臂**抛**(运行期,安静得多)。⇒ 对这一类消费方,0.55.0 是 **BREAKING**,发布帖必须点名。
+两形的事实各自钉在门里:`run-client-core-pure-test.mjs` G6-e ①(结构形零差异)/ ②(穷尽形真抛)
+/ ③(反空转:加员**前**同一个穷尽形消费者**不抛** ⇒ ② 的抛精确归因于多了一个判别值)。
+
+🔴 **第三形:不读 `kind` 的宿主**(0.55.0 发包扫描 [medium] 采,按实际消费者取来的分类):web-client 现状是把
+`retryStatus` 非空一律渲成既有错误行「Request failed · retrying (n/m)」,根本不看 `kind`。它在 waiting 相上
+渲的仍是那一行 —— 与 0.54.0 **逐字节相同**,所以不是回归;但用户面拿不到进度行,要接 §18b(读 `kind==='waiting'`
+渲 headline + `elapsedMs`/`timeoutMs`)才有真话。三形对照:结构形零差异 / 穷尽形 BREAKING / 不读 kind 形=旧行不变。
+
+判据不是一句承诺,是两道门(拿**本函数自己的 `default:` 臂**当活对照 —— 一个未知相走的正是加员前
+第七相走的那条臂 —— 两边在老宿主读得到的键上逐位相等才绿):
+`scripts/run-client-core-pure-test.mjs` G6-d(单元)/ `scripts/run-additive-key-passthrough-test.mjs`
+G5d(全链两段)。
+
+### 18d. `BrainStatus` 九键 → 十一键
+
+新增 `elapsedMs`(已经等了多久,ms)与 `timeoutMs`(这次等待的天花板,ms)。两位**进 `extra` 统一
+透传**,不按相位写特判 —— core 的不变式(「只在本相在场」)由 core 说,本层复述一遍就等于上游哪天
+把它铺到别的相时本层单方面剥键(`task_progress.model` / `retryAtMs` 两次存量的病根)。
+
+🔴 **族扫落点两处**:`adapter/downstream/eventToSdkMessage.ts` 的 `case 'status'`(wire → 内部臂)
+与 `adapt/arms.ts` 的 `retryStatusArm`(内部臂 → chrome 事件)。漏任一层,新相到端只剩空壳
+(kind 对了、秒数永远缺席)。
+
+### 18e. 端的措辞(sema 超集,非 CC parity)
+
+CC 2.1.250 语料**无同形提示行** —— `first token` / `firstToken` / `first_token` 的全部命中都是
+账号首 token 日期与流式计时**遥测**,无渲染面;同族里唯一的用户可见行是 `Waiting for API response`,
+而那是 `reconnecting` 相的既有行(「在等应答」≠「已连上、在等第一个字」)。⇒ 措辞按 [6386] / L-79②
+既定形 `Waiting for the model's first token · Ns [/ Ns]`,各端登记 divergence。
+
+**cli / web / desktop 认领**:cli 侧渲染臂在本批同车。web / desktop 按 18c **分两形**:
+消费形是**结构形**(`if (kind==='stalled') … else …`)⇒ 免动,逐字节零差异;
+消费形是**穷尽形**(`switch (kind)` + `default: assertNever`)⇒ **必须加一条 `waiting` case**,
+否则重新编译报「waiting 不可赋给 never」、已编译的老产物在 default 臂**抛**。
+跟车的正形都是加一条 `kind === 'waiting'` 臂,渲成**非错误色**的进度行。
+
+**实现锚**:`src/retryStatus.ts`(`RetryStatus` 的 `waiting` 臂 / `BRAIN_STATUS_PHASES` 七相 /
+`BRAIN_STATUS_PAYLOAD_KEYS` 十一键 / `mapBrainStatusToRetry` 的 `case 'waiting_first_token'`)、
+`src/adapt/arms.ts`、`src/adapter/downstream/eventToSdkMessage.ts`。
+**常驻门**:`scripts/run-client-core-pure-test.mjs` G6 组(相位→kind 全矩阵 / 缺席位不捏造 /
+老宿主零差异)、`scripts/run-additive-key-passthrough-test.mjs` G5 组(全链两段)、
+`scripts/run-engine-vocab-floor-test.mjs` G2-b/G2-c(对**实装 core** 逐词逐键等值)。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/client-core",
-  "version": "0.53.0",
+  "version": "0.55.0",
   "description": "Client-side session runtime shared by every sema human client (TUI / web / desktop): sema wire frames (AgentEvent) -> CC session vocabulary (SDKMessage) with dual-plane output (transcript/chrome), deterministic transcript ids, lane discipline as a type, and the notification/dedup ledgers. Every CC-skin shape is collected here so the wire itself stays neutral. Renamed from @sema-agent/wire-cc-adapter (0.1.x).",
   "license": "MIT",
   "type": "module",
@@ -35,7 +35,7 @@
   },
   "devDependencies": {
     "@sema-agent/agent-types": "^0.2.0",
-    "@sema-agent/core": "^7.1.0",
+    "@sema-agent/core": "~7.3.0",
     "@sema-agent/sdk": "^7.4.0",
     "esbuild": "^0.27.4",
     "typescript": "^6.0.2"