TokenRollAI · Disdjj · Sep 15, 2026 · Sep 15, 2026 · Sep 15, 2026 · Sep 15, 2026
diff --git a/llmdoc/app-runtime/host-neutral-assembly.mdx b/llmdoc/app-runtime/host-neutral-assembly.mdx
@@ -8,6 +8,7 @@ relations:
     - store/storage-backends.mdx
 code:
   paths:
+    - packages/app/src/index.ts
     - packages/app/src/deps.ts
     - packages/app/src/bootstrap.ts
     - packages/app/src/tbApp.ts

diff --git a/llmdoc/app-runtime/mcp-interop.mdx b/llmdoc/app-runtime/mcp-interop.mdx
@@ -17,6 +17,7 @@ code:
     - packages/app/src/routes/mcp.ts
     - packages/app/test/mcp.integration.test.ts
     - packages/app/test/mcpArguments.test.ts
+    - packages/app/test/contracts/processSessionCoverage.test.ts
     - scripts/verify-mcp.ts
 ---
 
@@ -103,6 +104,12 @@ gateway 明确判断 `not_dispatched` 时入队；设备业务错误属于 compl
    进入 tb_call 的闭环；窄 SK 仍看到固定入口，但发现隐藏越权目标、已知越权路径调用被拒。
 4. 真实上游仅在明确提供 URL/凭据时运行 `pnpm verify:mcp`。
 
+多入口共用 handler 不保证输入契约等价：Zod 默认值或 transform 可能使生成的 JSON Schema 描述输出，
+而 HTTP handler 接受的是输入；MCP 的 schema 前置校验会在到达 handler 前拒绝原本合法的省略字段。
+对含默认/可选参数的公开能力，用同一最小有效输入经真实 HTTP 与 MCP client 调用，覆盖空对象或仅必填字段；
+Help/schema 相同和 output 校验都不能替代这一步，也不能靠测试补齐可选值掩盖入口差异。修复须明确 input
+schema 与 handler 默认行为各自的职责，不要求一律禁用 default，也不将局部 optional 修复宣称为全仓生成器修复。
+
 排查连接先区分入站 `/~mcp` 与出站 MCP provider。CLI 经 HTBP 调用上游成功不能替代入站消费者验证；
 官方 SDK 成功也不能证明尚未复现的用户客户端链路兼容。验收还须证明工具目录规模有界、入口发现不访问
 上游、无关上游故障与 schema 错误被隔离，以及设备 delivery/operation 与原生 MCP 结果语义完整。

diff --git a/llmdoc/architecture.mdx b/llmdoc/architecture.mdx
@@ -6,6 +6,7 @@ relations:
     - hosts-deploy/managed-configuration.mdx
     - protocol/htbp-contract.mdx
     - protocol/security-boundaries.mdx
+    - device/process-sessions.mdx
 code:
   paths:
     - package.json
