@tencent-ai/agent-harness 0.2.0-beta.10 → 0.2.0-beta.11

package/cli/product.selfhosted.json

@@ -1 +1 @@
-{"agents":[{"name":"cli","instructions":"cli-agent-prompt","description":"cli agent","models":["codewise-chat"],"modelTags":["craft"],"commands":["init","compact","statusline","insights"],"tools":["Agent","Read","Write","Edit","Bash","PowerShell","Glob","Grep","EnterPlanMode","ExitPlanMode","TaskCreate","TaskGet","TaskUpdate","TaskList","WebFetch","WebSearch","TaskStop","TaskOutput","Skill","AskUserQuestion","AskUserForStructuredInput","StructuredOutput","ToolSearch","DeferExecuteTool","SendMessage","SendUserMessage","TeamCreate","TeamDelete","NotebookEdit","LSP","EnterWorktree","LeaveWorktree","CronCreate","CronDelete","CronList","DelegateTool","WeChatReply","WeComReply","PushNotification","ReportFindings","ComputerUse","ListMcpResources","ReadMcpResource","WaitForMcpServers","Workflow","Monitor","REPL","A2AGetAgentCard","A2ASendMessage","A2AGetTask","A2ACancelTask"],"tags":["cli","default","model:craft"]},{"name":"general-purpose","instructions":"cli-agent-prompt","description":"general-purpose agent","tools":["Read","Write","Edit","Bash","PowerShell","Glob","Grep","TaskCreate","TaskGet","TaskUpdate","TaskList","WebFetch","WebSearch","TaskStop","TaskOutput","Skill","AskUserQuestion","AskUserForStructuredInput","ToolSearch","DeferExecuteTool","StructuredOutput","SendMessage","SendUserMessage","NotebookEdit","LSP","ComputerUse","ImageGen","ImageEdit","Artifact","ArtifactControl","ListMcpResources","ReadMcpResource","WaitForMcpServers","REPL"],"tags":["cli","general-purpose"]},{"name":"compact","instructions":"compact-agent-prompt","description":"compact agent","tools":["Read"],"commands":["_compact"],"tags":["cli","compact"]},{"name":"contextSummary","instructions":"context-summary-agent-prompt","description":"Context summary agent for conversation compaction and max-token recovery","tools":[],"tags":["cli","contextSummary"]},{"name":"contentAnalyzer","instructions":"content-analyzer-agent-instructions","description":"content analyzer agent","tags":["cli","content-analyzer"],"tools":[]},{"name":"terminalTitleGenerator","instructions":"terminal-title-generator-instructions","description":"Generate terminal window titles from conversation topics.","tags":["cli","terminal-title-generator"],"tools":[]},{"name":"promptSuggestion","instructions":"prompt-suggestion-instructions","description":"Suggest the user's next prompt after a conversation turn.","tags":["cli","prompt-suggestion"],"tools":[]},{"name":"memorySelector","instructions":"memory-selector-instructions","description":"Select relevant memories for the current query.","models":["lite"],"tags":["cli","memory-selector"],"tools":[]},{"name":"summaryGenerator","instructions":"summary-generator-instructions","description":"Generate session summaries from conversation content.","tags":["cli","summary-generator"],"tools":[]},{"name":"securityReviewer","instructions":"security-reviewer-instructions","description":"Review bounded security decisions without tools.","models":["lite"],"tags":["cli","security-reviewer"],"tools":[]},{"name":"autoModeClassifier","instructions":"auto-mode-classifier-instructions","description":"Classify auto mode tool permission risk.","models":["lite"],"tags":["cli","auto-mode-classifier"],"tools":[]},{"name":"promptHookEvaluator","instructions":"prompt-hook-evaluator-instructions","description":"Evaluates prompt hooks using LLM to determine if conditions are met","models":["lite"],"tags":["cli","prompt-hook-evaluator"],"tools":[]},{"name":"insightsAnalyzer","instructions":"base-agent-instructions","description":"Analyzes user usage data facets for the /insights command","tags":["cli","insights-analyzer"],"tools":[]},{"name":"agentInstructions","instructions":"agent-instructions","description":"generating agent instructions","tags":["cli","agent-instructions"],"tools":[]},{"name":"statusline-setup","instructions":"agent-statusline-instructions","description":"Use this agent to configure the user's Codebuddy Code status line setting.","tools":["Read","Write","Edit","ToolSearch","DeferExecuteTool"],"asTool":true,"tags":["cli","sub-agent"]},{"name":"Explore","instructions":"agent-explore-instructions","description":"Fast agent specialized for exploring codebases. Use this when you need to quickly find files by patterns (eg. \"src/components/**/*.tsx\"), search code for keywords (eg. \"API endpoints\"), or answer questions about the codebase (eg. \"how do API endpoints work?\"). When calling this agent, specify the desired thoroughness level: \"quick\" for basic searches, \"medium\" for moderate exploration, or \"very thorough\" for comprehensive analysis across multiple locations and naming conventions.","models":["lite"],"tools":["Read","Bash","PowerShell","Glob","Grep","TaskCreate","TaskGet","TaskUpdate","TaskList","WebFetch","WebSearch","Skill","SendMessage","SendUserMessage","ToolSearch","DeferExecuteTool"],"asTool":true,"tags":["cli","sub-agent"]},{"name":"Plan","instructions":"agent-plan-instructions","description":"Software architect agent for designing implementation plans. Use this when you need to plan the implementation strategy for a multi-step task before writing code. Returns step-by-step plans, identifies critical files, and considers architectural trade-offs. Read-only: it designs but does not modify files or exit plan mode; the caller reviews the plan and implements it.","tools":["Read","Bash","PowerShell","Glob","Grep","TaskCreate","TaskGet","TaskUpdate","TaskList","WebFetch","WebSearch","Skill","ToolSearch","DeferExecuteTool","TeamCreate","TeamDelete","SendMessage","SendUserMessage"],"asTool":true,"tags":["cli","sub-agent"]}],"models":[{"credits":"x0.01 credits","id":"codewise-chat","name":"Codewise-Chat","vendor":"tencent","maxOutputTokens":8192,"maxInputTokens":128000,"supportsToolCall":true,"supportsImages":false,"disabledMultimodal":true,"maxAllowedSize":56000}],"links":{"officialWebsite":"https://copilot.tencent.com/cli","helpDocument":"https://copilot.tencent.com/docs/cli","issueFeedback":"https://cnb.cool/codebuddy/codebuddy-code/-/issues","issueCreation":"https://cnb.cool/codebuddy/codebuddy-code/-/issues/new","mcpHelpDocument":"https://copilot.tencent.com/docs/cli/mcp","hooksHelpDocument":"https://copilot.tencent.com/docs/cli/hooks","sandboxHelpDocument":"https://copilot.tencent.com/docs/cli/bash-sandboxing","upgradeUrl":""},"productFeatures":{"BillingNotice":false,"ShareLink":true,"Artifact":true,"CodeAdoptionRate":false,"CloudAgentsSmartMerge":true,"CustomModelsJSON":true,"CustomModelIdPrefix":true,"DeferToolLoading":true,"ScheduledTasks":true,"SkipToolCallSupportCheck":true},"commit":"aa90dfd60b848dce5150a7ed1913a2637f12e431","date":"2026-10-08T11:41:58.472Z"}
+{"agents":[{"name":"cli","instructions":"cli-agent-prompt","description":"cli agent","models":["codewise-chat"],"modelTags":["craft"],"commands":["init","compact","statusline","insights"],"tools":["Agent","Read","Write","Edit","Bash","PowerShell","Glob","Grep","EnterPlanMode","ExitPlanMode","TaskCreate","TaskGet","TaskUpdate","TaskList","WebFetch","WebSearch","TaskStop","TaskOutput","Skill","AskUserQuestion","AskUserForStructuredInput","StructuredOutput","ToolSearch","DeferExecuteTool","SendMessage","SendUserMessage","TeamCreate","TeamDelete","NotebookEdit","LSP","EnterWorktree","LeaveWorktree","CronCreate","CronDelete","CronList","DelegateTool","WeChatReply","WeComReply","PushNotification","ReportFindings","ComputerUse","ListMcpResources","ReadMcpResource","WaitForMcpServers","Workflow","Monitor","REPL","A2AGetAgentCard","A2ASendMessage","A2AGetTask","A2ACancelTask"],"tags":["cli","default","model:craft"]},{"name":"general-purpose","instructions":"cli-agent-prompt","description":"general-purpose agent","tools":["Read","Write","Edit","Bash","PowerShell","Glob","Grep","TaskCreate","TaskGet","TaskUpdate","TaskList","WebFetch","WebSearch","TaskStop","TaskOutput","Skill","AskUserQuestion","AskUserForStructuredInput","ToolSearch","DeferExecuteTool","StructuredOutput","SendMessage","SendUserMessage","NotebookEdit","LSP","ComputerUse","ImageGen","ImageEdit","Artifact","ArtifactControl","ListMcpResources","ReadMcpResource","WaitForMcpServers","REPL"],"tags":["cli","general-purpose"]},{"name":"compact","instructions":"compact-agent-prompt","description":"compact agent","tools":["Read"],"commands":["_compact"],"tags":["cli","compact"]},{"name":"contextSummary","instructions":"context-summary-agent-prompt","description":"Context summary agent for conversation compaction and max-token recovery","tools":[],"tags":["cli","contextSummary"]},{"name":"contentAnalyzer","instructions":"content-analyzer-agent-instructions","description":"content analyzer agent","tags":["cli","content-analyzer"],"tools":[]},{"name":"terminalTitleGenerator","instructions":"terminal-title-generator-instructions","description":"Generate terminal window titles from conversation topics.","tags":["cli","terminal-title-generator"],"tools":[]},{"name":"promptSuggestion","instructions":"prompt-suggestion-instructions","description":"Suggest the user's next prompt after a conversation turn.","tags":["cli","prompt-suggestion"],"tools":[]},{"name":"memorySelector","instructions":"memory-selector-instructions","description":"Select relevant memories for the current query.","models":["lite"],"tags":["cli","memory-selector"],"tools":[]},{"name":"summaryGenerator","instructions":"summary-generator-instructions","description":"Generate session summaries from conversation content.","tags":["cli","summary-generator"],"tools":[]},{"name":"securityReviewer","instructions":"security-reviewer-instructions","description":"Review bounded security decisions without tools.","models":["lite"],"tags":["cli","security-reviewer"],"tools":[]},{"name":"autoModeClassifier","instructions":"auto-mode-classifier-instructions","description":"Classify auto mode tool permission risk.","models":["lite"],"tags":["cli","auto-mode-classifier"],"tools":[]},{"name":"promptHookEvaluator","instructions":"prompt-hook-evaluator-instructions","description":"Evaluates prompt hooks using LLM to determine if conditions are met","models":["lite"],"tags":["cli","prompt-hook-evaluator"],"tools":[]},{"name":"insightsAnalyzer","instructions":"base-agent-instructions","description":"Analyzes user usage data facets for the /insights command","tags":["cli","insights-analyzer"],"tools":[]},{"name":"agentInstructions","instructions":"agent-instructions","description":"generating agent instructions","tags":["cli","agent-instructions"],"tools":[]},{"name":"statusline-setup","instructions":"agent-statusline-instructions","description":"Use this agent to configure the user's Codebuddy Code status line setting.","tools":["Read","Write","Edit","ToolSearch","DeferExecuteTool"],"asTool":true,"tags":["cli","sub-agent"]},{"name":"Explore","instructions":"agent-explore-instructions","description":"Fast agent specialized for exploring codebases. Use this when you need to quickly find files by patterns (eg. \"src/components/**/*.tsx\"), search code for keywords (eg. \"API endpoints\"), or answer questions about the codebase (eg. \"how do API endpoints work?\"). When calling this agent, specify the desired thoroughness level: \"quick\" for basic searches, \"medium\" for moderate exploration, or \"very thorough\" for comprehensive analysis across multiple locations and naming conventions.","models":["lite"],"tools":["Read","Bash","PowerShell","Glob","Grep","TaskCreate","TaskGet","TaskUpdate","TaskList","WebFetch","WebSearch","Skill","SendMessage","SendUserMessage","ToolSearch","DeferExecuteTool"],"asTool":true,"tags":["cli","sub-agent"]},{"name":"Plan","instructions":"agent-plan-instructions","description":"Software architect agent for designing implementation plans. Use this when you need to plan the implementation strategy for a multi-step task before writing code. Returns step-by-step plans, identifies critical files, and considers architectural trade-offs. Read-only: it designs but does not modify files or exit plan mode; the caller reviews the plan and implements it.","tools":["Read","Bash","PowerShell","Glob","Grep","TaskCreate","TaskGet","TaskUpdate","TaskList","WebFetch","WebSearch","Skill","ToolSearch","DeferExecuteTool","TeamCreate","TeamDelete","SendMessage","SendUserMessage"],"asTool":true,"tags":["cli","sub-agent"]}],"models":[{"credits":"x0.01 credits","id":"codewise-chat","name":"Codewise-Chat","vendor":"tencent","maxOutputTokens":8192,"maxInputTokens":128000,"supportsToolCall":true,"supportsImages":false,"disabledMultimodal":true,"maxAllowedSize":56000}],"links":{"officialWebsite":"https://copilot.tencent.com/cli","helpDocument":"https://copilot.tencent.com/docs/cli","issueFeedback":"https://cnb.cool/codebuddy/codebuddy-code/-/issues","issueCreation":"https://cnb.cool/codebuddy/codebuddy-code/-/issues/new","mcpHelpDocument":"https://copilot.tencent.com/docs/cli/mcp","hooksHelpDocument":"https://copilot.tencent.com/docs/cli/hooks","sandboxHelpDocument":"https://copilot.tencent.com/docs/cli/bash-sandboxing","upgradeUrl":""},"productFeatures":{"BillingNotice":false,"ShareLink":true,"Artifact":true,"CodeAdoptionRate":false,"CloudAgentsSmartMerge":true,"CustomModelsJSON":true,"CustomModelIdPrefix":true,"DeferToolLoading":true,"ScheduledTasks":true,"SkipToolCallSupportCheck":true},"commit":"583bb99e203fbbef3a2e42f36218688425e73bec","date":"2026-10-09T05:12:12.150Z"}