@@ -50,10 +51,11 @@ sdk (根入口 Node 22+;./client、./store、./device 为 neutral 子入口)
 CLI / Dashboard ──> sdk neutral entries ──HTTP──> app contract
 ```
 
-- `core`:类型、授权、树、store、builtin 纯逻辑、plugin/search 协议，以及 Store/Mailbox 的领域契约与 durable device 状态机；固定控制面 Zod wire/OpenAPI 与 HTBP 命令注册表也在此维护,不碰网络、环境变量、运行时资源。
+- `core`:类型、授权、树、store、builtin 纯逻辑、plugin/search 协议，以及 Store/Mailbox 的领域契约与 durable device 状态机；固定控制面 Zod wire/OpenAPI 与 HTBP 命令注册表也在此维护。根/neutral 契约不碰网络、环境变量、运行时资源；`core/node` 单独承载 Node 驱动和设备进程执行，不能沿 portable 导出泄漏。
 - `app`:Hono 路由、发现/调用、provider 编排、宿主注入面;不包含数据库驱动、S3 SDK 或专属启动。
 - `server` 装配 PG 领域仓库、官方 S3 SDK、Node WebSocket、bootstrap 和受管理维护；业务路由与协议语义仍归 app/core。
 - `sdk`:根入口嵌入 app 并以 Node ws 反向连接;`./client`、`./store`、`./device` 是面向 Web 标准宿主的 neutral 产物,不得反向触达 app、Node ws、`node:*` 或根入口。三个子入口的 HTTP 底层共用 `shared/transport.ts`:它是 TBError body、非规范错误体的 status fallback、credential header 与 timeout 边界的单一权威，各 client 只保留自己的上下文措辞和脱敏策略。`./client` 另是 builtin/system 管理视图类型、`ACTIONS` 与 presence 派生的 public consumer 出口；真源仍在 private core，公开消费者不应手抄。`./device` 同时提供实时 supervisor 与显式 pull-only Mailbox processor，后者要求宿主注入 durable journal；CLI/Dashboard 对固定控制面、Store 与设备连接的复用都应停在这些子入口。
+- neutral SDK 的公开 runtime validator 使用只含 `parse/safeParse` 和业务结果类型的结构接口；内部可复用 core schema，但不能直接导出 Zod 实例而把验证器实现类型带入消费方 `.d.ts`。进程会话的 parser 边界见 [进程会话](device/process-sessions.mdx)。
 - `plugin-sdk`:descriptor、OperationRegistry、envelope、受控出站;`plugins`:内置 provider 源码 + 生成 catalog + 迁移闸门。
 - `cli`:严格 argv 与脚本输出,不是服务端唯一校验层;`dashboard`:消费同一 HTTP 契约,不 import core。
 - `core` 与 `plugins` 是 private workspace 包,其余六个是 public artifact;发布判断按 artifact ownership,不沿依赖图机械 bump。

diff --git a/llmdoc/cli/agent-skill-integration.mdx b/llmdoc/cli/agent-skill-integration.mdx
@@ -69,6 +69,12 @@ Mailbox 使用 `operation` 中的 `deviceId`、`operationId` 与 `state`，不
 用户目标当下确实需要状态/终态时，按需做一次 `tb device op get <deviceId> <operationId>`。后续
 claim/complete 是设备侧协议，不计入 Agent 工具调用预算，也不由 Agent 模拟。
 
+设备根 Help 的 deviceContext 是最后一次 hello 自报环境，需连同 reportedAt/presence 判断新鲜度，不为确认
+平台先执行 shell 探测，也不把该摘要当成实时状态或授权依据。显式广告的进程会话用
+`tb device session start/list/observe/stop`；网络重连可继续观察，daemon 重启使旧会话失效。start 结果未知时
+按 requestId 查原会话，不盲目重新启动；取消 observe 不停止进程。它与上面的 Mailbox 恢复和默认不轮询
+规则有独立生命周期，详见 [进程会话](../device/process-sessions.mdx)。
+
 调用结果若含 `store://default/...`，它只是对象身份,不是访问凭证：Agent 用 `tb store stat/get` 读取当前 owner 的对象，
 只有用户明确要求把文件交给外部受众时才用 `tb store share` 创建短期 bearer，并把成功输出当 secret
 立即交付；用完可 `revoke-share`。普通设备产物不要求搜索或挂载 Context。需要 author 命名语义 entry

diff --git a/llmdoc/cli/argument-contract.mdx b/llmdoc/cli/argument-contract.mdx
@@ -110,6 +110,11 @@ CLI 是公共控制面,不是 API 的宽松包装。修改命令时同时检查
   `--path-prefix` 与 repeatable `--effect` 必须原样下发 SDK wire；CLI 只做非法枚举/组合的早拒，不能
   自己重排或过滤服务端结果。partial source 状态写 stderr warning，JSON page 保持机器可读。
 
+进程会话另用 `tb device session start/list/observe/stop` 消费普通 realtime command：start 包装绑定 input，
+以设备 list 返回的 runtimeId/时间建立接收窗口；丢响应保留 requestId，observe --follow 的中断只退出观察。
+它不复用 `tb device op` 的 durable operation 身份，也不是 `tb daemon logs` 的服务日志；完整边界见
+[Device 进程会话](../device/process-sessions.mdx)。
+
 ## 返回语义
 
 CLI 输出只能声明当前证据能证明的结果。人类文本与 JSON 必须同义，区分请求成功、业务终态和结果未知；

diff --git a/llmdoc/dashboard/canvas-architecture.mdx b/llmdoc/dashboard/canvas-architecture.mdx
@@ -99,10 +99,11 @@ Dashboard 是纯 HTTP 客户端,不 import core。固定控制面 wire 类型与
 - `lib/api.ts`:profile/session 到 `@tool-bridge/sdk/client` 的 browser 适配、Dashboard API error 桥接，以及尚未进入固定 client 的动态 HTTP 能力。通用 URL、timeout、错误 body 与固定响应校验不在此重写。
 - `lib/queries.ts`:TanStack Query key、分页、mutation 与失效。
 - `lib/session*`:profile、认证、连接上下文。
-- `WorkspaceShell`:统一导航、连接上下文、全局搜索与添加工具入口；工作台优先呈现日常使用入口，实例管理保留独立导航。`WorkspacePage` 承接本机收藏与最近使用，`ToolsPage` 按当前目录加载一层可见树和 owner help，避免为了列表预取全部远端命令；`ToolPage` 只定位命令，调用逻辑复用 `CmdPanel`。
+- `WorkspaceShell`:统一导航、连接上下文、全局搜索与添加工具入口；工作台优先呈现日常使用入口，实例管理保留独立导航。`WorkspacePage` 承接本机收藏与最近使用，`ToolsPage` 按当前目录加载一层可见树和 owner help，避免为了列表预取全部远端命令；`ToolPage` 定位命令，普通调用复用 `CmdPanel`；满足完整进程会话契约的节点复用 `DeviceSessionPanel`。
 - `canvas/`:能力树与节点检查。`CanvasPage`(`/canvas` 与兼容 `/nodes/*`:左画布 + 右 Inspector 抽屉,选中态由 URL 驱动)、`TreeCanvas`(React Flow 渲染)、`NodeInspector`(选中节点后右侧滑出,原样复用 node 子组件)。`treeGraph.ts` / `useCanvasTree.ts` 是无 DOM 的纯逻辑(工作树→图布局、展开集合、按需懒加载合并),性能边界:root depth=1、本地 lazy=1、remote lazy=3。
 - 节点动作 ownership:`CanvasNode` 只展示并上报语义动作,`TreeCanvas` 编排展开、懒加载与选中,`CanvasPage` 持有挂载/卸载 mutation 及确认交互;可操作性在图 view model 层统一派生。
 - `components/node/`:Inspector 内的节点子组件。`CommandWorkspace`(命令目录，选择命令进入独立调用页；旧节点深链接仍可自动打开 Dialog)、`CmdPanel`(单条 cmd 的 accordion / dialog / page 三种展示，共用表单、确认与执行)、`ResultView`、`CliHint`、反馈与 note。`CmdPanel`、实际 `invoke` 与 `CliHint` 共同信任 owner `~help` 返回的 `cmds[].path`——它已是含命令叶子的完整直连路径,除前导斜杠规范化外必须原样传递:不得用 owner path + `cmd.name` 重建、不得另传 `tool`、不得把 body 包成信封。设备 command metadata 的 `delivery` 只决定可选 policy；CmdPanel、SDK invoke 与 CliHint 统一在同一次普通 POST / `tb call` 中加入顶层 `~delivery`，不生成第二个 enqueue URL。
+- `DeviceSessionPanel` 是进程会话的消费者，`ToolPage` 与 `CommandWorkspace` 共用，不能只凭 start/stop 名称猜测能力。`useProcessSessionCommands` 先从无 schema 的 index 筛选四命令候选，再按需获取 start Help 并仅合并同 name/path 的 inputSchema；保留 index 的 identity/effect/confirm，不全局展开 schema。必填 runtime marker 确认后才显示面板，详情失败不能靠名称猜测。取消观察或卸载页面只 abort 读取，不隐式 stop；启动结果未知时保留 requestId，日志按字节 cursor 续读并显示 gap。发现测试须通过真实 SDK parser 覆盖 schema-free index → 单命令详情，不能只注入 full Help。设备侧身份、终态与跨入口验收归 [进程会话](../device/process-sessions.mdx)。
 - `components/add-tool/`:「添加工具」向导,通过受控 open/onOpenChange 供全局入口复用，也支持自带 trigger，按来源分流;不重复造挂载逻辑,内置集成走 `buildIntegrationCalls`、自定义 kind 走 `buildRegistryMountCalls`。`mountDiagnostics.ts` 把真实 `system/registry write` 的失败按 TBError code 归类,不另起与真实挂载不一致的 dry-run 探测。真正的 secret→registry→条件回滚链由 `pages/system/forms/mountOrchestration.ts` 单点持有，`useMountRunner`、`MountDialog` 与 `IntegrationDialog` 只负责表单/交互适配。
 - `pages/system/`:SK、secret、registry、plugin、catalog、federation、annotation。`pages/system/forms/`:将表单状态编译成 wire payload 的纯函数。
 - `pages/SearchPage.tsx` 通过 SDK fixed wire 执行 compact search，展示 coverage、effect、source 与 partial