package/cli/vendor/shim/node-safe-delete-shim.cjs

@@ -196,13 +196,13 @@ function shouldBypassSafeDelete(absPath) {
         || isPnpmVirtualStorePath(absPath);
 }
 
-function recordTrash(absPath) {
+function recordReport(operation, absPath) {
     if (!REPORT_PATH) return;
     try {
         fs.appendFileSync(
             REPORT_PATH,
             JSON.stringify({
-                operation: 'trash',
+                operation,
                 runtime: 'node',
                 path: absPath,
                 timestamp: Date.now(),
@@ -602,8 +602,25 @@ function tryTrash(absPath, opts) {
         throw new Error(`[safe-delete] broker denied delete: path=${absPath}`);
     }
 
+    // Windows 沙箱且开启文件备份：普通文件交给 tsbx+Center 决定是否进回收站（本轮新建的
+    // 直接删）。原生删除失败（如 Center 拒绝）时继续走 genie-trash，保留审批与 fail-closed。
+    if (PLATFORM === 'win32'
+        && process.env.CODEBUDDY_SAFE_DELETE_SANDBOX === '1'
+        && process.env.CODEBUDDY_FILE_BACKUP_ENABLED === '1') {
+        const st = safeLstat(absPath);
+        if (st && st.isFile()) {
+            try {
+                origUnlinkSync(absPath);
+                recordReport('native-delete', absPath);
+                return true;
+            } catch (_) {
+                // 继续走 genie-trash
+            }
+        }
+    }
+
     trashItem(absPath);
-    recordTrash(absPath);
+    recordReport('trash', absPath);
     return true;
 }
 

package/cli/vendor/shim/sitecustomize.py

@@ -824,13 +824,13 @@ if _SESSION_ID:
 
     _os_tmp_dirs = _build_os_tmp_dirs()
 
-    def _record_trash(abs_path):
+    def _record_report(operation, abs_path):
         if not _report_path:
             return
         try:
             with _orig_builtin_open(_report_path, "a", encoding="utf-8") as f:
                 f.write(json.dumps({
-                    "operation": "trash",
+                    "operation": operation,
                     "runtime": "python",
                     "path": abs_path,
                     "timestamp": int(time.time() * 1000),
@@ -998,15 +998,28 @@ if _SESSION_ID:
                 "[safe-delete] broker denied delete: path=%s" % abs_path
             )
 
+        # Windows 沙箱且开启文件备份：普通文件交给 tsbx+Center 决定是否进回收站（本轮新建的
+        # 直接删）。原生删除失败（如 Center 拒绝）时继续走 genie-trash，保留审批与 fail-closed。
+        if sys.platform == "win32" and _IN_SANDBOX \
+                and os.environ.get("CODEBUDDY_FILE_BACKUP_ENABLED") == "1":
+            st = _safe_lstat(abs_path)
+            if st and stat.S_ISREG(st.st_mode):
+                try:
+                    _orig_unlink(abs_path)
+                    _record_report("native-delete", abs_path)
+                    return True
+                except OSError:
+                    pass
+
         try:
             if _try_trash_via_binary(abs_path):
-                _record_trash(abs_path)
+                _record_report("trash", abs_path)
                 return True
             _platform_trash(abs_path)
         except Exception as e:
             _emit_safe_delete_fail_closed(abs_path, "trash-failed", str(e))
             raise
-        _record_trash(abs_path)
+        _record_report("trash", abs_path)
         return True
 
     def _safe_lstat(abs_path):

package/docs/acp-v2.md

@@ -449,6 +449,21 @@ head：
 两种操作都只修改 conversation history，不会恢复文件、Git、terminal、tool side effect、
 credential、config 或 MCP state。
 
+Fork 保留选定历史中的工具结果。已完成的普通 attached Subagent 历史会复制并重分配身份；
+background、仍为 running 的历史快照以及 Agent Teams 的运行关系不复制，新会话不会自动
+续跑这些任务，也不会订阅原团队的消息。原会话继续拥有自己的任务。历史文本可以提及原任务 ID，
+但这些条目不再携带新会话的 `subAgent` 关系，不出现在新会话的 `subagent/list` 中。
+这不回滚工具已经产生的外部副作用。
+
+Harness 默认不再以 32 个已挂载会话限制 `new` / `resume` / `fork`。需要驻留预算时，可设置
+`createHarness({ maxActiveSessions: 64 })` 或独立进程的 `--max-active-sessions 64`；
+预算包含已挂载的空闲会话，`session/close` 释放名额。它与持久化会话总数、并发执行数、
+transport 的连接限制及单次 fork 的历史复制预算相互独立。
+
+历史不完整或引用损坏返回 `SESSION_HISTORY_INVALID`，复制预算超限返回
+`SESSION_FORK_TOO_LARGE`，无效 turn cursor 仍返回 `SESSION_TURN_CURSOR_NOT_FOUND`。
+详细内部路径仅写入诊断日志，错误响应不回显。
+
 ### 文件 checkpoint
 
 Harness v1 用同一个 root `user_message.messageId` 提供独立的文件恢复面；它不引入
@@ -475,6 +490,9 @@ Harness v1 用同一个 root `user_message.messageId` 提供独立的文件恢
 `checkpoint/list` 只列出已记录 Agent 文件 checkpoint 的 canonical root user
 message 锚点，并按 conversation 从旧到新排列。List 不读取文件快照；
 快照是否仍可用由后续 `checkpoint/read` 或 `checkpoint/restore` 校验。
+列表不附加 `hasFileChanges` / `changedFileCount`。按本轮变更筛选的客户端可复用
+live / replay 的工具结果，见[客户端筛选说明](client.md#筛选文件恢复锚点)；没有完整证据的
+轮次应保留，不能把未加载或缺失记录当成无变更。
 
 `checkpoint/read` 返回当前 workspace 回到该消息之前状态时会发生的
 累计 ACP v2 `Diff`；它不是该 turn 自身的增量：
@@ -531,8 +549,9 @@ message 锚点，并按 conversation 从旧到新排列。List 不读取文件
 `session/resume`（`replayFrom: { "type": "start" }`），不会因此再次恢复文件。
 
 冷恢复从 durable session 恢复 canonical cwd。未持久化的
-`additionalDirectories` / `addDir` 不会在重启后授予文件恢复权限；涉及这些目录的
-checkpoint 会在 cold `checkpoint/read` / `checkpoint/restore` 中 fail closed。
+`additionalDirectories` / `addDir` 不会在重启后授予文件恢复权限。历史中能够确认位于
+当前恢复范围之外的文件条目会被排除，既不出现在预览中，也不会阻断工作区内文件恢复；
+这些文件本身保持不变。无法安全解析的路径或无效快照仍拒绝恢复，不会放宽安全校验。
 
 ## 7. 反向交互与配置
 

package/docs/client.md

@@ -317,3 +317,47 @@ await client.session.prompt({ sessionId, prompt: [{ type: 'text', text: '从这
 `after` 保留该用户轮次，`before` 排除该轮次。游标使用根用户消息的 messageId，
 该轮的 steer 输入仍属于同一轮。回退会结束该会话的执行资源；下一次 prompt 从回退后的历史恢复。
 它只回退对话历史，文件恢复使用 checkpoint 接口。RPC 返回后不会自动重放历史。
+
+## 筛选文件恢复锚点
+
+`checkpoint/list` 返回文件恢复锚点，不提供每轮文件变更摘要。客户端可复用现有消息模型，
+从实时和历史回放中的 ACP 工具结果筛选“发生过文件变更的轮次”，无需逐个调用
+`checkpoint/read`。后者预览的是**当前工作区回到锚点之前**的累计变化，不能拿它判断该轮
+是否修改过文件；纯问答轮次也可能回退后面多轮产生的修改。
+
+在现有消息归并流程中处理这些证据：
+
+- 先按会话和 `toolCallId` 归并 `tool_call` / `tool_call_update`，再检查最终状态。
+  `status: 'completed'` 且 `diff.changes` 非空是已记录变更的证据；`patch: null`
+  不影响文件列表。预览以及失败、取消的工具结果不能当作已提交变更。
+- 按工具所属的根用户轮次归类，使用根 `user_message.messageId` 对应 checkpoint。
+  `codebuddy.ai/requestId` / `codebuddy.ai/rootRequestId` 可辅助关联执行事件，但不能替代
+  持久化的消息游标。steer 输入仍属于原轮次；不能简单归到最后到达的一条用户消息。
+- live 与回放使用同一套归并逻辑，重复事件不重复计数。同一路径在一轮中修改多次可以
+  去重，但这不代表最终净差异：改动后再改回的轮次仍然“发生过变更”。
+- 只有整轮已结束、历史完整且相关操作的变更记录完整时，才能确认“无变更”。未加载的
+  历史、仍在执行的轮次、缺少文件变更记录的旧历史，以及结果不完整的工具调用均保留为
+  “未知”。当前这套文件记录不覆盖任意 Bash / MCP 副作用，不能由无 `diff` 推导无变更。
+
+例如，下列状态由 Host 从**已有消息模型**计算，不是 Harness 的字段，也不需要另存一份历史：
+
+```ts
+// changeStateByRootMessageId 是 Host 派生的 Map：
+// 根 user messageId -> 'changed' | 'unchanged' | 'unknown'
+const { checkpoints } = await client.checkpoint.list({ sessionId });
+const visibleCheckpoints = checkpoints.filter(
+    ({ messageId }) => changeStateByRootMessageId.get(messageId) !== 'unchanged',
+);
+```
+
+未知条目暂时保留，可能显示少量没有变更的锚点，但不会因历史尚未加载而误隐藏。已加载
+的最后一轮可直接读取它自己的工具结果，不必等待下一轮生成 checkpoint。
+
+需要历史时，复用正常的 `session/resume` 回放：`replayFrom: { type: 'start' }` 为完整历史，
+`{ type: '_codebuddy.ai/turn', last: 20 }` 按轮分页。分页未加载到的轮次仍是未知；不要为每次
+打开恢复菜单重复 resume，它还涉及会话挂载和 MCP 配置。具体契约见
+[历史回放](acp-v2.md#5-resume-与-replay)及[文件 checkpoint](acp-v2.md#文件-checkpoint)。
+
+筛选仅决定列表展示，不授予文件恢复权限。用户选中锚点后仍调用 `checkpoint/read`，由
+Server 按 canonical workspace 和有效的附加目录生成预览；确认后再调用
+`checkpoint/restore`。客户端用路径前缀过滤不能替代 Server 对符号链接和恢复范围的校验。

package/docs/errors.md

@@ -70,6 +70,7 @@ request；它们不属于下面的 prompt terminal `CodeBuddyError`：
 | `SESSION_CHECKPOINT_TOO_LARGE` | `checkpoint/list/read/restore` | Session history 超过安全检查预算，Server 未读取或修改文件 |
 | `SESSION_CWD_UNAVAILABLE` | `session/rewind`、`checkpoint/list/read/restore` | Durable session 没有可信的 canonical workspace；Server fail closed，不使用进程 cwd |
 | `SESSION_CHECKPOINT_RESTORE_FAILED` | `checkpoint/restore` | 一个或多个 tracked file 未能恢复；请求返回失败，但文件系统可能已经部分改变，Host 应重新调用 `checkpoint/read` 收敛 UI |
+| `SESSION_HISTORY_INVALID` | `session/fork`、`session/delete` | 持久化历史不完整或关系不一致；保留原历史，详细原因见服务端日志 |
 | `SESSION_FORK_TOO_LARGE` | `session/fork` | Session history 超过可安全复制的预算，未创建 fork |
 | `SESSION_REPLAY_TOO_LARGE` | `session/resume` | Session history 超过可安全 replay 的预算，未 attach |
 | `SESSION_REWIND_TOO_LARGE` | `session/rewind` | Session history 超过可安全修改的预算，未移动 conversation head |

package/docs/in-process.md

@@ -64,6 +64,7 @@ await harness.close();
 | `tools` | Host 的 `tool()` 定义数组，追加到默认内置工具。省略或 `[]` 均表示不注册 Host 工具；会话工具选择由插件 Agent 声明决定。 |
 | `hooks` | Functional hooks 的 `register(on, options)` 函数，每个 Harness 注册一次，见下文。 |
 | `mcp.toolsSyncTtlMs` | 工具目录的兜底刷新间隔，默认 15 分钟；`null` 关闭过期刷新，变更通知仍生效。 |
+| `maxActiveSessions` | 可选的已挂载会话数量预算，包含空闲会话，必须为正整数。默认不设固定数量上限；`session.close()` 释放名额，持久化历史保留。独立进程使用 `--max-active-sessions <count>`。 |
 | `strictMcpConfig` | 为 `true` 时只使用会话显式传入的 MCP；默认还发现用户和插件 MCP。 |
 | `telemetry` | Harness 的结构化日志 sink、队列和刷新设置；传入的 sink 由 Harness flush/close。Agent 内核日志在本地模式默认写入 `configDir/logs`，与此 sink 分开。 |
 | `signal` | Harness 的生命周期取消信号，覆盖创建和运行阶段。 |