diff --git a/llmdoc/device/device-daemon.mdx b/llmdoc/device/device-daemon.mdx
@@ -25,8 +25,9 @@ code:
 
 - 以实际运行设备连接的普通 Linux 用户执行;禁止 `sudo tb daemon ...` 或 root 用户。
 - 先准备只允许目标设备路径 `register` 的最小权限 Device SK;不要复用 Admin SK。
-- `install` 与前台 `tb connect` 共用网关、设备、shell、文件系统和 structured command profile 暴露参数(解析在 `commands/connect.ts`)。Shell 默认不允许命令,只有显式 `--allow` 的命令可执行。
-- `--allow '*'` 会按该 Linux 用户的权限开放任意远程 shell 命令。交互终端必须二次确认;非交互环境必须显式传 `--yes`。
+- `install` 与前台 `tb connect` 共用网关、设备、shell、文件系统和 structured command profile 与显式进程会话暴露参数(解析在 `commands/connect.ts`)。Shell 默认不允许命令,只有显式 `--allow` 的命令可执行。
+- **升级行为变化**：受限 `--allow` 现在拒绝任何含 LF/CR 的命令，包括引号内换行；同步 shell 和显式 shell session 均在 spawn 前检查。此前可通过换行追加第二条命令的输入不再被接受。
+- `--allow '*'` 仍允许含换行的复合命令，会按该 Linux 用户的权限开放任意远程 shell 命令。交互终端必须二次确认;非交互环境必须显式传 `--yes`。
 - 可重复 `--command-profile <file>` 暴露预声明的结构化命令;优先配合 `--no-shell` 只开放所需操作。profile 是 strict JSON,设备所有者必须为每条命令固定 executable、argv 模板并显式声明 `read | write | destructive` effect;平台不从命令文本推断安全等级。
 
 ## 安装或更新
@@ -55,6 +56,17 @@ choice、flag、required/multiple,并限制 `cwd`、`timeoutMs`、`maxOutputByte
 
 重复执行 `install` 是更新操作:即使服务已经 active 也会 restart,让新配置立即生效。安装、启动或等待 ready 失败时,恢复安装前的配置、状态和 unit;此前已有服务时还会尝试恢复旧服务。
 
+## 进程会话生命周期
+
+profile 的单条 `commands[].session` 或 shell 的 `--shell-session-path` 显式启用长命令会话，具体配置与
+恢复边界见 [Device 进程会话](process-sessions.mdx)。两者与 profile 一起冻结在 daemon 配置中；会话路径
+冲突必须同时通过安装解析和运行时装配校验，不能只信任配置来源。
+
+会话 manager 归一次 deviceRuntime 所有，重连不重建、不因单次 call 或 observe 被取消而停止 child。
+永久 close、连接初始化失败和正常进程退出统一等待 manager 清理，清理失败必须暴露；daemon restart
+生成新 runtime，旧会话和日志不可恢复。systemd unit 明确使用 control-group、停止时限与最终 SIGKILL
+兜底，设备进程内的 stop/timeout 仍独立完成进程组清理，不能靠 unit 配置替代运行时状态机。
+
 ## Mailbox 消费生命周期
 
 `tb connect` 与 daemon 共用 `deviceRuntime` adapter。Device SDK 的 Mailbox processor 不自启；CLI 只在